Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-415

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

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: V4.0_WD01
    • Fix Version/s: V4.0_CSD02
    • Component/s: CSDL XML
    • Labels:
      None
    • Environment:

      [Proposed]

      Description

      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.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              patrick Patrick Durusau
            • Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: