OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

odata message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: [OASIS Issue Tracker] Created: (ODATA-415) Use of "MUST," "MAY," "SHOULD," etc in Part 3 CSDL definitions


Use of "MUST," "MAY," "SHOULD," etc in Part 3 CSDL definitions
--------------------------------------------------------------

                 Key: ODATA-415
                 URL: http://tools.oasis-open.org/issues/browse/ODATA-415
             Project: OASIS Open Data Protocol (OData) TC
          Issue Type: Bug
          Components: OData CSDL
    Affects Versions: V4.0_WD01
            Reporter: Patrick Durusau


The prose in CSDL is a mixture of stating the definitions for elements and attributes and occassionally using RFC 2119 control language for other elements and attributes. 

First, definitions of elements and attributes are just stated as facts. ODATA is defining its elements/attributes and the use of MUST/SHOULD/MAY don't add anything to a definition. Either an element or attribute meets the definition, or it doesn't.

Second, the mixture of RDF 2119 terms risks leaving readers with the impression that some definitions are subject to greater precision than others. My assumption is that all definitions in CSDL, when appropriate, must be met by a conforming service or client. 

A couple of examples:

*****
3.1 Element edmx:Edmx

The metadata document MUST contain a single root edmx:Edmx element. This element MUST contain a single direct child edmx:DataServices element. 

In addition to the data services element, the Edmx element contains zero or more edmx:Reference elements. Reference elements specify the location of schemas used by the OData service.
*****

The first paragraph uses "MUST" but we are missing a "MAY for the edmx:Reference elements. But neither one is needed.

For example:

*****
The edmx:Edmx element is the root element of a metadata document. Every edmx:Edmx element contains one direct child edmx:DataServices element.

A edmx:Edmx element may contain zero or more edmx:Reference elements.
*****

I would move the "Reference elements specify the location of schemas used by the OData service." to where refernece elements are defined. 

Mostly because if the definitions of a reference element change, it will be very difficult to track down all the places where it is mentioned in passing.

Another example:

*****
3.1.1 Attribute Version

The Version attribute MUST be present on the edmx:Edmx element.

The Version attribute is a string value that specifies the version of the EDMX wrapper, and must be of the form <majorversion>.<minorversion>. This version of the specification defines version 4.0 of the EDMX Wrapper.
*****

I would say:

*****
Every edmx:Edmx element has a Version attribute.

The Version attribute is a string value that specifies the version of the EDMX wrapper, and has the form <majorversion>.<minorversion>. 
*****

I would make "This version of the specification defines version 4.0 of the EDMX Wrapper." into a note (non-normative) and add what the value should be for the <minorversion>. The value for minorversion maybe defined elsewhere but if a note is to be helpful, it should give the complete information needed by a reader.  

BTW, probably just my lack of familiarity with the spec but I didn't see a convention for specifying values? I am assuming <majorversion>.<minorversion> is satisfied by 4.0 but that is a guess on my part. Could be 4. or <4>.<0>. 

PS: I think among the XML community saying "root" for a document qualifies as being a single element. 

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira

        


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]