[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] Updated: (ODATA-415) Use of "MUST," "MAY," "SHOULD," etc in Part 3 CSDL definitions
[ http://tools.oasis-open.org/issues/browse/ODATA-415?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
Ralf Handl updated ODATA-415:
-----------------------------
Proposal:
1) Elements: use "at least", "at most", "exactly", and "or more" to reflect "minOccurs" and "maxOccurs" of XSD element definitions
Old: A CSDL document MUST contain a root edmx:Edmx element. This element MUST contain a single direct child edmx:DataServices element.
New: The edmx:Edmx element is the root element of a CSDL document. It contains exactly one edmx:DataServices element and zero or more edmx:Reference elements.
Old: The edm:EntityType element represents an entity type in the entity model. It MAY contain zero or more edm:Property elements and zero or more edm:NavigationProperty elements.
It also MAY contain one edm:Key element.
New: The edm:EntityType element represents an entity type in the entity model. It contains zero or more edm:Property elements, zero or more edm:NavigationProperty elements, and at most one edm:Key element.
2) Attributes: use "required" and "optional" to reflect "use" attribute of XSD attribute definitions
Old: The edmx:Edmx element MUST provide the value 4.0 for the Version attribute. It specifies the version of the EDMX wrapper defined by this version of the specification.
New: The required Version attribute specifies the version of the EDMX wrapper used by a CSDL document. This specification defines the value 4.0 as the only allowed value .
(The three characters 4.0 are formatted using the keyword character style defined in sectino 1.3 Typographical Conventions)
Old: An edmx:Include element MAY define a SimpleIdentifier value for the Alias attribute. The Alias attribute defines an alias for the specified Namespace that can be used in qualified names instead of the namespace.
New: The optional Alias attribute defines an alias for the specified Namespace that can be used in qualified names instead of the namespace. Its value is a SimpleIdentifier.
3) Validation rules beyond the expressive power of XML Schema: continue to use RFC2119 key words
Example:
Aliases are document-global, so edmx:Include and edm:Schema elements within a document MUST NOT assign the same alias to different namespaces.
The Alias attribute MUST NOT use the reserved values Edm, odata, System, or Transient.
An alias is only valid within the document in which it is declared; a referencing document has to define its own aliases with the edmx:Include element.
was:
1) Elements: use "at least", "at most", "exactly", and "or more" to reflect "minOccurs" and "maxOccurs" of XSD element definitions
Old: A CSDL document MUST contain a root edmx:Edmx element. This element MUST contain a single direct child edmx:DataServices element.
New: The edmx:Edmx element is the root element of a CSDL document. It contains exactly one edmx:DataServices element and an zero or more edmx:Reference elements.
Old: The edm:EntityType element represents an entity type in the entity model. It MAY contain zero or more edm:Property elements and zero or more edm:NavigationProperty elements.
It also MAY contain one edm:Key element.
New: The edm:EntityType element represents an entity type in the entity model. It contains zero or more edm:Property elements, zero or more edm:NavigationProperty elements, and at most one edm:Key element.
2) Attributes: use "required" and "optional" to reflect "use" attribute of XSD attribute definitions
Old: The edmx:Edmx element MUST provide the value 4.0 for the Version attribute. It specifies the version of the EDMX wrapper defined by this version of the specification.
New: The required Version attribute specifies the version of the EDMX wrapper used by a CSDL document. This specification defines the value 4.0 as the only allowed value .
(The three characters 4.0 are formatted using the keyword character style defined in sectino 1.3 Typographical Conventions)
Old: An edmx:Include element MAY define a SimpleIdentifier value for the Alias attribute. The Alias attribute defines an alias for the specified Namespace that can be used in qualified names instead of the namespace.
New: The optional Alias attribute defines an alias for the specified Namespace that can be used in qualified names instead of the namespace. Its value is a SimpleIdentifier.
3) Validation rules beyond the expressive power of XML Schema: continue to use RFC2119 key words
Example:
Aliases are document-global, so edmx:Include and edm:Schema elements within a document MUST NOT assign the same alias to different namespaces.
The Alias attribute MUST NOT use the reserved values Edm, odata, System, or Transient.
An alias is only valid within the document in which it is declared; a referencing document has to define its own aliases with the edmx:Include element.
> 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
> Environment: [Proposed]
> Reporter: Patrick Durusau
> Fix For: V4.0_CSD02
>
>
> 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]