[standards-jig] RFC draft 3.0

Iain Shigeoka iainshigeoka at yahoo.com
Thu Feb 14 20:05:41 UTC 2002


Hello,

A lot of these are nit picks but since you asked for it... :)  Sorry for not
chiming in earlier but I was busy on something else.  I also apologize since
I'm currently in the editing mode with other work so a lot of this is
non-technical (although since this should be final draft may be best to
fix.)

Overview

Is it normal to make the overview an exact copy of the abstract?

Section 1.2  

Paragraph following bullet list.  Last sentence.  Plural of URI is URIs not
URIS

Following paragraph, could you break up the sentences?  They're a bit
complex and difficult to follow.

Section 1.3

First paragraph, last sentence.  Mising "the": (most importantly the
DIALBACK PROTOCOL).  I'd also break up that sentence into two.  End at
October 2000.  It is the protocols...

Last paragraph.  Once again, long sentence.  Break it up.  I think at least
2 sentences.  In addition, you have an extra "for" in the middle:  ...to the
IETF both for to document...  Should read:  ...to the IETF both to
document...

I'm going to stop the grammar edits here.  If you find this helpful, I'll do
it, but I just realized there are many here and if you're going to have a
proofreader go over it there's no point in me wasting time and you wasting
bandwidth...

Section 2

Section 2 refers to, and defines its own terms in relation to words/entities
defined in Section 3.  Section 3 does not refer to anything in section 2.  I
think it would be clearer to put section 3 before section 2 so the reader
knows what "host", "node" etc mean in Jabber before their use in Section 2
to define the Jabber ID.

Section 2.1

IETF documents usually use a standard ABNF notation for data.  Perhaps the
Jabber ID should be given in that format rather than the ad hoc unix-ish one
used here.  I also don't know about saying the Jabber ID is "nearly
consistent with the URI spec."  If you are going to do so, you should state
how it differs.  Also since it doesn't follow exactly, you should at least
define the character set allowed etc.  I also think you should expand "spec"
to "specification."

The use of "node" is confusing in the second paragraph.  From the previous
paragraph it appears to refer to only the first part of the JID.  But the
second paragraph makes it sound like the node is actually the full address
(addressable node.) or an identifier for a host or even a connection.  Since
host and connection is not defined (nor is user) the second paragraph seems
more confusing than clarifying.  I think it may be better to simply
eliminate the second paragraph entirely.

Section 2.3

I think you should provide a formal ABNF definition for a node's acceptable
characters rather than a text description (or in addition to.)  The intent
of the RFC is to document a testable spec and ABNF helps to precisely define
data (you can generate parsers directly from ABNF.)

Section 2.4

Once again, a formal ABNF would be best.  If you provided the formal ABNF
for the Jabber ID in Section 2.1 you wouldn't need to create separate ones
for each subsection.  I also am very cautious about the sentence that
begins: All characters are allowed in a resource...  This would imply that
you could insert blank space, nulls, quotes, control characters, etc into a
resource string.  This could cause significant problems for most XML
parsers!  You also don't define the character set for a resource's
characters.  I think you could take care of all these issues using an ABNF.

Rather than say, "A resource may be understood to be similar to the path
part of a URL." how about just saying that is the common format and
interpretation: The most common format for resources follows the URL path
conventions (path names following the node data format separated by forward
slashes.)

Section 3.1 

I think the Connection Map would be clearer if N4 used another letter than
N.  Perhaps F for foreign.  Since you are differentiating S3 as a gateway (a
defined term) I think the key and perhaps the letter should indicate that it
is a gateway.

Section 3.2

I think it is important to somehow work in the concept of "user accounts"
and the fact that the host manages them.  At least mention it here.  The
host is not a pure router because of its user management duties (especially
presence/roster.)

Section 4.

I think it may be good to mention how Jabber entities are expected to deal
with other XML data such as processing instructions.  I see you have it in
5.3 but you may want to mention in here.

Section 5.3

States that XML chunks do not contain PI, etc.  However the stream is
outside of any chunk isn't it?  So does that mean PI coming between chunks
or at the opening of the connection (before the establishment of the stream)
is supported/required/rejected/ignored?  I think you should just say, Jabber
XML streams (or something like that) do not contain...

Section 5.4

from and id bullet.  Should specify the behavior of the receiver when it
does get a from/id attribute (it sends a <stream:error> and bails)

Xmlns bullet.  should specify the behavior of either party when it does get
an xmlns with value other than the acceptable ones.  Should provide a
reference to allowed namespaces.  Should specify behavior of parties if the
don't match.  Should specify who is responsible for detecting mismatched
namespaces...

Section 5.7

Shouldn't we have a DTD/schema for stream:error?  The example is also
malformed (no opening <stream:stream>.)  jabberd will spit out a
<stream:error> immediately without opening <stream:stream> on a bad opening
<stream:stream> so perhaps this is the behavior we want but it is bad XML.

Section 5.8

Perhaps the SEND/RECV should be NODE/HOST instead (it seems clearer.)

I think you also should include a full example of an error and use of the
<stream:error> packet.

Section 6

We see the specification of the responsibilities that the host must fulfill
spread out across the various element types.  However none of these are
mentioned in the definition of the host in section 2.  Perhaps they should
be distilled and mentioned there as well.

There are several places where you say something "must" contain some value.
For example, the show element must be away, chat, xa, or dnd.  In these
cases, you should specify what happens in the case of a violation (ignore,
error, etc.)  I would also suggest referring to, and using the IETF standard
nomenclature for words like MUST, SHOULD, etc and put them in all caps as
per that standard (sorry I don't have the RFC on hand)

The type attribute description for all of the elements uses words like "has
several preset values" or "values include" before the list of allowed
values.  However as I understand the standard, the type values MUST be one
of the given values (and the DTD backs this up.)  Can there be other values
for the type attribute that are not listed?  If so what are they or are we
free to invent anything we want?  What is the behavior of compliant
implementations when receiving a value not specified?  If not, use precise
language and state it MUST be one of the following.  The same problem exists
for 7.7.1 subscription values and the ask values and probably others.

Section 7

I'm wondering about the value of listing all of the semi-standard extensions
in section 7.  It's too sketchy to implement compliant support from most of
the descriptions alone.  Perhaps we should omit most/all of them and refer
to subsequent RFCs or other standards mechanisms (like the JEP site and
process) for documenting these extensions.  The intent of this RFC is
documenting Jabber and doesn't have to include all of the "application
layer" protocols in the same document.  There is enough to cover just on
Jabber for the RFC.

I'm also thinking that perhaps the whole security issue should be moved out
into its own RFC or other doc as well and just mentioned in this RFC.  There
is just so much information in here...  OTOH, I realize that this may be
just a way to "throw it all out there" in which case, this may be the best
way to go.  I suppose the question is whether this is an RFC for defining
implementation compliance or simply an FYI.

Sorry for the long list without any kudos.  I really like the RFC and
appreciate the work and many improvements to the Jabber documentation it
provides.  The fact that I point to these nit picks shows that most of the
fundamental issues are well documented.   Great job Peter!

-iain


_________________________________________________________
Do You Yahoo!?
Get your free @yahoo.com address at http://mail.yahoo.com




More information about the Standards mailing list