Subject: [apps-discuss] Apps-team review of draft-ietf-xcon-common-data-model-25.txt

From: Tim Bray <[email-masked]>
Date: Sat, 16 Apr 2011 10:29:12 -0700

I have been selected as the Applications Area Review Team reviewer for
this draft (for background on apps-review, please see
http://www.apps.ietf.org/content/applications-area-review-team).

I'm not a strong enough SIP expert to express an opinion as to whether
this is ready for publication in the sense of it being a useful and
problem-free extension of the SIP standards framework.  However, it
seems a reasonable specification of a reasonable XML language
extension and I didn't see anything obviously broken at the SIP level;
there are a few nits, noted below, that should be addressed:

Observation: Element names given in double quotes, attribute names in
single quotes.  Odd.  Is this a convention?

General issue: There is much discussion of the values of various
elements.  There seems little discussion of whether exact case
matching is required, whether white-space on either side of the
designated values is allowed, and so on.  Is this obvious from the
context of the other SIP RFCs?  It would trouble me as an implementor.
 There are a couple of nits below where I've called this out.

Apology in advance: There are quite likely things I've called out that
would be obvious to a seasoned SIP implementor who is after all the
target of this draft; pardon the irritation.

Nits:

1. 3rd para "specifies by whom, and in which way that information" -
needs comma after 'way'

3.4 "defined in the data model" is unclear. You mean "the data model
in this specification" I think? But I'm not sure.

4.1 " A conference object document begins with the root element tag
<conference-info>" - the word 'tag' is superfluous here, not part of
the idiom used elsewhere in this document

4.2 <conference-description> takes a "lang" attribute.  Is this free
text, ISO 639, or takes its definition from elsewhere in the SIP
suite?  Shouldn't something be said?

4.2.6  "The <allow-sidebars> element represents a boolean value.  If
set to  TRUE" Does this mean the content of the element must be the
string TRUE?  Case-sensitive?  White-space before and after allowed?

4.2.9 2nd bullet - 'This attribute contains one of the following
values: "none", "administrator", "moderator",  "user", "observer", and
"participant". '  Is it obvious to a reader whether exact-matching is
required or case-mixing is allowed? Is white space allowed?  Apologies
if this is defined elsewhere and I missed it.

4.2.9 2nd bullet - " The roles semantic" - missing apostrophe after
"roles".  Also grammatically awkward, maybe "The roles' semantic
definitions are.."

4.2.9 3rd bullet - "The <mixing-end-offset> child element specifies
the time a conference media mixing stops" - superfluous "a" after
"time"

4.2.13 4th bullet - missing comma after "values"

4.4.1 "The <allow-conference-event-subscription> element represents a
boolean action. " - should 'action' be 'value'? (this idiom also
appears several more times in the draft)

4.5 " Other elements from different namespaces MAY be present for the
purposes of extensibility." I was a bit surprised to encounter this
for the first time here; does such extensibility not apply to all the
elements defined previously? If it's generally true, maybe move it up
to an introductory section?   If child namespaces are generally
disallowed and this is an exception, that also deserves saying at the
top of the document.  Section 6 suggests that extensibility is
generally allowed for elements in this language, in which case the
statement here is superfluous?

