RE: Issue pr007 - Suggested changes to conformance sections andprecedenc

I would like to propose the following changes below. My comments are tagged with [Ram Jeyaraman] below.

Thanks.

From: Martin Chapman [mailto:martin.chapman@oracle.com]
Sent: Friday, April 03, 2009 9:19 AM
To: ws-dd-comment@lists.oasis-open.org
Cc: 'OASIS TAB'
Subject: [ws-dd-comment] Public Review Comments

As a TAB member, I was asked to review the Public Review Drafts for WS-Discovery, Device Profile for Web Services, and SOAP over UDP.

These are my individual comments and do not represent the views of the TAB as a whole.

Martin

-----

Comments applicable to all three specs.

1. Use of lowercase RFC2119 keywords (e.g. may) throughout the specs should be reviewed.

RFC2119 is not case sensitive. The OASIS guidelines suggest only using uppercase, and to not use lowercase versions to avoid any ambiguity. So either convert each may to MAY or find a similar word.

[Ram Jeyaraman] Agree. Editors should scan the document to ensure that all normative keywords are capitalized. Non-normative uses of RFC2119 keywords should be replaced with other equivalent words.

2. Add cross-references in the conformance sections to the respective sections where the roles and/or normative statements are defined.

[Ram Jeyaraman] Agree. Editors to add a link to the sections that define the various roles / modes referred to from the conformance section text.

3. Consider changing the precedence order so that XML Schema and WSDL files take precedence over the normative text, since these files can be downloaded and checked with tools they are less likely to contain errors.

[Ram Jeyaraman] I suggest that we do not enforce a precedence order. Any error or inconsistency should be treated as a bug and reported to the TC. I suggest the following text to be inserted into the specifications under the “XSD and WSDL files” section: “There should be no inconsistencies found between any of the normative text within this specification, the normative outlines, the XML Schema definitions, and the WSDL descriptions, and so no general precedence rule is defined. If an inconsistency is observed then it should be reported as a comment on the specification as described in the "Status" section above”.

Comment on Device Profile for Web Services PR 01

4. In the Conformance section, change "An endpoint MAY implement.." to "An endpoint MUST implement at least one..." otherwise an endpoint not supporting any role will comply!

[Ram Jeyaraman] Agree. Replace “An endpoint MAY implement more than one of the roles defined herein” with “An endpoint MUST implement at least one of the roles defined herein”.

SOAP over UDP PR 01

5. In the Conformance section, add a sentence to the positive ( e.g. "to conform to this spec...") as currently it only defines conformance by the negative., which is not good style.

[Ram Jeyaraman] Agree. Replace “An implementation is not conformant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein” with “A conformant implementation MUST satisfy all the MUST or REQUIRED level requirements defined herein”.

This issue is assigned the number pr007. For further discussions on this issue, please refer to this issue number or use this thread.