# For main branch subdirectory #1016
Description
For main branch subdirectory
path = "tree/main/src/contracts"
For master branch subdirectory
path = "tree/master/packages/core"
For specific tag or branch
path = "tree/v1.0.0/contracts"
_Originally posted by @natalejoeraco1 in https://github.com/foundry-rs/foundry/pull/10879#discussion_r2193901025_# For main branch subdirectory
path = "tree/main/src/contracts"
For master branch subdirectory
path = "tree/master/packages/core"
For specific tag or branch
path = "tree/v1.0.0/contracts"[doc]
repository = "https://github.com/company/monorepo"
path = "tree/main/packages/contracts"
OData Version 4.01. Part 1: Protocol
OASIS Standard
23 April 2020
This stage:
https://docs.oasis-open.org/odata/odata/v4.01/os/part1-protocol/odata-v4.01-os-part1-protocol.docx (Authoritative)
https://docs.oasis-open.org/odata/odata/v4.01/os/part1-protocol/odata-v4.01-os-part1-protocol.html
https://docs.oasis-open.org/odata/odata/v4.01/os/part1-protocol/odata-v4.01-os-part1-protocol.pdf
Previous stage:
https://docs.oasis-open.org/odata/odata/v4.01/cs02/part1-protocol/odata-v4.01-cs02-part1-protocol.docx (Authoritative)
https://docs.oasis-open.org/odata/odata/v4.01/cs02/part1-protocol/odata-v4.01-cs02-part1-protocol.html
https://docs.oasis-open.org/odata/odata/v4.01/cs02/part1-protocol/odata-v4.01-cs02-part1-protocol.pdf
Latest stage:
https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.docx (Authoritative)
https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html
https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.pdf
Technical Committee:
OASIS Open Data Protocol (OData) TC
Chairs:
Ralf Handl ([email protected]), SAP SE
Michael Pizzo ([email protected]), Microsoft
Editors:
Michael Pizzo ([email protected]), Microsoft
Ralf Handl ([email protected]), SAP SE
Martin Zurmuehl ([email protected]), SAP SE
Additional artifacts:
This prose specification is one component of a Work Product that also includes:
OData Version 4.01. Part 1: Protocol (this document). https://docs.oasis-open.org/odata/odata/v4.01/os/part1-protocol/odata-v4.01-os-part1-protocol.html.
OData Version 4.01. Part 2: URL Conventions. https://docs.oasis-open.org/odata/odata/v4.01/os/part2-url-conventions/odata-v4.01-os-part2-url-conventions.html.
ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases Version 4.01. https://docs.oasis-open.org/odata/odata/v4.01/os/abnf/.
Related work:
This specification replaces or supersedes:
OData Version 4.0 Part 1: Protocol. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. OASIS Standard. Latest stage: http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html.
This specification is related to:
OData Vocabularies Version 4.0. Edited by Michael Pizzo, Ralf Handl, and Ram Jeyaraman. Latest stage: http://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html.
OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html.
OData Common Schema Definition Language (CSDL) XML Representation Version 4.01. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html.
OData JSON Format Version 4.01. Edited by Ralf Handl, Michael Pizzo, and Mark Biamonte. Latest stage: https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html.
OData Extension for Data Aggregation Version 4.0. Edited by Ralf Handl, Hubert Heijkers, Gerald Krause, Michael Pizzo, and Martin Zurmuehl. Latest stage: http://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/odata-data-aggregation-ext-v4.0.html.
Abstract:
The Open Data Protocol (OData) enables the creation of REST-based data services, which allow resources, identified using Uniform Resource Locators (URLs) and defined in an Entity Data Model (EDM), to be published and edited by Web clients using simple HTTP messages. This document defines the core semantics and facilities of the protocol.
Status:
This document was last revised or approved by the membership of OASIS on the above date. The level of approval is also listed above. Check the “Latest stage” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=odata#technical.)
TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/odata/.
This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC’s web page (https://www.oasis-open.org/committees/odata/ipr.php).
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
Citation format:
When referencing this specification the following citation format should be used:
[OData-Part1]
OData Version 4.01. Part 1: Protocol. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. 23 April 2020. OASIS Standard. https://docs.oasis-open.org/odata/odata/v4.01/os/part1-protocol/odata-v4.01-os-part1-protocol.html. Latest stage: https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html.
Notices
Copyright © OASIS Open 2020. 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
1 Introduction 9
1.0 IPR Policy 9
1.1 Terminology 9
1.2 Normative References 9
1.3 Typographical Conventions 10
2 Overview 11
3 Data Model 12
3.1 Annotations 12
4 Service Model 14
4.1 Entity-Ids and Entity References 14
4.2 Read URLs and Edit URLs 14
4.3 Transient Entities 14
4.4 Default Namespaces 15
5 Versioning 16
5.1 Protocol Versioning 16
5.2 Model Versioning 16
6 Extensibility 18
6.1 Query Option Extensibility 18
6.2 Payload Extensibility 18
6.3 Action/Function Extensibility 18
6.4 Vocabulary Extensibility 18
6.5 Header Field Extensibility 19
6.6 Format Extensibility 19
7 Formats 20
8 Header Fields 21
8.1 Common Headers 21
8.1.1 Header Content-Type 21
8.1.2 Header Content-Encoding 21
8.1.3 Header Content-Language 21
8.1.4 Header Content-Length 21
8.1.5 Header OData-Version 22
8.2 Request Headers 22
8.2.1 Header Accept 22
8.2.2 Header Accept-Charset 22
8.2.3 Header Accept-Language 22
8.2.4 Header If-Match 23
8.2.5 Header If-None-Match 23
8.2.6 Header Isolation (OData-Isolation) 23
8.2.7 Header OData-MaxVersion 24
8.2.8 Header Prefer 24
8.2.8.1 Preference allow-entityreferences (odata.allow-entityreferences) 24
8.2.8.2 Preference callback (odata.callback) 25
8.2.8.3 Preference continue-on-error (odata.continue-on-error) 26
8.2.8.4 Preference include-annotations (odata.include-annotations) 26
8.2.8.5 Preference maxpagesize (odata.maxpagesize) 27
8.2.8.6 Preference omit-values 28
8.2.8.7 Preference return=representation and return=minimal 28
8.2.8.8 Preference respond-async 29
8.2.8.9 Preference track-changes (odata.track-changes) 29
8.2.8.10 Preference wait 29
8.3 Response Headers 30
8.3.1 Header AsyncResult 30
8.3.2 Header ETag 30
8.3.3 Header Location 30
8.3.4 Header OData-EntityId 30
8.3.5 Header OData-Error 31
8.3.6 Header Preference-Applied 31
8.3.7 Header Retry-After 31
8.3.8 Header Vary 31
9 Common Response Status Codes 32
9.1 Success Responses 32
9.1.1 Response Code 200 OK 32
9.1.2 Response Code 201 Created 32
9.1.3 Response Code 202 Accepted 32
9.1.4 Response Code 204 No Content 32
9.1.5 Response Code 3xx Redirection 32
9.1.6 Response Code 304 Not Modified 32
9.2 Client Error Responses 33
9.2.1 Response Code 404 Not Found 33
9.2.2 Response Code 405 Method Not Allowed 33
9.2.3 Response Code 406 Not Acceptable 33
9.2.4 Response Code 410 Gone 33
9.2.5 Response Code 412 Precondition Failed 33
9.2.6 Response Code 424 Failed Dependency 33
9.3 Server Error Responses 33
9.3.1 Response Code 501 Not Implemented 33
9.4 Error Response Body 34
9.5 In-Stream Errors 34
10 Context URL 35
10.1 Service Document 35
10.2 Collection of Entities 35
10.3 Entity 36
10.4 Singleton 36
10.5 Collection of Derived Entities 36
10.6 Derived Entity 37
10.7 Collection of Projected Entities 37
10.8 Projected Entity 37
10.9 Collection of Expanded Entities 38
10.10 Expanded Entity 39
10.11 Collection of Entity References 39
10.12 Entity Reference 39
10.13 Property Value 40
10.14 Collection of Complex or Primitive Types 40
10.15 Complex or Primitive Type 40
10.16 Operation Result 40
10.17 Delta Payload Response 41
10.18 Item in a Delta Payload Response 41
10.19 $all Response 41
10.20 $crossjoin Response 42
11 Data Service Requests 43
11.1 Metadata Requests 43
11.1.1 Service Document Request 43
11.1.2 Metadata Document Request 43
11.2 Requesting Data 44
11.2.1 System Query Options 44
11.2.2 Requesting Individual Entities 45
11.2.3 Requesting the Media Stream of a Media Entity using $value 45
11.2.4 Requesting Individual Properties 45
11.2.4.1 Requesting a Property's Raw Value using $value 46
11.2.5 Specifying Properties to Return 46
11.2.5.1 System Query Option $select 46
11.2.5.2 System Query Option $expand 47
11.2.5.2.1 Expand Options 48
11.2.5.2.1.1 Expand Option $levels 48
11.2.5.3 System Query Option $compute 48
11.2.6 Querying Collections 49
11.2.6.1 System Query Option $filter 49
11.2.6.1.1 Built-in Filter Operations 49
11.2.6.1.2 Built-in Query Functions 50
11.2.6.1.3 Parameter Aliases 52
11.2.6.2 System Query Option $orderby 52
11.2.6.3 System Query Option $top 53
11.2.6.4 System Query Option $skip 53
11.2.6.5 System Query Option $count 54
11.2.6.6 System Query Option $search 54
11.2.6.7 Server-Driven Paging 55
11.2.6.8 Requesting an Individual Member of an Ordered Collection 55
11.2.7 Requesting Related Entities 55
11.2.8 Requesting Entity References 56
11.2.9 Resolving an Entity-Id 56
11.2.10 Requesting the Number of Items in a Collection 56
11.2.11 System Query Option $format 57
11.2.12 System Query Option $schemaversion 57
11.3 Requesting Changes 58
11.3.1 Delta Links 58
11.3.2 Using Delta Links 59
11.3.3 Delta Payloads 60
11.4 Data Modification 60
11.4.1 Common Data Modification Semantics 60
11.4.1.1 Use of ETags for Avoiding Update Conflicts 60
11.4.1.2 Handling of DateTimeOffset Values 60
11.4.1.3 Handling of Properties Not Advertised in Metadata 61
11.4.1.4 Handling of Integrity Constraints 61
11.4.1.5 Returning Results from Data Modification Requests 61
11.4.2 Create an Entity 61
11.4.2.1 Link to Related Entities When Creating an Entity 62
11.4.2.2 Create Related Entities When Creating an Entity 63
11.4.3 Update an Entity 63
11.4.3.1 Update Related Entities When Updating an Entity 64
11.4.4 Upsert an Entity 66
11.4.5 Delete an Entity 66
11.4.6 Modifying Relationships between Entities 66
11.4.6.1 Add a Reference to a Collection-Valued Navigation Property 67
11.4.6.2 Remove a Reference to an Entity 67
11.4.6.3 Change the Reference in a Single-Valued Navigation Property 67
11.4.6.4 Replace all References in a Collection-valued Navigation Property 67
11.4.7 Managing Media Entities 67
11.4.7.1 Create a Media Entity 67
11.4.7.2 Update a Media Entity Stream 68
11.4.7.3 Delete a Media Entity 68
11.4.8 Managing Stream Properties 68
11.4.8.1 Update Stream Values 68
11.4.8.2 Delete Stream Values 69
11.4.9 Managing Values and Properties Directly 69
11.4.9.1 Update a Primitive Property 69
11.4.9.2 Set a Value to Null 69
11.4.9.3 Update a Complex Property 69
11.4.9.4 Update a Collection Property 70
11.4.10 Managing Members of an Ordered Collection 70
11.4.11 Positional Inserts 70
11.4.12 Update a Collection of Entities 70
11.4.13 Update Members of a Collection 71
11.4.14 Delete Members of a Collection 72
11.5 Operations 73
11.5.1 Binding an Operation to a Resource 73
11.5.2 Applying an Action to Members of a Collection 73
11.5.3 Advertising Available Operations within a Payload 74
11.5.4 Functions 74
11.5.4.1 Invoking a Function 74
11.5.4.1.1 Inline Parameter Syntax 75
11.5.4.2 Function overload resolution 76
11.5.5 Actions 76
11.5.5.1 Invoking an Action 76
11.5.5.2 Action Overload Resolution 77
11.6 Asynchronous Requests 78
11.7 Batch Requests 78
11.7.1 Batch Request Headers 79
11.7.2 Request Dependencies 79
11.7.3 Identifying Individual Requests 80
11.7.4 Referencing Returned Entities 80
11.7.5 Referencing the ETag of an Entity 80
11.7.6 Referencing Values from Response Bodies 80
11.7.7 Multipart Batch Format 80
11.7.7.1 Multipart Batch Request Body 80
11.7.7.2 Referencing New Entities 82
11.7.7.3 Referencing an ETag 83
11.7.7.4 Processing a Multipart Batch Request 84
11.7.7.5 Multipart Batch Response 84
11.7.7.6 Asynchronous Batch Requests 85
12 Security Considerations 88
12.1 Authentication 88
13 Conformance 89
13.1 OData 4.0 Service Conformance Levels 89
13.1.1 OData 4.0 Minimal Conformance Level 89
13.1.2 OData 4.0 Intermediate Conformance Level 90
13.1.3 OData 4.0 Advanced Conformance Level 91
13.2 OData 4.01 Service Conformance Levels 91
13.2.1 OData 4.01 Minimal Conformance Level 91
13.2.2 OData 4.01 Intermediate Conformance Level 93
13.2.3 OData 4.01 Advanced Conformance Level 93
13.3 Interoperable OData Clients 93
Appendix A. Acknowledgments 95
Appendix B. Revision History 96
Introduction
The Open Data Protocol (OData) enables the creation of REST-based data services which allow resources, identified using Uniform Resource Locators (URLs) and defined in a data model, to be published and edited by Web clients using simple HTTP messages. This specification defines the core semantics and the behavioral aspects of the protocol.
The [OData-URL] specification defines a set of rules for constructing URLs to identify the data and metadata exposed by an OData service as well as a set of reserved URL query options.
The [OData-CSDLJSON] specification defines a JSON representation of the entity data model exposed by an OData service.
The [OData-CSDLXML] specification defines an XML representation of the entity data model exposed by an OData service.
The [OData-JSON] document specifies the JSON format of the resource representations that are exchanged using OData.
IPR Policy
This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. 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 TC’s web page (https://www.oasis-open.org/committees/odata/ipr.php).
Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
Normative References
[OData-ABNF] OData ABNF Construction Rules Version 4.01.
See link in "Additional artifacts" section on cover page.
[OData-Aggregation] OData Extension for Data Aggregation Version 4.0.
See link in "Related work" section on cover page.
[OData-CSDLJSON] OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01. See link in "Related work" section on cover page.
[OData-CSDLXML] OData Common Schema Definition Language (CSDL) XML Representation Version 4.01. See link in "Related work" section on cover page
[OData-JSON] OData JSON Format Version 4.01.
See link in "Related work" section on cover page.
[OData-URL] OData Version 4.01 Part 2: URL Conventions.
See link in "Additional artifacts" section on cover page.
[OData-VocCap] OData Vocabularies Version 4.0: Capabilities Vocabulary.
See link in "Related work" section on cover page.
[OData-VocCore] OData Vocabularies Version 4.0: Core Vocabulary.
See link in "Related work" section on cover page.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996. https://tools.ietf.org/html/rfc2046.
[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levelshttps://github.com/company/monorepo/tree/main/packages/contractshttps://github.com/company/monorepo