4.6.2 ""closedAuthenticated": A 'closedAuthenticated' policy MUST have
 each conference participant in the allowed users list (listed under
the <allowed-users-list> XML element" - 'XML' is superfluous, appears
a couple of times in this section

4.6.5 "4.6.5.  <user> and Its <user> Sub-elements" - title looks
funny, is the second <user> superfluous?

8. "Futhermore, users may use different namespaces to access to a
conference as explained in Section 4.6.5."  I revisited 4.6.5 and it
doesn't contain the word "namespace", it discusses user identifiers.
Should "namespace" be replaced by "identifier" in this paragraph?
Also "Futhermore" is misspelled.

---

From: Oscar Novo <[email-masked]>
Date: Tue, 19 Apr 2011 14:16:52 +0200

Hi Tim,

I've created a new version of the draft with your comments:

http://tools.ietf.org/html/draft-ietf-xcon-common-data-model-26

My comments inline as a [ON]

Cheers,

Oscar

-----Original Message-----
From: Tim Bray [mailto:[email-masked]] 
Sent: 16. huhtikuuta 2011 20:29
To: [email-masked]; [email-masked]; S Moonesamy; [email-masked]; Oscar Novo; Gonzalo Camarillo; [email-masked]; [email-masked]
Subject: Apps-team review of draft-ietf-xcon-common-data-model-25.txt

I have been selected as the Applications Area Review Team reviewer for this draft (for background on apps-review, please see http://www.apps.ietf.org/content/applications-area-review-team).

I'm not a strong enough SIP expert to express an opinion as to whether this is ready for publication in the sense of it being a useful and problem-free extension of the SIP standards framework.  However, it seems a reasonable specification of a reasonable XML language extension and I didn't see anything obviously broken at the SIP level; there are a few nits, noted below, that should be addressed:

Observation: Element names given in double quotes, attribute names in single quotes.  Odd.  Is this a convention?

[ON] That's only a way to facilitate the reader a better understanding of the documents. 

General issue: There is much discussion of the values of various elements.  There seems little discussion of whether exact case matching is required, whether white-space on either side of the designated values is allowed, and so on.  Is this obvious from the context of the other SIP RFCs?  It would trouble me as an implementor.
 There are a couple of nits below where I've called this out.

[ON] The RELAX NG shema is defining the syntactic of the elements. That's why the text is not giving any clear guidance about it. The implementor just has to follow the RELAX NG schema defined in this document. 

Apology in advance: There are quite likely things I've called out that would be obvious to a seasoned SIP implementor who is after all the target of this draft; pardon the irritation.

Nits:

1. 3rd para "specifies by whom, and in which way that information" - needs comma after 'way'

[ON] OK

3.4 "defined in the data model" is unclear. You mean "the data model in this specification" I think? But I'm not sure.

[ON] OK

4.1 " A conference object document begins with the root element tag <conference-info>" - the word 'tag' is superfluous here, not part of the idiom used elsewhere in this document

[ON] OK

4.2 <conference-description> takes a "lang" attribute.  Is this free text, ISO 639, or takes its definition from elsewhere in the SIP suite?  Shouldn't something be said?

[ON] the precise type of the attribute is defined in the RELAX NG Schema. It would be redundant to mention it in the text. 

4.2.6  "The <allow-sidebars> element represents a boolean value.  If set to  TRUE" Does this mean the content of the element must be the string TRUE?  Case-sensitive?  White-space before and after allowed?

[ON] The type of <allow-sidebars> is defined in the RELAX NG schema as a boolean value. The implementor should follow the XML rules to define it. 

4.2.9 2nd bullet - 'This attribute contains one of the following
values: "none", "administrator", "moderator",  "user", "observer", and "participant". '  Is it obvious to a reader whether exact-matching is required or case-mixing is allowed? Is white space allowed?  Apologies if this is defined elsewhere and I missed it.

[ON] The RELAX NG schema defined the type of this attribute in the single-role-type element. An implementor should follow the exact syntactic format defined in this attribute. 

4.2.9 2nd bullet - " The roles semantic" - missing apostrophe after "roles".  Also grammatically awkward, maybe "The roles' semantic definitions are.."

[ON] OK

4.2.9 3rd bullet - "The <mixing-end-offset> child element specifies the time a conference media mixing stops" - superfluous "a" after "time"

[ON] OK

[ON] OK

4.4.1 "The <allow-conference-event-subscription> element represents a boolean action. " - should 'action' be 'value'? (this idiom also appears several more times in the draft)

[ON] I would say it's right. The element represents a boolean action. That's mean, the action can only take two boolean values. 

4.5 " Other elements from different namespaces MAY be present for the purposes of extensibility." I was a bit surprised to encounter this for the first time here; does such extensibility not apply to all the elements defined previously? If it's generally true, maybe move it up
to an introductory section?   If child namespaces are generally
disallowed and this is an exception, that also deserves saying at the top of the document.  Section 6 suggests that extensibility is generally allowed for elements in this language, in which case the statement here is superfluous?

[ON] Right, I've removed it from that section. It creates unclarity and confision in this part of the text. As you point out, section 6 explains the extensibility of the elements. 

4.6.2 ""closedAuthenticated": A 'closedAuthenticated' policy MUST have  each conference participant in the allowed users list (listed under the <allowed-users-list> XML element" - 'XML' is superfluous, appears a couple of times in this section

[ON] OK

4.6.5 "4.6.5.  <user> and Its <user> Sub-elements" - title looks funny, is the second <user> superfluous?

[ON] This document extends RFC4575. The name of that section comes from it:

http://tools.ietf.org/html/rfc4575#page-18

8. "Futhermore, users may use different namespaces to access to a conference as explained in Section 4.6.5."  I revisited 4.6.5 and it doesn't contain the word "namespace", it discusses user identifiers.
Should "namespace" be replaced by "identifier" in this paragraph?
Also "Futhermore" is misspelled.

[ON] OK

---

From: Tim Bray <[email-masked]>
Date: Tue, 19 Apr 2011 10:42:11 -0700

Looks good. Follow up:

> [ON] The RELAX NG shema is defining the syntactic of the elements. That's why the text is not giving any clear guidance about it. The implementor just has to follow the RELAX NG schema defined in t…

So I think you need a paragraph in your introduction saying that the
syntax of element values is constrained by the provided RNG grammar,
which is normative; the text in the main body of the specification is
explanatory, but implementation MUST generate and parse content
conforming to the schema.

> [ON] I would say it's right. The element represents a boolean action. That's mean, the action can only take two boolean values.

The term "boolean" has well-defined semantics in math and in computer
language type theory.  It is not applicable to an "action" in either
of these senses.  But I don't care, it's obvious what you mean.

---

From: Oscar Novo <[email-masked]>
Date: Wed, 20 Apr 2011 10:23:49 +0200

Hi,

Thanks for your feedback. Section "3.1 Data Model Format" already take care of explaining your suggestion: 

   "A conference object document is an XML [W3C.REC-xml-20001006]
   document that MUST be well formed and SHOULD be valid.  Conference
   object documents MUST be based on Extensible Markup Language (XML)
   1.0 and SHOULD be encoded using UTF-8." 

Cheers,

Oscar

-----Original Message-----
From: Tim Bray [mailto:[email-masked]] 
Sent: 19. huhtikuuta 2011 20:42
To: Oscar Novo
Cc: [email-masked]; S Moonesamy; [email-masked]; Gonzalo Camarillo; [email-masked]; [email-masked]
Subject: Re: Apps-team review of draft-ietf-xcon-common-data-model-25.txt

Looks good. Follow up:

> [ON] The RELAX NG shema is defining the syntactic of the elements. That's why the text is not giving any clear guidance about it. The implementor just has to follow the RELAX NG schema defined in t…

So I think you need a paragraph in your introduction saying that the syntax of element values is constrained by the provided RNG grammar, which is normative; the text in the main body of the specification is explanatory, but implementation MUST generate and parse content conforming to the schema.

> [ON] I would say it's right. The element represents a boolean action. That's mean, the action can only take two boolean values.

The term "boolean" has well-defined semantics in math and in computer language type theory.  It is not applicable to an "action" in either of these senses.  But I don't care, it's obvious what you mean.