comment attached to AVDL ballot

["Karl F. Best" <karl.best@oasis-open.org>]

In the just completed ballot to approve the AVDL spec as an OASIS 
Standard, the following comment was received:

 From BEA (a Yes vote):

I have decided to cast BEA’s vote for AVDL 1.0 as an OASIS Standard, 
however I have significant concerns about the specification in its 
current form. I would not be inclined to approve a future version 
without substantial improvement in some areas. In general, the document 
is insufficiently precise about what an implementer must do and must not 
do to comply with this specification. Experience has shown that tends to 
lead to practical interoperability problems. Section 2 mixes examples 
and normative statements in a way that makes it difficult to understand 
which is which.
I have the following specific suggestions.
1. Adopt the conventional use of keywords like MUST, SHOULD and MAY as 
defined in RFC 2119. Add a short section at the beginning stating that 
you have done so.
2. Mixing normative text and examples together makes it hard to be 
precise. Consider an alternative structure, such as a separate section 
for examples. If you keep the examples intermixed, clearly label each 
and state at the beginning what is normative.
3. The schema is not explicitly referenced in the document and it should 
be. It is reasonable to say that the use of XML Schema is not required, 
but that AVDL compliant documents must conform to the schema.
4. Each schema element should be described in a separate subsection. The 
exact name of the element should be given; along with whether it 
required or optional; XML attributes if any; relationship or 
dependencies on other elements; semantics; any syntax constraints not 
captured by the schema, etc. BTW, I think some of the comments in the 
schema file would better appear in the specification.
5. Line 234 says that the complete example is contained in the appendix, 
but it is not.
6. Line 180 starts with Traversal Ste. I think you mean Traversal Step. 
But the paragraph seems to be defining Traversal, Traversal Step and 
Traversal Step Id. I suggest using three definitions.
I suggest you look at the SAML or XACML specifications as examples of 
how to construct normative language using the RFC 2119 keywords.



-Karl

=================================================================
Karl F. Best
Vice President, OASIS
office  +1 978.667.5115 x206     mobile +1 978.761.1648
karl.best@oasis-open.org      http://www.oasis-open.org