OData Version 4.0 Errata 01
Committee Specification Draft 01 /
Public Review Draft 01
24 July 2014
Specification URIs
This version:
http://docs.oasis-open.org/odata/odata/v4.0/errata01/csprd01/odata-v4.0-errata01-csprd01.doc (Authoritative)
http://docs.oasis-open.org/odata/odata/v4.0/errata01/csprd01/odata-v4.0-errata01-csprd01.html
http://docs.oasis-open.org/odata/odata/v4.0/errata01/csprd01/odata-v4.0-errata01-csprd01.pdf
Previous version:
N/A
Latest version:
http://docs.oasis-open.org/odata/odata/v4.0/errata01/odata-v4.0-errata01.doc (Authoritative)
http://docs.oasis-open.org/odata/odata/v4.0/errata01/odata-v4.0-errata01.html
http://docs.oasis-open.org/odata/odata/v4.0/errata01/odata-v4.0-errata01.pdf
Technical Committee:
OASIS Open Data Protocol (OData) TC
Chairs:
Ralf Handl (ralf.handl@sap.com), SAP AG
Ram Jeyaraman (Ram.Jeyaraman@microsoft.com), Microsoft
Editors:
Michael Pizzo (mikep@microsoft.com), Microsoft
Ralf Handl (ralf.handl@sap.com), SAP AG
Martin Zurmuehl (martin.zurmuehl@sap.com), SAP AG
Hubert Heijkers (hubert.heijkers@nl.ibm.com), IBM
Additional artifacts:
This prose specification is one component of a Work Product that also includes:
Related work:
This specification is related to:
Abstract:
This document lists Errata for the OASIS Standard OData Version 4.0.
Status:
This document was last revised or approved by the OASIS Open Data Protocol (OData) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document.
Technical Committee members should send comments on this specification to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the “Send A Comment” button on the Technical Committee’s web page at https://www.oasis-open.org/committees/odata/.
For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (https://www.oasis-open.org/committees/odata/ipr.php).
Citation format:
When referencing this specification the following citation format should be used:
[OData-v4.0-errata01]
OData Version 4.0 Errata 01. Edited by Michael Pizzo, Ralf Handl, Martin Zurmuehl, and Hubert Heijkers. 24 July 2014. OASIS Committee Specification Draft 01 / Public Review Draft 01. http://docs.oasis-open.org/odata/odata/v4.0/errata01/csprd01/odata-v4.0-errata01-csprd01.html. Latest version: http://docs.oasis-open.org/odata/odata/v4.0/errata01/odata-v4.0-errata01.html.
Notices
Copyright © OASIS Open 2014. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.
Table of Contents
4 Part 3: Common Schema Definition Language
8 EDMX Schema: MetadataService
This document lists the approved changes to the OData Version 4.0 specification and contains one chapter per changed part of the specification.
Additional documents containing the final specification text with these changes applied are also available and linked in section "Additional artifacts" on the title page.
[OData-Protocol] OData Version 4.0 Part 1:
Protocol.
See link in “Related work” section on cover page.
Section |
Issue |
Comment |
1.2 Normative References |
Reference to obsolete RFC 2616 removed, references to draft RFCs updated to non-draft RFCs |
|
3 Data Model |
Made entity identity description more precise |
|
4.1 Entity-Ids and Entity References |
Made entity identity description more precise |
|
4.2 Read URLs and Edit URLs |
Consistent use of Read/Edit URL and Read/Edit Link |
|
5.2 Model Versioning
|
Clarified rules around schema versioning |
|
Clarified rules around schema versioning |
||
6.1 Query Option Extensibility
|
Minor editorial changes |
|
Clarified handling of query options in returned URLs |
||
7 Formats |
Reference updated |
|
8.1.1 Header Content-Type
|
Clarified rules around custom format parameters |
|
Clarified rules around use of custom query options |
||
Reference updated |
||
8.1.2 Header Content-Encoding |
Reference updated |
|
8.1.3 Header Content-Language |
Reference updated |
|
8.1.4 Header Content-Length |
Reference updated |
|
8.2.1 Header Accept
|
Clarified rules around custom format parameters |
|
Reference updated |
||
8.2.2 Header Accept-Charset |
Reference updated |
|
8.2.3 Header Accept-Language |
Reference updated |
|
8.2.4 Header If-Match
|
Fixed typo to match defined term name |
|
Clarified use of If-Match with Actions |
||
Reference updated |
||
8.2.5 Header If-None-Match
|
Fixed typo to match defined term name |
|
Reference updated |
||
8.2.8 Header Prefer |
Reference updated |
|
8.2.8.7 Preference return=representation and return=minimal |
Minor editorial changes |
|
Reference updated |
||
8.2.8.8 Preference respond-async |
Reference updated |
|
8.2.8.9 Preference wait |
Reference updated |
|
8.3.4 Header Preference-Applied |
Reference updated |
|
9.1.4 Response Code 204 No Content |
Reference updated |
|
9.1.5 Response Code 3xx Redirection |
Reference updated |
|
9.1.6 Response Code 304 Not Modified
|
Removed invalid case |
|
Reference updated |
||
9.2.2 Response Code 405 Method not Allowed |
Reference updated |
|
9.2.4 Response Code 412 Precondition Failed
|
Imported definition of 412 response code from [RFC2616] to reference from other sections that use it |
|
Reference updated |
||
9.3 Server Error Responses |
Reference updated |
|
10 Context URL |
Fixed description of {type-name} |
|
10.2,10.3,10.7,10.8,10.9,10,10.16 Context URL |
Spelled out construction rules for unknown entity set cases |
|
10.6 Derived Entity |
Minor editorial changes |
|
10.9 Collection of Projected Entities |
Moved example 19 from section 10.8 |
|
10.14 Collection of Complex or Primitive Types |
Added missing parens to example 25 |
|
Clarified use case |
||
10.15 Complex or Primitive Type
|
Added missing parens to example 26 |
|
Clarified use case |
||
11.2 Requesting Data |
Consistent use of "structural" |
|
11.2.4.2 System Query Option $expand |
Consistent use of "related" |
|
Minor editorial changes |
||
11.2.4.2.1 Expand Options |
Consistent use of "related" |
|
Minor editorial changes |
||
11.2.4.2.1.1 Expand Option $levels |
Minor editorial changes |
|
11.2.5.1 System Query Option $filter |
Consistent description of $count segment |
|
11.2.5.1.2 Build-in Query Functions |
Fixed non-normative example |
|
11.2.5.2 System Query Option $orderby |
Consistent description of $count segment |
|
11.2.5.5 System Query Option $count |
Added client guidance |
|
11.2.5.7 Server-Driven Paging |
Clarified the use of $format in delta links |
|
11.2.9 Requesting the Number of Items in a Collection |
Consistent description of $count segment |
|
Consistent use of "primitive" |
||
11.4.1.5 Returning Results from Data Modification Request
|
Added section to centralized common description of rules for returning an entity from a data modification |
|
Added section to centralize common description of rules for returning an entity from a data modification |
||
Clarified rules in new section for media entities |
||
11.4.2 Create an Entity |
Minor editorial changes |
|
11.4.2.1 Link to Related Entities When Creating an Entity |
Removed use of "associated" |
|
11.4.2.2 Create Related Entities When Creating an Entity |
Called out that media entities do not support deep inserts |
|
11.4.3 Update an Entity |
Made wording more precise |
|
More consistent/precise wording |
||
Called out handling of id and type in update payload |
||
More consistent/precise wording |
||
11.4.4 Upsert an Entity |
Made wording consistent with Update |
|
Describe limitation of upserts with server generated keys |
||
11.4.7.3 Deleting a Media Entity |
Clarified handling of media entity URL for Delete |
|
11.4.8.2 Deleting Stream Values |
Clarified handling of media entity URL for Delete |
|
11.4.9 Managing Values and Properties Directly |
Formally define the “edit URL” of a property |
|
11.4.9.1 Update a Primitive Property |
Added description of update using /$value |
|
11.4.9.2 Set a Value to Null
|
Clarified handling of media entity URL for Delete |
|
Clarified error results |
||
Minor editorial changes |
||
11.4.9.3 Update a Complex Type |
Corrected section title |
|
11.5.3.1.1 Inline Parameter Syntax |
Minor editorial changes |
|
11.6 Asynchronous Requests
|
Minor editorial changes |
|
Reference updated |
||
11.7.1 Batch Request Headers |
Fixed header value in non-normative code example |
|
11.7.3 Change Sets |
Minor editorial change |
|
11.7.3.1 Referencing New Entities in a Change Set |
Clarified use of $<content-id> in a changeset |
|
11.7.4 Responding to a Batch Request |
Minor editorial change |
|
12 Security Considerations |
Reference updated |
|
13.1.1 OData Minimal Conformance Level |
Consistent use of Read/Edit URL and Read/Edit Link |
Section |
Issue |
Comment |
2 Url Components |
Clarified that percent-decoding happens exactly once and copied reference to RFC3986 from [OData-ABNF] |
|
3 Service Root URL |
Clarified that, as per the [OData-ABNF] rules, the service root always terminates in a forward slash. |
|
4 Resource Path |
Removed incorrect reference to Content-Location. |
|
4.8 Addressing Count of a Collection |
Replicated common semantics of composing system query options to $count for better locality/discoverability |
|
4.12 Addressing All Entities in a Service |
Replicated common semantics for composing type segments to collections and added examples for better locality/discoverability |
|
5.1 System Query Options |
Added missing rule from [OData-ABNF] around composing $filter and $search to /$count |
|
5.1.1.1 Logical Operators |
Called out eq/ne comparison for stream,binary,geo types |
|
5.1.1.4.28 isof |
Added reference to assignment rules in 5.1.1.4.29 cast |
|
5.1.1.4.29 cast |
Made description of type returned by cast function consistent with [OData-ABNF] |
|
Included description of assignability of structured types to enable this section to be shared with isof |
||
Corrected typo; the first four rules (not three) all refer to primitive types |
||
5.1.1.6.2 Complex and Collection Literals |
Described the use of parameter aliases to reference inline complex and collection values |
|
5.1.1.6.4 $it |
Called out use of /$it for invoking bound functions (as per [OData-ABNF]) and added example |
|
5.1.2 $expand
|
Optional cast to complex type, ABNF was more restrictive than normative prose text |
|
Add descriptive text for counting related entities |
||
5.1.3 $select |
Made description more precise |
|
Optional cast to complex type, ABNF was more restrictive than normative prose text |
Section |
Issue |
Comment |
3.2 Element edmx:DataServices |
Minor editorial changes |
|
3.3 edmx:Reference |
Clarified alias conflicts and recursive referencing |
|
3.3.1 Attribute Uri |
Minor editorial changes |
|
3.4.2 Attribute Alias |
Clarified alias conflicts and recursive referencing |
|
4.4 Primitive Types |
Clarified the usage of the primitive type Edm.Stream |
|
5.1.1 Attribute Namespace |
Minor editorial changes |
|
6.2 Property Facet |
Minor editorial changes |
|
6.2.4 Attribute Scale |
Clarified allowed range of Scale values |
|
6.2.7 Attribute DefaultValue |
Minor editorial changes |
|
7.1.5 Attribute ContainsTarget
|
Minor editorial changes |
|
Described use of NavPropBinding with Containment |
||
Minor editorial change |
||
8.1.5 Attribute HasStream |
Clarified relationship of HasStream attribute and inheritance |
|
Consistent use of "nominal" |
||
11.1.3 Type Definition Facets |
Minor editorial changes |
|
12.1 Element edm:Action |
Consistent use of "primitive" |
|
12.2 Element edm:Function |
Consistent use of "primitive" |
|
13 Entity Container |
Removed redundant and confusing note referencing “Part 1: Protocol” |
|
13.4.1 Attribute Path |
Described use of NavPropBinding with Containment
|
|
13.4.2 Attribute TargetPath |
||
13.6 Element edm:FunctionImport |
Clarified, that all overloads of unbound functions specified in a function import are callable from the entity container |
|
14.1.4 Attribute DefaultValue |
Minor editorial changes |
|
14.1.5 Attribute AppliesTo |
Clarified client expectations around AppliesTo |
|
14.2.1 Attribute Target |
Removed unnecessary reference to TargetPath section |
|
Called out that the Schema element can be annotated by inline annotations |
||
Minor editorial changes |
||
Described targeting property of an entity type within an entityset |
||
14.3 Element edm:Annotation |
Included missing ReturnType in annotatable elements |
|
14.5.1 Comparison and Logical Operators |
Minor editorial changes |
|
14.5.6 Expression edm:If |
Minor editorial changes |
|
14.5.11 Expression edm:NavigationPropertyPath |
Consistent use of "structural" |
|
14.5.13 Expression edm:PropertyPath |
Consistent use of "structural" |
|
14.5.15 Expression edm:UrlRef |
Consistent description of relative reference handling |
|
Added example |
||
15.1 Entity Model Wrapper |
Minor editorial changes |
|
15.2 Schema |
Minor editorial changes |
|
15.3 Types |
Added enumeration member name syntax from [OData-ABNF] |
|
Fixed typo to match defined term name |
||
15.6 Entity Container |
Added missing IncludeInServiceDocument property in example |
|
16.1 Products and Categories Example |
Corrected vocabulary URIs in example. |
|
17.5 TargetPath |
Removed unused path expression |
|
Minor editorial changes |
||
17.6 Boolean |
Minor editorial changes |
Line |
Issue |
Comment |
167 |
Optional type-cast segment for boundComplexColFuncCall, ABNF was more restrictive than normative prose text / boundComplexColFuncCall [ "/" qualifiedComplexTypeName ] [ collectionPath ] |
|
245 |
Optional cast to complex type, ABNF was more restrictive than normative prose text expandPath = [ ( qualifiedEntityTypeName / qualifiedComplexTypeName ) "/" ] |
|
261 |
Discourage leading zeroes in $levels levels = '$levels' EQ ( oneToNine 1*DIGIT / 'max' ) |
|
299 |
Optional cast to complex type, ABNF was more restrictive than normative prose text / [ ( qualifiedEntityTypeName / qualifiedComplexTypeName ) "/" ] |
|
426 |
/ streamProperty [ singlePathExpr ] |
|
522 |
Made hasExpr more precise hasExpr = RWS 'has' RWS |
|
662 |
Added comment that forward slash literal is allowed in query part of URLs / ( "/" / "%2F" ) ; solidus U+002F - literal form is allowed in the query part of a URL |
|
897 |
Hour value 22 is allowed / "2" ( "0" / "1" / "2" / "3" ) |
|
992 |
Refactored header rules to use new rule EQ-h for equal signs in headers ; / token [EQ-hBWS "=" BWS word ] *( OWS ";" [ OWS parameter ] ) |
|
996 |
Refactored header rules to use new rule EQ-h for equal signs in headers callbackPreference = "odata.callback" OWS ";" OWS "url" EQ-hBWS "=" BWS DQUOTE URI DQUOTE |
|
1000 |
Refactored header rules to use new rule EQ-h for equal signs in headers includeAnnotationsPreference = "odata.include-annotations" EQ-hBWS "=" BWS DQUOTE annotationsList DQUOTE |
|
1008 |
Refactored header rules to use new rule EQ-h for equal signs in headers maxpagesizePreference = "odata.maxpagesize" EQ-hBWS "=" BWS oneToNine *DIGIT |
|
1012 |
Refactored header rules to use new rule EQ-h for equal signs in headers returnPreference = "return" EQ-hBWS "=" BWS ( 'representation' / 'minimal' ) |
|
1016 |
Refactored header rules to use new rule EQ-h for equal signs in headers waitPreference = "wait" EQ-hBWS "=" BWS 1*DIGIT |
|
1018 |
Refactored header rules to use new rule EQ-h for equal signs in headers ;parameter = token [ EQ-hBWS "=" BWS word ] |
|
1029 |
Rule OWS is only used in headers where no percent-encoding is allowed OWS = *( SP / HTAB ) ; "optional" whitespace |
|
Added rule BWS-h for discouraged whitespace in headers BWS-h = *( SP / HTAB ) ; "bad" whitespace in header values |
||
Added rule EQ-h for equal sign with discouraged whitespace in headers EQ-h = BWS-h EQ BWS-h |
||
1034 |
Rule OWS moved to header section OWS = *( SP / HTAB / "%20" / "%09" ) ; "optional" whitespace |
|
1036 |
Rule BWS now explicitly defined BWS = OWS*( SP / HTAB / "%20" / "%09" ) ; "bad" whitespace |
|
1125 |
Typo unintentionally excluded %70 to %7f pct-encoded-unescaped = "%" ( "0" / "1" / "3" / "4" / "6" / "7" / "8" / "9" / A-to-F ) HEXDIG |
Line |
Issue |
Comment |
67 |
Copied overview text from file header to XML comment below document root <!--
This document contains positive and negative test cases for the OData ABNF Construction Rules Version 4.0. Positive test cases consist of the rule to test, the input string to parse, and a description of the test case, often starting with a section number referring to OData Version 4.0 Part 2: URL Conventions. Negative test cases in addition state the character position at which the invalid portion of input text starts, 0 meaning the whole input string.
These test cases can be automatically executed with the ABNF test tool available at https://github.com/SAP/abnf-test-tool. This tool is neither required for interpreting the test cases, nor is it part of the OData work product.
--> |
|
73 |
Removed TODO comment <!-- TODO: remove constraints that were only needed for data aggregation --> |
|
255 |
Added new primitiveNonKeyProperty value <Match>State</Match> |
|
260 |
Added new primitiveNonKeyProperty value <Match>ZipCode</Match> |
|
361 |
Hour value 22 <Input>2012-09-03T0822:09:02Z</Input> |
|
932 |
Test cases for bound complex collection function with cast segment <TestCase Name="4.5.2 Call bound complex collection function with cast" Rule="odataRelativeUri"> <Input>Customers/Model.MostPopularAddresses()/Model.AddressWithLocation</Input> </TestCase> <TestCase Name="4.5.2 Call bound complex collection function with cast" Rule="odataRelativeUri"> <Input>Customers/Model.MostPopularAddresses()/Model.AddressWithLocation/$count</Input> </TestCase> |
|
1085 |
Test case for $expand with complex type cast <TestCase Name="4.9 Inheritance - $expand on complex resource" Rule="odataRelativeUri"> <Input>TheMostPopularAddresses()?$expand=Model.AddressWithLocation/Country</Input> </TestCase> |
|
1176 |
Test case for function bound to stream property <TestCase Name="5.1.1 Filter - member expressions - stream" Rule="firstMemberExpr"> <Input>Thumbnail/Model.Available()</Input> </TestCase> |
|
1217 |
Test case for comparing complex times <TestCase Name="5.1.1.1.1 comparing complex types" Rule="filter"> <Input>$filter=Address eq {"Street":"NE 40th","City":"Redmond","State":"WA","ZipCode":"98052"}</Input> </TestCase> |
|
1692 |
Negative test case for $levels with leading zeroes <TestCase Name="5.1.2 Expand - levels without leading zeroes" Rule="expand" FailAt="25"> <Input>$expand=Category($levels=04)</Input> </TestCase> |
|
1720 |
Test case for $select with complex type cast <TestCase Name="5.1.3 Select on complex resource - with cast and property of sub-type" Rule="select"> <Input>$select=Model.AddressWithLocation/Location</Input> </TestCase> |
|
2046 |
Added test case for $filter with geometry literals <TestCase Name="$filter with geometry" Rule="filter"> <Input>$filter=geo.intersects(geometry'SRID=0;Point(142.1 64.1)',geometry'SRID=0;Polygon((1 1,1 1),(1 1,2 2,3 3,1 1))')</Input> </TestCase> |
|
2487 |
Added test case for wait with unnecessary whitespace <TestCase Name="Preferences - wait with bad whitespace" Rule="preference"> <Input>wait = 0</Input> </TestCase> |
|
2487 |
Test case for percent-encoded hex pairs starting with 7 <TestCase Name="ODATA-633 hex pair bug" Rule="stringInJSON"> <Input>"b%75g"</Input> </TestCase> |
Line |
Issue |
Comment |
183 |
Added Annotation to TActionFunctionReturnType <xs:complexType name="TActionFunctionReturnType"> <xs:sequence> <xs:element ref="edm:Annotation" minOccurs="0" maxOccurs="unbounded" /> </xs:sequence> <xs:attribute name="Type" type="edm:TTypeName" use="required" /> <xs:attribute name="Nullable" type="xs:boolean" use="optional" /> <xs:attributeGroup ref="edm:TFacetAttributes" /> </xs:complexType> |
|
734 |
Added ReturnType to list of values for TAppliesTo <xs:enumeration value="ReturnType" /> |
Line |
Issue |
Comment |
283 |
Added property IncludeInServiceDocument <Property Name="IncludeInServiceDocument" Type="Edm.Boolean" Nullable="false" /> |
|
297 |
Removed property Annotations <Property Name="Annotations" Type="Collection(Edm.Metadata.InlineAnnotation)" /> |
The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol], are gratefully acknowledged.
Revision |
Date |
Editor |
Changes Made |
WD01 |
2014-05-16 |
Michael Pizzo Ralf Handl Martin Zurmuehl Hubert Heijkers |
First version |