OData JSON Format for Common Schema Definition ... · Web viewOData JSON Format for Common Schema Definition Language (CSDL) Version 4.0 Working Draft 02 13 July 2016 Technical Committee:

OData JSON Format for Common Schema Definition Language (CSDL) Version 4.0

Working Draft 02

18 May13 July 2016

Technical Committee:OASIS Open Data Protocol (OData) TC

Chairs:Ram Jeyaraman ([email protected]), MicrosoftRalf Handl ([email protected]), SAP SE

Editors:Ralf Handl ([email protected]), SAP SEHubert Heijkers ([email protected]), IBMMike Pizzo ([email protected]), MicrosoftMartin Zurmuehl ([email protected]), SAP SE

Additional artifacts:This prose specification is one component of a Work Product that also includes: OData JSON Format for Common Schema Definition Language (CSDL) Version 4.0 (this

document) edm.json

Related work:This specification replaces or supersedes: NoneThis specification is related to: OData JSON Format Version 4.0. OASIS Standard. 24 February 2014. http://docs.oasis-

open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html. OData Version 4.0, a multi-part Work Product which includes:

OData Version 4.0 Part 1: Protocol. 24 February 2014. http://docs.oasis-open.org/odata/odata/v4.0/os/odata-v4.0-part1-protocol.html

OData Version 4.0 Part 2: URL Conventions. 24 February 2014. http://docs.oasis-open.org/odata/odata/v4.0/os/odata-v4.0-part2-url-conventions.html

OData Version 4.0 Part 3: Common Schema Definition Language (CSDL). 24 February 2014. http://docs.oasis-open.org/odata/odata/v4.0/os/odata-v4.0-part3-csdl.html

ABNF components: OData ABNF Construction Rules Version 4.0 and OData ABNF Test Cases. 14 August 2013. http://docs.oasis-open.org/odata/odata/v4.0/os/abnf/

Vocabulary components: OData Core Vocabulary, OData Measures Vocabulary and OData Capabilities Vocabulary. 24 February 2014. http://docs.oasis-open.org/odata/odata/v4.0/os/vocabularies/

Declared XML namespaces: None

Abstract:The Open Data Protocol (OData) is an open protocol for creating and consuming queryable and interoperable RESTful APIs in a simple and standard way. OData services are described by an entity-relationship model, and the model description is an integral part of each OData service. This document extends the specification OData Version 4.0 Part 3: Conceptual Schema Definition Language (CSDL) by defining a JSON format for representing the entity-relationship model and resulting REST resources of an OData service. This JSON format for CSDL is based on the OpenAPI Specification, which itself is based on JSON Schema.

odata-json-csdl-v4.0-wd02 Working Draft 02 13 July 2016Standards Track Draft Copyright © OASIS Open 2016. All Rights Reserved. Page 1 of 57

Ralf Handl, 03/03/16,

ODATA-907

http://docs.oasis-open.org/odata/odata/v4.0/cs01/vocabularies/

http://docs.oasis-open.org/odata/odata/v4.0/cs01/abnf/

http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part3-csdl.html

http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html

http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html

http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part1-protocol.html

http://docs.oasis-open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html

http://docs.oasis-open.org/odata/odata-json-format/v4.0/os/odata-json-format-v4.0-os.html

https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/edm.json

http://www.sap.com/

mailto:[email protected]

http://www.microsoft.com/


http://www.ibm.com/


http://www.sap.com/


http://www.sap.com/


http://www.microsoft.com/


https://www.oasis-open.org/committees/odata/

Status:This Working Draft (WD) has been produced by one or more TC Members; it has not yet been voted on by the TC or approved as a Committee Draft (Committee Specification Draft or a Committee Note Draft). The OASIS document Approval Process begins officially with a TC vote to approve a WD as a Committee Draft. A TC may approve a Working Draft, revise it, and re-approve it any number of times as a Committee Draft.

URI patterns:Initial publication URI:http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/csd01/odata-json-csdl-v4.0-csd01.doc Permanent “Latest version” URI:http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/odata-json-csdl-v4.0.doc Permanent link to latest version of edm.json:http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/edm.json

(Managed by OASIS TC Administration; please don’t modify.)

Copyright © OASIS Open 2016. 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.


https://www.oasis-open.org/policies-guidelines/ipr

http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/edm.json

http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/odata-json-csdl-v4.0.doc

http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/csd01/odata-json-csdl-v4.0-csd01.doc

https://www.oasis-open.org/policies-guidelines/tc-process#standApprovProcess

https://www.oasis-open.org/policies-guidelines/tc-process#committeeDraft

https://www.oasis-open.org/policies-guidelines/tc-process#dWorkingDraft

Table of Contents1 Introduction......................................................................................................................................... 5

1.1 Terminology....................................................................................................................................... 51.2 Normative References....................................................................................................................... 51.3 Non-Normative References...............................................................................................................51.4 Typographical Conventions...............................................................................................................7

2 CSDL JSON Format Design...............................................................................................................82.1 Design Goals..................................................................................................................................... 82.2 Design Principles............................................................................................................................... 8

3 Requesting the CSDL JSON Format...................................................................................................94 CSDL JSON Documents...................................................................................................................10

4.1 Keyword x-odata-version.........................................................................................................104.2 Keyword swagger..........................................................................................................................104.3 Keyword info................................................................................................................................. 104.4 Keywords schemes, host, and basePath....................................................................................114.5 Keywords consumes and produces.............................................................................................114.6 Keyword tags................................................................................................................................. 114.7 Keyword parameters....................................................................................................................124.8 Keyword responses......................................................................................................................134.9 Keyword paths............................................................................................................................... 13

4.9.1 Entity Sets................................................................................................................................ 134.9.1.1 Query a Collection of Entities..............................................................................................................144.9.1.2 Create an Entity..................................................................................................................................164.9.1.3 Retrieve an Entity................................................................................................................................174.9.1.4 Update an Entity.................................................................................................................................184.9.1.5 Delete an Entity...................................................................................................................................194.9.1.6 Invoke Bound Actions and Bound Functions......................................................................................20

4.9.2 Singletons................................................................................................................................ 204.9.2.1 Retrieve a Singleton............................................................................................................................204.9.2.2 Update a Singleton.............................................................................................................................21

4.9.3 Action Imports.......................................................................................................................... 224.9.4 Function Imports......................................................................................................................22

4.10 Keyword definitions................................................................................................................234.10.1 Entity Types and Complex Types...........................................................................................244.10.2 Properties............................................................................................................................... 25

4.10.2.1 Primitive Properties...........................................................................................................................254.10.2.2 Complex Properties......................................................................................................................29304.10.2.3 Navigation Properties........................................................................................................................304.10.2.4 Collection-Valued Properties............................................................................................................314.10.2.5 Nullable Properties........................................................................................................................3132

4.10.3 Enumeration Types................................................................................................................324.10.4 Type Definitions.................................................................................................................3334

4.11 Keywords x-actions and x-functions...................................................................................344.12 Keyword x-entityContainer...................................................................................................35


4.13 Keyword x-terms........................................................................................................................ 364.14 Keyword x-schemas.................................................................................................................... 374.15 Keyword x-references..........................................................................................................3738

4.15.1 Keyword includeAnnotations..........................................................................................384.16 Annotations................................................................................................................................... 38

4.16.1 Keyword annotations.....................................................................................................38394.16.2 Inline Annotations...................................................................................................................39

4.16.2.1 Constant Expressions.......................................................................................................................394.16.2.2 Path Expressions..........................................................................................................................39404.16.2.3 Collection Expressions......................................................................................................................404.16.2.4 Record Expressions..........................................................................................................................404.16.2.5 Comparison and Logical Operators and If Expression...................................................................404.16.2.6 Expression Apply........................................................................................................................40414.16.2.7 Expressions Cast and IsOf............................................................................................................414.16.2.8 Expression LabeledElement.........................................................................................................414.16.2.9 Expression LabeledElementReference..................................................................................41424.16.2.10 Expression Not...............................................................................................................................424.16.2.11 Expression Null.............................................................................................................................424.16.2.12 Expression UrlRef....................................................................................................................42434.16.2.13 Annotation Core.Description...............................................................................................4243

5 Extensions to the OpenAPI Specification..........................................................................................445.1 The edm.json Document...............................................................................................................445.2 Keywords......................................................................................................................................... 445.3 Formats........................................................................................................................................... 44

6 Extensibility....................................................................................................................................... 467 CSDL Examples................................................................................................................................ 47

7.1 Products and Categories Example..................................................................................................477.2 Annotations for Products and Categories Example.........................................................................52

8 Conformance..................................................................................................................................... 548.1 OData Service Conformance...........................................................................................................548.2 OData Client Conformance.............................................................................................................54

Appendix A. Acknowledgments............................................................................................................55Appendix B. Revision History...............................................................................................................56


1 IntroductionOData services are described in terms of an Entity Data Model (EDM). [OData-CSDL] defines an XML representation of the entity data model exposed by an OData service. This document defines an alternative representation using the JavaScript Object Notation (JSON), see [RFC7159].Instead of inventing an OData-specific JSON format for describing OData services the JSON representation of an entity data model is based in the OpenAPI Specification Version 2.0 (see [OpenAPI]). The OpenAPI Specification is a project used to describe and document RESTful APIs. It defines a set of JSON or YAML files required to describe such an API. These files can then be used by various tools to display the API, test the API, or generate clients in various programming languages. The OpenAPI Specification is extensible and allows adding keywords and formats for CSDL concepts that do not correspond to or aren’t fully covered by OpenAPI Specification concepts.

1.1 TerminologyThe 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].

1.2 Normative References[OData-CSDL] OData Version 4.0 Part 3: Common Schema Definition Language (CSDL).

See link in “Related work” section on cover page.[OData-JSON] OData JSON Format Version 4.0.

See link in “Related work” section on cover page.[OData-Protocol] OData Version 4.0 Part 1: Protocol.

See link in “Additional artifacts” section on cover page.[OData-URL] OData Version 4.0 Part 2: URL Conventions.

See link in "Related work" section on cover page.[OData-VocCore] OData Core Vocabulary.

See link in "Related work" section on cover page.[OData-VocCap] OData Capabilities Vocabulary.

See link in "Related work" section on cover page.[OpenAPI] OpenAPI Specification Version 2.0,

https://openapis.org/specification.[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP

14, RFC 2119, March 1997. http://www.ietf.org/rfc/rfc2119.txt. [RFC7159] Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format”,

RFC 7159, March 2014. http://tools.ietf.org/html/rfc7159.

1.3 Non-Normative References[ECMAScript] ECMAScript Language Specification Edition 5,1. June 2011. Standard ECMA-

262. http://www.ecma-international.org/publications/standards/Ecma-262.htm. [JS-Core] JSON Schema: core definitions and terminology.

http://tools.ietf.org/html/draft-zyp-json-schema-04. [JS-Validation] JSON Schema: interactive and non interactive validation.

http://tools.ietf.org/html/draft-fge-json-schema-validation-00. [XML-Schema-2] W3C XML Schema Definition Language (XSD) 1.1 Part 2: DatatypesW3C XML

Schema Definition Language (XSD) 1.1 Part 2: Datatypes, D. Peterson, S. Gao,


http://tools.ietf.org/html/draft-fge-json-schema-validation-00

http://tools.ietf.org/html/draft-zyp-json-schema-04

http://www.ecma-international.org/publications/standards/Ecma-262.htm

http://tools.ietf.org/html/rfc7159

http://www.ietf.org/rfc/rfc2119.txt

https://openapis.org/specification

https://d.docs.live.net/17ea5a0da4145c51/OData/odata-json-csdl-v4.0-wd01-old.docx#rfc2119

C. M. Sperberg-McQueen, H. S. Thompson, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 5 April 2012, http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/.Latest version available at http://www.w3.org/TR/xmlschema11-2/.


http://www.w3.org/TR/xmlschema11-2/

http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/

http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/

1.4 Typographical ConventionsKeywords defined by this specification use this monospaced font.

Normative source code uses this paragraph style.

Some sections of this specification are illustrated with non-normative examples.

Example 1: text describing an example uses this paragraph style

Non-normative examples use this paragraph style.

All examples in this document are non-normative and informative only.All other text is normative unless otherwise labeled.


2 CSDL JSON Format Design2.1 Design GoalsThe goals and guiding design principles are

CSDL JSON documents are valid OpenAPI Specification files CSDL JSON documents contain the same information as CSDL XML documents defined in

[OData-CSDL] CSDL JSON uses OpenAPI Specification concepts as much as possible CSDL JSON uses [OData-JSON] concepts where it goes beyond the OpenAPI Specification JSON.parse() of CSDL JSON documents creates JavaScript object graphs that

o Appeal to JavaScript programmers by following common naming conventions

o Satisfy basic access patterns

o Can easily be augmented with client-side post-processing to satisfy more sophisticated access patterns

2.2 Design PrinciplesTo achieve the design goals the following principles were applied:

Structure-describing CSDL elements (structured types, type definitions, enumerations) are translated into OpenAPI Schema Objects within the OpenAPI Definitions Object

Attributes and child elements of structure-describing CSDL elements that cannot be translated into OpenAPI Specification constructs are added as extension keywords to the target OpenAPI Specification constructs

The entity container is translated into an OpenAPI Paths Object All other CSDL elements are translated into JSON with a consistent set of rules

o Element and attribute names in UpperCamelCase are converted to lowerCamelCase, and uppercase attribute names are converted to lowercase

o Elements that can occur at most once within a parent become name/value pairso Elements that can occur more than once within a parent and can be uniquely identified

within their parent (schemas, key properties, entity sets, …) become a name/value pair with pluralized name and a "dictionary" object as value containing one name/value pair per element with the identifier as name

o Elements that can occur more than once within a parent and cannot be uniquely identified within their parent (action overloads, function overloads, …) become a name/value pair with pluralized name and an array as value containing one item per child element


3 Requesting the CSDL JSON FormatThe CSDL JSON format can be requested in Metadata Document Requests (see [OData-Protocol]) using the $format query option in the request URL with the MIME type application/openapi+json, optionally followed by format parameters.Alternatively, this format can be requested using the Accept header with the MIME type application/openapi+json, optionally followed by format parameters.

If specified, $format overrides any value specified in the Accept header.

Possible format parameters are: IEEE754Compatible

These are defined in [OData-JSON].



To be confirmed, see https://github.com/OAI/OpenAPI-Specification/issues/110

4 CSDL JSON DocumentsA CSDL JSON document is represented as an OpenAPI Specification document with additional keywords.In addition to the keywords swagger, info and paths required by the OpenAPI Specification it a CSDL JSON document MUST contain the name/value pairkeyword x-odata-version, .

It MAY contain any keyword defined by the OpenAPI Specification, especially the definitions keyword, and it MAY contain the name/value pairskeywords x-actions, x-functions, x-terms, x--entityContainer, x-schemas, and x-references.

The value of x-odata-version is the string "4.0".

Example 2: Structure of a CSDL document

{ "x-odata-version":"4.0", "swagger":"2.0", "info": …, "paths": …, "definitions": …, "x-actions": …, "x-functions": …, "x-terms": …, "x-entityContainer": …, "x-schemas": …, "x-references": …}

4.1 Keyword x-odata-versionThe value of x-odata-version is the string "4.0".

4.2 Keyword swaggerThe value of swagger is the string "2.0".

4.3 Keyword infoThe value of info is an Info Object, see [OpenAPI]. It MUST contain the keywords title and version, and it SHOULD contain the keyword description.

The value of title SHOULD be the value of the annotation Core.Description (see [OData-VocCore]) of the main schema or the entity container of the CSDL document.The value of version SHOULD be the value of the annotation Core.SchemaVersion (see [OData-VocCore]) of the main schema.The value of description SHOULD be the value of the annotation Core.LongDescription (see [OData-VocCore]) of the main schema or the entity container.

Example 3: Info Object – note that description accepts Markdown format

"info":{ "title":"OData Service for namespace ODataDemo", "version":"0.1.0",


Handl, Ralf, 07/05/16,

ODATA-925, not yet published

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#infoObject

"description":"This OData service is located at http://localhost/service-root/\n\n## References\n- [Org.OData.Core.V1](http://localhost/swagger-ui/?url=http://localhost/examples/Org.OData.Core.V1.openapi.json)\n- [Org.OData.Measures.V1](http://localhost/swagger-ui/?url=http://localhost/examples/Org.OData.Measures.V1.openapi.json)"}

4.4 Keywords schemes, host, and basePathThe value of schemes is an array of strings. If present it MUST contain an item with the scheme component of the service root URL.The value of host is a string. If present it MUST be the authority component of the service root URL.

The value of basePath is a string. If present it MUST be the path component of the service root URL.

Example 4: service root URL

"schemes": [ "http"],"host":"localhost","basePath":"/service-root"

4.5 Keywords consumes and producesThe values of consumes and produces are arrays of strings. If present they MUST contain an item for each media type listed in the Capabilities.SupportedFormats annotation (see [OData-VocCap]) on the entity container.

Example 5: supported formats

"consumes":[ "application/json"],"produces":[ "application/json"]

4.6 Keyword tagsThe value of tags is an array of Tag Objects, see [OpenAPI]. Tags are used for logical grouping of operations. For an OData service the natural groups are entity sets and singletons, so the tags array SHOULD contain one Tag Object per entity set and singleton in the entity container.A Tag Object MUST contain the keyword name, whose value SHOULD be the name of the entity set or singleton, and it MAY contain the keyword description, whose value SHOULD be the value of the annotation Core.Description of the entity set or singleton.

The tags array MAY contain additional Tag Objects for other logical groups, e.g. for action imports or function imports that are not associated with an entity set.

Example 6: tags with optional descriptions

"tags":[ { "name": "Products" }, { "name": "Categories", "description": "Product Categories" },


https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#tagObject




{ "name": "Suppliers" }, { "name": "MainSupplier", "description": "Primary Supplier" }, { "name": "Countries" }]

4.7 Keyword parametersThe value of parameters is a Parameters Definitions Object, see [OpenAPI]. It allows defining query options and headers that can be reused across operations of the service.It SHOULD contain one name/value pair per OData system query option supported by the service. Alternatively operation descriptions can reference the parameter definitions in the edm.json document.

Example 7: reusable query options

"parameters": { "top": { "name": "$top", "type": "integer", "in": "query", "description": "Show only the first n items, see [OData Paging - Top](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398306)" }, "skip": { "name": "$skip", "type": "integer", "in": "query", "description": "Skip the first n items, see [OData Paging - Skip](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398307)" }, "count": { "name": "$count", "type": "boolean", "in": "query", "description": "Include count of items, see [OData Count](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398308)" }, "filter": { "name": "$filter", "type": "string", "in": "query", "description": "Filter items by property values, see [OData Filtering](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398301)" }, "search": { "name": "$search", "type": "string", "in": "query", "description": "Search items by search phrases, see [OData Searching](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398309)" }


https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parametersDefinitionsObject

}

4.8 Keyword responsesThe value of responses is a Responses Definitions Object, see [OpenAPI]. It allows defining responses that can be reused across operations of the service.It SHOULD contain one name/value pair for the standard OData error response that is referenced from all operations of the service. Alternatively operation descriptions can directly reference the odata.error schema in the edm.json document.

Example 8: reusable error response referencing the odata.error schema in edm.json

"responses": { "error": { "description": "Error", "schema": { "$ref": "https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/spec/schemas/edm.json#/definitions/odata.error" } }}

4.9 KeywOpenAPI ord pPaths ObjectThe value of paths is a Paths Object, see [OpenAPI]. It is the main source of information on how to use the described API. It consists of name/value pairs whose name is a path template relative to the service root URL, and whose value is a Path Item Object, see [OpenAPI].Due to the power and flexibility of OData a full representation of all service capabilities in the Paths ObjectPaths Object is typically not feasible, so this specification only describes the minimum information required in the Paths ObjectPaths Object. Service Iimplementations are free allowed – and in fact encouraged – to add additional information that is deemed useful for the intended target audience of the OpenAPI description of that service, leveraging the documentation features of the OpenAPI Specification, especially and not limited to human-readable descriptions. The extension keyword x-entityContainer contains a full description of the OData entity container.The minimum information to be included in the Paths Object Paths object is described in the remainder of this section. Each entity set, singleton, action import, and function import is represented as one or more name/value pairs within the OpenAPI Paths Object, see [OpenAPI], section Paths Object.The OpenAPI Paths Object Paths Object SHOULD reflect the resources and capabilities of the service as closely as possible, i.e. only list supported operations and query options.

Example 9: paths for entity sets, individual entities, singletons, action imports, and function imports

"paths": { "/Products": …, "/Products('{ID}')": …, "/Categories": …, "/Categories({ID})": …, "/Suppliers": …, "/Suppliers('{ID}')": …, "/MainSupplier": …, "/Countries": …, "/Countries('{Code}')": …, "/ProductsByRating(Rating={Rating})": …}



Replace with latest-version link to edm.json

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathsObject

http://swagger.io/specification/#pathsObject





https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathItemObject

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#pathTemplating


https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesDefinitionsObject

4.9.1 Entity SetsEach entity set is represented as a name/value pair whose name is the service-relative resource path of the entity set prepended with a forward slash, and whose value is an OpenAPI Path Item Object, see [OpenAPI].Each entity set that is indexable by key is additionally represented as a name/value pair whose name is the path template for key access, with path parameters for the key values, and whose value is a Path Item Object describing the allowed operations on individual entities of this set. If the service defines bound actions or functions applicable to the entity set or its entities, these MAY be described as additional name/value pairs with corresponding path templates for action/function invocation.

4.9.1.1 Query a Collection of EntitiesThe Path Item Object for the entity set SHOULD contain the keyword get with an Operation Object as value that describes the capabilities for querying the entity set. The tags array of the Operation Object – as well as all other Operation Objects described in this section – SHOULD include the entity set name.

Example 10: GET operation for an entity set – summary and tags

"/Products": { "get": { "summary": "Get entities from Products", "tags": [ "Products" ],

The parameters array SHOULD contain Parameter Objects for system query options allowed for this entity set, and it SHOULD NOT list system query options not allowed for this entity set.

Example 11: GET operation for an entity set - parameters

"parameters": [ { "$ref": "#/parameters/top" }, { "$ref": "#/parameters/skip" }, { "$ref": "#/parameters/search" }, { "$ref": "#/parameters/filter" }, { "$ref": "#/parameters/count" },

Note: the syntax of the system query options $expand, $select, and $orderby is too flexible to be formally described with OpenAPI Specification means, yet the typical use cases of just providing a comma-separated list of properties can be expressed via an array-valued parameter with an enum constraint, as shown in the following example. This makes it easy to try out these system query options in OpenAPI tools.

Example 12: GET operation for an entity set – more specific parameters

{ "name": "$expand", "in": "query",


https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#parameterObject

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#operationObject







"description": "Expand related entities, see [OData Expand](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398298)", "type": "array", "uniqueItems": true, "items": { "type": "string" }, "enum": [ "*", "Category", "Supplier" ] }, { "name": "$select", "in": "query", "description": "Select properties to be returned, see [OData Select](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398297)", "type": "array", "uniqueItems": true, "items": { "type": "string" }, "enum": [ "ID", "Description", "ReleaseDate", "DiscontinuedDate", "Rating", "Price", "Currency" ] }, { "name": "$orderby", "in": "query", "description": "Order items by property values, see [OData Sorting](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398305)", "type": "array", "uniqueItems": true, "items": { "type": "string" }, "enum": [ "ID", "ID desc", "Description", "Description desc", "ReleaseDate", "ReleaseDate desc", "DiscontinuedDate", "DiscontinuedDate desc", "Rating", "Rating desc", "Price", "Price desc", "Currency", "Currency desc" ] }


],

The value of responses is a Responses Object, see [OpenAPI]. It SHOULD contain a name/value pair for the success case (HTTP response code 200) describing the structure of a successful response, referencing the schema of the entity set’s entity type in the global definitions. In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 13: GET operation for an entity set - responses

"responses": { "200": { "description": "Retrieved entities", "schema": { "type": "object", "title": "Collection of Product", "properties": { "value": { "type": "array", "items": { "$ref": "#/definitions/ODataDemo.Product" } } } } }, "default": { "$ref": "#/responses/error" } } } },

4.9.1.2 Create an EntityIf the entity set allows inserts, the Path Item Object SHOULD contain the keyword post with an Operation Object as value that describes the capabilities for creating new entities. The tags array of the Operation Object SHOULD include the entity set name.The parameters array MUST contain a Parameter Objects for the request body that SHOULD reference the schema of the entity set’s entity type in the global definitions.

The responses object SHOULD contain a name/value pair for the success case (HTTP response code 201) describing the structure of the success response, referencing the schema of the entity set’s entity type in the global definitions. If the service supports the preference return=minimal, it SHOULD contain a name/value pair for the HTTP response code 204. In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 14: POST operation for an entity set

"post": { "summary": "Add new entity to Products", "tags": [ "Products" ], "parameters": [ { "name": "Product", "in": "body", "description": "New entity", "schema": {






https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responsesObject

"$ref": "#/definitions/ODataDemo.Product" } } ], "responses": { "201": { "description": "Created entity", "schema": { "$ref": "#/definitions/ODataDemo.Product" } }, "default": { "$ref": "#/responses/error" } } } }}

4.9.1.3 Retrieve an Entitydescribing the GET operation of that entity set. If the entity set allows inserts, the OpenAPI Path Item Object also describes the POST operation for inserting new entities. The OpenAPI Operation Objects describing the operations SHOULD refer to the types defined in the OpenAPI Definitions object, see section .Each entity set that is indexable by key is additionally represented as a name/value pair whose name is the path template for key access, with path parameters for the key values, and whose value is an OpenAPI Path Item Object describing the allowed operations on entities of this set. The Path Item Object for individual entities in the entity set SHOULD contain the keyword get with an Operation Object as value that describes the capabilities for retrieving a single entity. The tags array of the Operation Object SHOULD include the entity set name.

Example 15: GET operation for an individual entity

"/Products('{ID}')": { "get": { "summary": "Get entity from Products by key", "tags": [ "Products" ],

The parameters array MUST contain a Parameter Object for each key property, and it SHOULD contain specific Parameter Objects for the system query options $select and $expand if these are allowed.

The Parameter Objects OpenAPI Parameter Objects describing the allowed key values MUST use the same type mapping as described for primitive properties in section 4.10.2.1, with the exception that for key properties of type Edm.Decimal the OpenAPI type keyword has the value "number".

Example 16: GET operation for an individual entity - parameters

"parameters": [ { "name": "ID", "in": "path", "required": true, "description": "key: ID", "type": "string" }, { "name": "$select", "in": "query",








"description": "Select properties to be returned, see [OData Select](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398297)", "type": "array", "uniqueItems": true, "items": { "type": "string" }, "enum": [ "ID", "Description", "ReleaseDate", "DiscontinuedDate", "Rating", "Price", "Currency" ] }, { "name": "$expand", "in": "query", "description": "Expand related entities, see [OData Expand](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398298)", "type": "array", "uniqueItems": true, "items": { "type": "string" }, "enum": [ "*", "Category", "Supplier" ] } ],

The responses object SHOULD contain a name/value pair for the success case (HTTP response code 201) describing the structure of the success response, referencing the schema of the entity set’s entity type in the global definitions. In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 17: GET operation for an individual entity - responses

"responses": { "200": { "description": "Retrieved entity", "schema": { "$ref": "#/definitions/ODataDemo.Product" } }, "default": { "$ref": "#/responses/error" } } } },


4.9.1.4 Update an EntityIf the entity set allows updates, the Path Item Object for individual entities in the entity set SHOULD contain the keyword patch with an Operation Object as value that describes the capabilities for updating entities. The tags array of the Operation Object SHOULD include the entity set name.

The parameters array MUST contain a Parameter Object for each key property, using the same type mapping as described for primitive properties in section 4.10.2.1, with the exception that for key properties of type Edm.Decimal the type keyword has the value "number".

The responses object SHOULD contain a name/value pair for the success case (HTTP response code 204). If the service supports the preference return=representation, it SHOULD contain a name/value pair for the HTTP response code 200 describing the structure of the success response, referencing the schema of the entity set’s entity type in the global definitions. In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 18: PATCH operation for an individual entity

"patch": { "summary": "Update entity in Products", "tags": [ "Products" ], "parameters": [ { "name": "ID", "in": "path", "required": true, "description": "key: ID", "type": "string" }, { "name": "Product", "in": "body", "description": "New property values", "schema": { "$ref": "#/definitions/ODataDemo.Product" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/responses/error" } } } },

4.9.1.5 Delete an EntityIf the entity set allows deletion of entities, the Path Item Object for individual entities in the entity set SHOULD contain the keyword delete with an Operation Object as value that describes the capabilities for deleting entities. The tags array of the Operation Object SHOULD include the entity set name.

The parameters array MUST contain a Parameter Object for each key property, using the same type mapping as described for primitive properties in section 4.10.2.1, with the exception that for key properties of type Edm.Decimal the type keyword has the value "number".










The responses object SHOULD contain a name/value pair for the success case (HTTP response code 204). In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 19: DELETE operation for an individual entity

"delete": { "summary": "Delete entity from Products", "tags": [ "Products" ], "parameters": [ { "name": "ID", "in": "path", "required": true, "description": "key: ID", "type": "string" }, { "name": "If-Match", "in": "header", "description": "ETag", "type": "string" } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/responses/error" } } } }}

[4.1.1.1] Invoke Bound Actions and Bound FunctionsIf the service defines bound actions or functions applicable to the entity set or its entities, these MAY be described as additional name/value pairs. …

Example 20: …

…

[4.1.2] All operations for an entity set SHOULD be tagged with the name of the entity set for consistent grouping in OpenAPI tools.Singletons

Each singleton is represented as a name/value pair whose name is the service-relative resource path of the singleton prepended with a forward slash, and whose value is Path Item Object an OpenAPI Path Item Object describing the allowed operations on this singleton.If the service defines bound actions or functions applicable to singleton, these MAY be described as additional name/value pairs.All operations for a singleton SHOULD be tagged with the name of the entity set for consistent grouping in OpenAPI tools.



TODO: example


If the service defines bound actions or functions applicable to the singleton, these MAY be described as additional name/value pairs with corresponding path templates for action/function invocation.

4.9.1.6 Retrieve a SingletonThe Path Item Object for a singleton SHOULD contain the keyword get with an Operation Object as value that describes the capabilities for retrieving the singleton, unless the singleton is write-only. The tags array of the Operation Object SHOULD include the singleton’s name.

The parameters array SHOULD contain specific Parameter Objects for the system query options $select and $expand if these are allowed.

The responses object SHOULD contain a name/value pair for the success case (HTTP response code 200) describing the structure of the success response, referencing the schema of the singleton’s entity type in the global definitions. In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 21: GET operation for a singleton

"/MainSupplier": { "get": { "summary": "Get MainSupplier", "tags": [ "MainSupplier" ], "parameters": [ { "name": "$select", "in": "query", "description": "Select properties to be returned, see [OData Select](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398297)", "type": "array", "uniqueItems": true, "items": { "type": "string" }, "enum": [ "ID", "Name", "Address", "Concurrency" ] }, { "name": "$expand", "in": "query", "description": "Expand related entities, see [OData Expand](http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398298)", "type": "array", "uniqueItems": true, "items": { "type": "string" }, "enum": [ "*", "Products" ] } ], "responses": {






"200": { "description": "Retrieved entity", "schema": { "$ref": "#/definitions/ODataDemo.Supplier" } }, "default": { "$ref": "#/responses/error" } } },

4.9.1.7 Update a SingletonThe Path Item Object for a singleton SHOULD contain the keyword patch with an Operation Object as value that describes the capabilities for updating the singleton, unless the singleton is read-only. The tags array of the Operation Object SHOULD include the singleton’s name.

The responses object SHOULD contain a name/value pair for the success case (HTTP response code 204). If the service supports the preference return=representation, it SHOULD contain a name/value pair for the HTTP response code 200 describing the structure of the success response, referencing the schema of the singleton’s entity type in the global definitions. In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 22: PATCH operation for a singleton

"patch": { "summary": "Update MainSupplier", "tags": [ "MainSupplier" ], "parameters": [ { "name": "Supplier", "in": "body", "description": "New property values", "schema": { "$ref": "#/definitions/ODataDemo.Supplier" } } ], "responses": { "204": { "description": "Success" }, "default": { "$ref": "#/responses/error" } } }}

[4.1.3] Action ImportsEach action import is represented as a name/value pair whose name is the service-relative resource path of the action import prepended with a forward slash, and whose value is a Path Item Object containing the keyword post with an Operation Object as value that describes how to an OpenAPI Path Item Object describing the POST operation for invoke theing that action import.







If the function import specifies the EntitySet attribute, the tags array of the Operation Object SHOULD include the entity set name.… body parameter… responses

Example 23: …

…

4.9.2 Function ImportsEach funaction import is represented as one name/value pair per unbound function overload whose name is the service-relative resource path template of the function overload access, and whose value is a Path Item Object containing the keyword get with an Operation Object as value that describes how to invoke the function overload.If the function import specifies the EntitySet attribute, the tags array of the Operation Object SHOULD include the entity set name.The parameters array MUST contain a Parameter Object for each parameter of the function overload, and it SHOULD contain specific Parameter Objects for the allowed system query options.The Parameter Objects describing the allowed parameter values MUST use the same type mapping as described for primitive properties in section 4.10.2.1, with the exception that for parameters of type Edm.Decimal the type keyword has the value "number".

an OpenAPI Path Item Object describing the POST operation for invoking that action import. For each function parameter the resource path template MUST either contain a path parameter for the function parameter value, or contain a parameter alias for deferring the function parameter values into the query part of the request URL, in which case the Operation Object for the GET operation MUST define a corresponding query parameter.… structured and array-valued parametersThe responses object SHOULD contain a name/value pair for the success case (HTTP response code 200) describing the structure of the success response, ideally by referencing an appropriate schema in the global definitions. In addition it SHOULD contain a default name/value pair for the OData error response, ideally referencing the global responses.

Example 24: function import

"/ProductsByRating(Rating={Rating})": { "get": { "summary": "Invoke function ProductsByRating", "tags": [ "Products" ], "parameters": [ { "name": "Rating", "in": "path", "required": true, "type": "integer", "x-nullable": true, "format": "int32" } ], "responses": { "200": { "description": "Success", "schema": { "title": "Result",



Elaborate


TODO: example









"type": "object", "properties": { "value": { "type": "array", "items": { "$ref": "#/definitions/ODataDemo.Product" } } } } }, "default": { "$ref": "#/responses/error" } } } }}

4.10 Keyword TypesdefinitionsThe value of definitions is a Definitions Object, see [OpenAPI]. Each entity type, complex type, enumeration type, and type definition defined in the CSDL document is represented as a name/value pair within of the OpenAPI Definitions Object, see [OpenAPI], section Definitions Object.The name of each pair is the namespace-qualified name of the type. It uses the namespace instead of the alias because these definitions can be reused by other CSDL documents, and aliases are document-local, so they are meaningless for referencing documents.The value of each pair is an OpenAPI Schema Object, see [OpenAPI], section Schema Object.

Example 25: Definitions

"definitions":{ "ODataDemo.Product": …, "ODataDemo.Category": …, "ODataDemo.Supplier": …, "ODataDemo.Country": …, "ODataDemo.Address": …, "org.example.Employee": …, "org.example.Manager": …}

4.10.1[4.1.4] Entity Types and Complex TypesA structured type without a base type is represented as a Schema Object Schema Object of type object.

A structured type with a base type is represented as a Schema Object that Schema Object contains the keyword allOf whose value is an array with two items: a JSON Reference to the definition of the base type, and a Schema ObjectSchema Object describing the derived type. In addition it contains a name/value pair x-baseType whose value is the namespace-qualified name of the base type.

The Schema ObjectSchema Object describing the (derived) type contains the standard OpenAPI Specification keywords appropriate for type object. It MUST NOT contain the additionalProperties keyword in order to allow additional properties beyond the declared properties. This is necessary for inheritance as well as annotations and dynamic properties, and is in line with the model versioning rules defined in [OData-Protocol].In addition it MAY contain name/value pairsthe extension keywords x-abstract and x-openType, and for entity types also x-mediaEntity and x-keys.


https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject




http://swagger.io/specification/#schemaObject


http://swagger.io/specification/#definitionsObject

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#definitionsObject

The x-abstract, x-openType, and x-mediaEntity name/valuekeywords pairs have Boolean values. If not present, their value is false. They correspond to the Abstract, OpenType, and HasStream attributes defined in [OData-CSDL].The value of x-keys is an array with one item per key property. An array is used to preserve the order of the key properties. If the key property has a key alias, the item is an object with one name/value pair, the name is the key alias and the value is the property path. For abstract entity types that neither specify a base type nor a key the value of x-keys is an empty array.

The Schema ObjectSchema Object MAY contain an the keyword x-annotations name/value pair whose value is an object containing annotations.

Example 26: Product entity type

"ODataDemo.Product":{ "type":"object", "x-mediaEntity":true, "x-keys":[ "ID" ], "properties": …, …}

Example 27: Manager entity type inheriting from Employee

"org.example.Manager":{ "type":"object", "x-baseType":"org.example.Employee", "allOf":[ { "$ref":"#/definitions/org.example.Employee" }, { … } ]}

Example 28: Category entity type with key alias

"org.example.Category18": { "type": "object", "x-keys": [ { "EntityInfoID": "Info/ID" } ], …}

4.10.2[4.1.5] PropertiesEach structural property and navigation property is represented as a name/value pair of the standard OpenAPI properties object. The name is the property name, the value is a Schema ObjectSchema Object describing the allowed values of the property.The Schema ObjectSchema Object MAY contain an the keyword x-annotations name/value pair whose value is an object containing annotations.

Example 29: structural and navigation properties of Supplier entity type

"ODataDemo.Supplier":{ …,



ODATA-911




"properties":{ "ID":…, "Name":…, "Address":…, "Concurrency":…, "Products":… }, …}

4.10.2.1[4.1.5.1] Primitive PropertiesPrimitive properties of type Edm.PrimitiveType, Edm.Stream, and any of the Edm.Geo* types are represented as Schema ObjectsSchema Objects that are JSON References to definitions in the edm.json document. JSON References to Edm.Geo* MAY contain the name/value pair x-srid with a string value. All other primitive properties are represented as a Schema ObjectSchema Object with the following OpenAPI Specification types, formats, and validation keywords:

OData Primitive Type OpenAPI Specification Comment

Type Format Keywords

Edm.Binary string base64url maxlengthx-byteLength

OData-specific formatmaxLength is maximum length of string representation, i.e. 4*ceil(MaxLength/3)

x-byteLength is the maximum length of the binary value in octets

Edm.Boolean boolean

Edm.Byte integer uint8 OData-specific format

Edm.Date string date OpenAPI format

Edm.DateTimeOffset string date-time precision OpenAPI formatOData-specific keyword

Edm.Decimal number, string

decimal minimum maximum multipleOfx-precision x-scale

OData-specific format string is needed for IEEE754Compatible modeOData-specific keywords x-precision and x-scale

Edm.Double number[,string]

double OpenAPI format with extended meaningstring is needed for -INF, INF, and NaN

Edm.Duration string duration OData-specific format

Edm.Guid string uuid OData-specific format

Edm.Int16 integer int16 OData-specific format



Consider omitting this as service can use ODATA-920 to represent -INF, INF, NaN



OData Primitive Type OpenAPI Specification Comment

Type Format Keywords

Edm.Int32 integer int32 OpenAPI format

Edm.Int64 integer, string

int64 OpenAPI formatstring is needed for IEEE754Compatible mode

Edm.SByte integer int8 OData-specific format

Edm.Single number[,string]

float OpenAPI format with extended meaningstring is needed for -INF, INF, and NaN

Edm.String string maxlength Sequence of UTF-8 characters

Edm.TimeOfDay string time x-precision

OData-specific format OData-specific keyword

Properties of type Edm.Decimal and Edm.Int64 are represented as JSON strings if the format option IEEE754Compatible=true is specified, so they have to be declared with both number and string.

Properties of type Edm.Decimal use OData-specific keywords x-precision and x-scale to represent the corresponding type facets. In addition a numeric scale value is represented with the OpenAPI Specification keyword multipleOf and a value of 10-scale. The precision is represented with the maximum and minimum keywords and a value of ±(10precision-scale - 10-scale) if the scale facet has a numeric value, and ±(10precision - 1) if the scale is variable).Properties of type Edm.Double and Edm.Single have special values for -INF, INF, and NaN that are represented as JSON strings, so they also have to be declared with both number and string. Services that do not support the special values -INF, INF, and NaN MAY omit the string keyword.

The default value of a property is represented with the OpenAPI Specification keyword default.

The Schema ObjectSchema Object describing a property MAY contain an the keyword x-annotations name/value pair whose value is an object containing annotations.

Example 30: non-nullable Boolean property with default value

"BooleanValue":{ "type":"boolean", "default":false}

Example 31: non-nullable binary property with both maxLength and byteLength

"BinaryValue":{ "type":"string", "format":"base64url", "maxLength":44, "byteLength":31, "default":"T0RhdGE"}

Example 32: non-nullable integer property

"IntegerValue":{ "type":"integer",



Consider omitting this as service can use ODATA-920 to represent -INF, INF, NaN


"format":"int32", "default":-128}

Example 33: non-nullable floating-point properties: string representation for -INF, INF, and NaN,

"DoubleValue":{ "type":[ "number", "string" ], "format":"double", "default":3.1415926535897931},"SingleValue":{ "type":[ "number", "string" ], "format":"float"}

Example 34: non-nullable decimal property with unspecified precision: no minimum and maximum

"DecimalValue":{ "type":[ "number", "string" ], "format":"decimal", "x-scale":"variable", "default":34.95}

Example 35: non-nullable decimal property with specified precision, minimum and maximum

"FixedDecimalValue":{ "type":[ "number", "string" ], "format":"decimal", "x-precision":12, "x-scale":2, "multipleOf":0.01, "minimum":-999999999.99, "maximum":999999999.99}

Example 36: non-nullable string property with maximum length of 40 characters

"StringValue":{ "type":"string", "maxLength":40 "default":"Say \"Hello\",\nthen go"}

Example 37: non-nullable date property

"DateValue":{ "type":"string", "format":"date", "default":"2012-12-03"}


Example 38: non-nullable timestamp property with 7 fractional digits precision

"DateTimeOffsetValue":{ "type":"string", "format":"date-time", "x-precision":7, "default":"2012-12-03T07:16:23:00.0000000Z"}

Example 39: non-nullable timestamp property with 12 fractional digits precision

"DurationValue":{ "type":"string", "format":"duration", "x-precision":12, "default":"P12DT23H59M59.999999999999S"}

Example 40: non-nullable time property with 3 fractional digits precision

"TimeOfDayValue":{ "type":"string", "format":"time", "x-precision":3, "default":"07:59:59.999"}

Example 41: non-nullable guid property with default value

"GuidValue":{ "type":"string", "format":"uuid", "default":"1234567-89ab-cdef-0123-456789abcdef"}

Example 42: non-nullable 8-byte integer property, allowing for string representation in IEEE754Compatible mode

"Int64Value":{ "type":[ "integer", "string" ], "format":"int64", "default":0}

Example 43: non-nullable enumeration property

"ColorEnumValue":{ "$ref":"#/definitions/Model1.Color", "default":"yellow"},

Example 44: non-nullable geography-point property

"GeographyPoint":{ "$ref":"http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/edm.json#/definitions/Edm.GeographyPoint", "default":{ "type":"Point", "coordinates":[ 142.1, 64.1 ]


}}

Example 45: non-nullable stream property: not part of payload in version 4.0

"StreamValue":{ "$ref":"http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/edm.json#/definitions/Edm.Stream"}

Example 46: non-nullable property typed with a type definition

"TypeDefValue":{ "$ref":"#/definitions/Model1.IntegerDecimal", "default":42}

Example 47: non-nullable primitive property with abstract type, e.g. in term definition

"PrimitiveValue":{ "$ref":"http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/edm.json#/definitions/Edm.PrimitiveType"}

4.10.2.2[4.1.5.2] Complex PropertiesComplex properties are represented as JSON References to the definition of the complex type, either as local references for types directly defined in the CSDL document, or as external references for types defined in referenced CSDL documents.

Example 48: structural properties of Supplier entity type: a string property, a nullable string property, a complex property, and an integer property

"properties":{ "ID":{ "type":"string" }, "Name":{ "type":[ "string", "null" ] }, "Address":{ "$ref":"#/definitions/ODataDemo.Address" }, "Concurrency":{ "type":"integer", "format":"int32" }, …}

4.10.2.3[4.1.5.3] Navigation PropertiesNavigation properties are represented similar to complex properties so that a standard OpenAPI Specification validator can validate the expanded representation of the navigation property.Navigation properties contain a the keyword x-relationship name/value pair whose value is an object that MAY contain the keywordsname/value pairs partner, onDelete, and referentialConstraints.


The value of partner is the name of the partner navigation property. The value of onDelete is an object with a single name/value pair action whose value is one of the values Cascade, None, SetDefault, or SetNull defined in [OData-CSDL], section 7.3.1.

The value of referentialConstraints is an object with one name/value pair per dependent property, using the dependend property name as name and an object as value. This object contains the name/value pairkeyword referencedProperty whose value is the name of the principal property.

In addition this object MAY contain annotations.

Example 49: multi-valued navigation property Products with partner and on-delete constraint

"Products":{ "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" }, "x-relationship":{ "partner":"Category", "onDelete":{ "action":"Cascade" } }}

Example 50: required single-valued navigation property Category

"Category":{ "anyOf":[ { "$ref":"#/definitions/ODataDemo.Category" } ], "relationship":{}}

Example 51: nullable single-valued navigation property Country with referential constraint

"Country":{ "anyOf":[ { "$ref":"#/definitions/ODataDemo.Country" }, { "type":"null" } ], "x-relationship":{ "referentialConstraints":{ "CountryName":{ "referencedProperty":"Name" } } }}

4.10.2.4[4.1.5.4] Collection-Valued PropertiesCollection-valued structural and navigation properties are represented as Schema Objects Schema Objects of type array. The value of the items keyword is a Schema ObjectSchema Object specifying the type of the items.




Example 52: collection-valued nullable string property Tags

"Tags":{ "type":"array", "items":{ "type":[ "string", "null" ] }}

Example 53: collection-valued navigation property Products of Supplier entity type

"Products":{ "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" }, "x-relationship":{ "partner":"Supplier" }}

4.10.2.5[4.1.5.5] Nullable PropertiesNullable properties of primitive types except Edm.Stream and Edm.Geo* are represented with an array-valued type that consists of the corresponding OpenAPI Specification primitive type(s) and the null type. In addition they are marked with the keyword x-nullable whose value is true.

Other nullable structural and navigation properties are represented as a Schema ObjectSchema Object as described in the preceding section, with an additional name/value pairkeyword x-nullable whose value is true.

Example 54: nullable property Price of type Edm.Decimal with precision 15 and scale 3

"Price":{ "type":["number","string","null"], "x-nullable":true, "format":"decimal", "x-precision":15, "x-scale":3, "multipleOf":1e-3, "minimum":-999999999999.999, "maximum":999999999999.999}

Example 55: nullable property Created of type Edm.DateTimeOffset with precision 6

"Created":{ "type":["string","null"], "x-nullable":true, "format":"date-time", "x-precision":6}

Example 56: nullable collection-valued property Dates

"Dates":{ "type":"array", "items":{ "type":["string","null"], "x-nullable":true,



ODATA-911


"format":"date" }},

Example 57: nullable navigation property Supplier

"Supplier":{ "$ref":"#/definitions/ODataDemo.Supplier", "x-nullable":true, "x-relationship":{ "partner":"Products" }}

4.10.3[4.1.6] Enumeration TypesAn enumeration type is represented as a Schema ObjectSchema Object of type string containing the OpenAPI Specification enum keyword. Its value is an array that contains a string with the member name for each enumeration member.If the enumeration type allows multiple members to be selected simultaneously, the Schema Object contains the keyword x-isFlags name/value pair with a value of true.

The Schema ObjectSchema Object contains an the keyword x-annotations name/value pair whose value is an object containing annotations.The numeric value of each enumeration member is represented as an annotation on the members with the term value.

Annotations on enumeration members are represented as name/value pairs whose name is the member name, followed by an at (@) sign, followed by the namespace-qualified term name, and optionally followed by a hash (#) sign and the qualifier. The annotation value is represented according to the rules defined in this specification.The x-annotations object MAY contain additional annotations.

Example 58: enumeration type with exclusive members and annotations on members and on the type

"org.example.ShippingMethod":{ "type":"string", "enum":[ "FirstClass", "TwoDay", "Overnight" ], "x-annotations":{ "[email protected]":"Shipped with highest priority", "[email protected]":"Shipped within two days", "[email protected]":"Shipped overnight" "description":"Method of shipping" }}

Example 59: enumeration type with flag values

"org.example.Pattern":{ "type":"string", "enum":[ "Plain", "Red", "Blue", "Yellow", "Solid", "Striped",




"SolidRed", "SolidBlue", "SolidYellow", "RedBlueStriped", "RedYellowStriped", "BlueYellowStriped" ], "x-isFlags":true, "x-annotations":{ "Plain@value":0, "[email protected]":1, "[email protected]":2, "[email protected]":4, "[email protected]":8, "[email protected]":16, "[email protected]":9, "[email protected]":10, "[email protected]":12, "[email protected]":19, "[email protected]":21, "[email protected]":22 }}

4.10.4[4.1.7] Type Definitions A type definition is represented as a Schema Object Schema Object describing the allowed values of the type definition using the same rules as for primitive properties.The Schema Object Schema Object MAY contain an the keyword x-annotations name/value pair whose value is an object containing annotations.

Example 60: type definitions based on Edm.String, Edm.Decimal and Edm.DateTimeOffset

"Model1.Text50":{ "type":"string", "maxLength":50},"Model1.VariableDecimal":{ "type":"number", "description":"A type definition"},"Model1.ExactTimestamp":{ "type":"string", "format":"date-time", "x-precision":12}

[4.2] Keywords x-aActions and x-fFunctionsThe x-actions and x-functions objects contain one name/value pair for each action/function name defined in the CSDL document. The name is the namespace-qualified action/function name, the value is an array with one action/function description object for each overload for this name. An action/function description object has contain the name/valuekeywords pairs entitySetPath, isBound, parameters, and returnType. Objects representing functions in addition MAY have contain the keywordan isComposable name/value pair with a Boolean value.

The value of entitySetPath is a string.

The values of isBound and isComposable are Boolean.

The value of parameters is an array with one object per parameter. It has a name/valuecontains the keyword name for the parameter name and a name/value pair the keyword parameterType whose



Remove odata. throughout the document and in the XSL transformation



value is a Schema Object schema describing the allowed parameter values. It has the same structure as the Schema Object schema for a property.The value of returnType is a Schema Object schema describing the allowed return values. It has the same structure as the Schema Object schema for a property.All objects MAY contain annotations.

Example 61: action Rejection with two overloads and function Foo with one overload and no parameters

"x-actions":{ "Model1.Rejection":[ { "isBound":true, "parameters":[ { "name":"foo", "parameterType":{ "$ref":"#/definitions/Model.One.Waldo" } } ] }, { "isBound":true, "parameters":[ { "name":"bar", "parameterType":{ "$ref":"#/definitions/Model.One.Waldo" } }, { "name":"Reason", "parameterType":{ "type":"string" } } ] } ]},"x-functions":{ "Model1.Foo":[ { "parameters":[ ], "returnType":{ "type":"string", "maxLength":42 } } ]}

[4.3] Keyword x-eEntity ContainerThe entity container of an OData service describes the top-level addressable resources of that service. From this information an OData client can construct all potentially valid URLs for that service by applying the OData URL Conventions [OData-URL].

The OpenAPI Specification offers a similar concept, the OpenAPI Paths Object, see [OpenAPI], section Paths Object.








Due to the flexibility of the OData query language and resource path construction rules it is not feasible to express all possible OData resource paths in the OpenAPI Paths Object.Consequently the entity container is represented twice: fully with the OData-specific keyword x-entityContainer, and in addition partially with the OpenAPI Specification keyword paths whose value is a Paths Object.

[4.3.1] OData Entity Container ObjectThe value of the x-entityContainer name/value pair is an object that contains the name/value pairskeywords name and resources.

The value of name is a string containing the entity container name.

The value of resources is an object with one name/value pair per entity container child. The name of each pair is the child's unqualified name, the value is an object.Each child object contains a the keyword kind name/value pair with a string value of either EntitySet, Singleton, ActionImport, or FunctionImport.

An object describing an entity set MUST have contain the keywordan entityType name/value pair whose value is the namespace-qualified name of the declared entity type of the entity set. In addition it MAY have contain the keyworda navigationPropertyBindings whosename/value pair. Its value is an object with one name/value pair per navigation property that has a binding. The name is the path to the navigation property, the value is a string with the name of the target entity set. If the target entity set is a child of the same entity container, the unqualified name is used, otherwise the namespace-qualified name.An object describing a singleton MUST have contain the keyworda type name/value pair whose value is the namespace-qualified name of the entity type of the singleton. It MAY have contain the keyworda navigationPropertyBindings name/value pair with the same structure as in objects describing an entity set.An object describing an action import MUST have contain the keywordan action name/value pair whose value is the namespace-qualfied name of the action triggered by this action import. It MAY have ancontain the keyword entitySet name/value pair whose value is the name of the entity set containing the entity or entities returned by the action.An object describing a function import MUST contain the keywordhave a function name/value pair whose value is the namespace-qualified name of the the function triggered by this function import. It MAY have acontain the keywordn entitySet name/value pair whose value is the name of the entity set containing the entity or entities returned by the function. If the function has no parameters, it also MAY have an includeInServiceDocument name/value pair with a Boolean value.

The entity container object and each entity-container child object MAY contain annotations.

Example 62: entity container object

"x-entityContainer":{ "name":"DemoService", "resources":{ "Products":{ "kind":"EntitySet", "entityType":"ODataDemo.Product", "type":"array","items":{"$ref":"…/…/ODataDemo.Product"}, "navigationPropertyBindings":{ "Category":"Categories" } }, "Categories":{ "kind":"EntitySet", "entityType":"ODataDemo.Category" }, "navigationPropertyBindings":{



Check whether using $ref here works with Swagger UI and Swagger EditorIf it works, also do it for singletons


Consider using a JSON Reference


Consider using a JSON Reference


ODATA-910

"Products":"Products" } }, "Suppliers":{ "kind":"EntitySet", "entityType":"ODataDemo.Supplier", "navigationPropertyBindings":{ "Products":"Products", "Address/Country":"Countries" }, "@Core.OptimisticConcurrency":[ { "@odata.propertyPath":"Concurrency" } ] }, "Countries":{ "kind":"EntitySet", "entityType":"ODataDemo.Country" } }, "Contoso":{ "kind":"Singleton", "type":"Self.Supplier", "navigationPropertyBindings":{ "Products":"Products" } }, "ProductsByRating":{ "kind":"FunctionImport", "entitySet":"Products", "function":"ODataDemo.ProductsByRating" } } }}

[4.4] Keyword x-tTermsThe value of Terms are represented as a name/value pair x-terms whose value is is an object containing. It contains one name/value pair per term defined within the CSDL document. The name of each pair is the term's namespace-qualified name, the value is a Schema ObjectSchema Object describing the type of the term. It has the same structure as the Schema Object schema for a property, and in addition MAY have contain the keyworda name/value pair baseTerm whose value is the namespace-qualified name of the base term, and a name/value pairthe keyword appliesTo whose value is either a string or an array of strings specifying the model element(s) the term can be applied to.All Schema ObjectsSchema Objects describing a term MAY contain annotations which are directly contained in the object Schema Object without an x-annotations wrapper.

Example 63: term definition

"x-terms":{ "Core.IsURL":{ "$ref":"#/definitions/Org.OData.Core.V1.Tag" "x-nullable":true "default": true, "appliesTo": [ "Property", "Term" ],





"description": "Properties and terms annotated with this term MUST contain a valid URL", "@Core.RequiresType": "Edm.String" }, "Core.OptimisticConcurrency": { "type": "array", "items": { "$ref": "http://docs.oasis-open.org/odata/odata-json-csdl/v4.0/edm.json#/definitions/Edm.PropertyPath" }, "appliesTo": "EntitySet", "description": "Data modification requires the use of Etags. A non-empty collection contains the set of properties that are used to compute the ETag" }, "Y.Developer":{ "$ref":"#/definitions/Y.DeveloperType" "baseTerm":"X.Person" }}

[4.5] Keyword x-sSchemasOData schemas defined or included in the CSDL document are represented with the keyword x-schemas whose value is an object that contains one name/value pair per OData schema defined or included in the CSDL document, and one name/value pair per defined alias.. For aliases the name is the alias, and the value is an object containing the keyword aliasFor whose value is the namespace if of the aliased schema.For OData schemas defined in the document the name is the namespace of the schema, and the value is an object that MAY contain the keyword annotations and that also MAY contain annotations for the schema itself.For included OData schemas the name is the namespace of the schema, and the value is an object containing the keyword uri whose value is the URI of the referenced CSDL file document describing the included schema.

Example 64: schemas

"x-schemas":{ "SomeAlias":{ "aliasFor":"Some.DocumentDefined.Model" }, "Some.Included.Schema":{ "uri":"http://host/path/Some.External.CSDL.Document" }, "AnotherAlias":{ "aliasFor":"Some.Included.Schema" }, "Some.DocumentDefined.Model":{ "annotations": …, "@Annotation.With.Some.Term": … }}

[4.6] Keyword x-r ReferencesReferences to other CSDL documents are represented with the keyword x-references whose value is an object with one name/value pair per referenced CSDL document. The name is the URI of the referenced CSDL document. Its value is an object that MAY contain the keyword includeAnnotations and that also MAY contain annotations.


Example 65: references

"x-references": { "http://tinyurl.com/Org-OData-Measures-V1": { "@Some.Term": … }, "http://somewhere/ExternalAnnotations": { "includeAnnotations": … }}

4.10.5[4.6.1] Keyword includeAnnotationsThe value of the includeAnnotations name/value pair is an object. It contains one name/value pair per included term namespace whose name is the term namespace and whose value is an array of objects. Each object in this array MAY have name/value pairs targetNamespace and qualifier. The values of these name/value pairs are strings.

Example 66: includeAnnotations

"includeAnnotations":{ "Name.Space":[ { "targetNamespace": "Target.Space" }, { "targetNamespace": "Target.Space", "qualifier": "SomeName" }, { "qualifier": "SomeName" }, {

} ]}

4.11[4.7] AnnotationsAnnotations can appear inline within a model element, or externally as a group that targets a model element.

4.11.1[4.7.1] Keyword annotationsAnnotations with external targeting are represented within their defining OData schema with the keyword annotations whose value is an object. It contains name/value pairs whose name is a path expression identifying the annotated model element and whose value is an object containing the annotations for the annotated model element in the same format that is used for inline annotations.

Example 67: Annotations with external targeting

"annotations":{ "Some.EntityType/SomeProperty":{ "@X.Y":…, … }, "Another.EntityType":{ "@X.Y":…, … }, …


}

4.11.2[4.7.2] Inline AnnotationsAnnotations are represented similar to instance annotations in [OData-JSON], chapter 18.Annotations for JSON objects are name/value pairs placed within the object, the name is an at (@) sign followed by the namespace-qualified name of the term, optionally followed by a hash (#) sign and the qualifier of the annotation.Annotations for JSON arrays or primitives are name/value pairs placed next to the name/value pair whose value is the annotated array or primitive value. The name is the name of the annotated name/value pair followed by an at (@) sign, followed by the namespace-qualified name of the term, optionally followed by a hash (#) sign and the qualifier of the annotation.

The value of the annotation is either a plain JSON value or a JSON object.

Example 68: annotation within an object, annotation of a non-object value, and annotation of an annotation

"@Some.Term" : …,"[email protected]" : …,"@Some.Term#[email protected]": …

Annotations always specify an explicit value, even if the term definition specifies a default value. This is consistent with the representation of instance annotations in JSON payloads and an intentional difference to the XML representation of annotations.

4.11.2.1[4.7.2.1] Constant ExpressionsConstant expressions edm:Bool and edm:String are represented as plain JSON values as defined in [OData-JSON], section 7.1.

Example 69

"@A.Binary":"T0RhdGE","@A.Boolean" : true,"@A.Date":"2013-10-09","@A.DateTimeOffset":"2000-01-01T16:00:00.000Z","@A.Decimal":12.34,"@A.Duration":"P7D","@An.EnumMember":"Red,Striped","@A.Float":1.23e4,"@A.Float#inf": "INF","@A.Float#minusInf":"-INF","@A.Float#nan":"NaN","@A.Guid":"86a96539-871b-45cf-b96b-93dbc235105e","@An.Int": 42"@A.String":"plain text","@A.String#withAmp":"Fast&Furious","@A.String#ToBeEscaped":"A/\"good\"\r\nstory\\for\tkids","@A.TimeOfDay":"21:45:00",

4.11.2.2[4.7.2.2] Path ExpressionsThe expressions edm:AnnotationPath, edm:NavigationPropertyPath, edm:Path, and edm:PropertyPath are represented similar to individual properties or operation responses in [OData-JSON], chapter 11, as a JSON object with a name/value pair @odata.annotationPath, @odata.navigationPath, @odata.path, or @odata.propertyPath whose value is a string containing the path expression.

Example 70: annotation with edm:Path dynamic expression

"@Org.OData.Measures.V1.ISOCurrency":{



ODATA-911

"@odata.path":"Currency"}

4.11.2.3[4.7.2.3] Collection ExpressionsThe dynamic expression edm:Collection is represented as a JSON array. Its items are representations of its child expressions according to the rules defined in this specification.

4.11.2.4[4.7.2.4] Record ExpressionsThe dynamic expression edm:Record is represented as a JSON object. The Type attribute of the edm:Record expression is represented as an @odata.type annotation. Each edm:PropertyValue child element is represented as a name/value pair with the value of the Property attribute as name. Its value expression is represented according to the rules defined in this specification. It MAY also contain annotations.

Example 71: annotation with edm:Record dynamic expression, one Boolean edm:PropertyValue and one with an edm:Collection value

"@Capabilities.UpdateRestrictions":{ "Updatable":true, "NonUpdatableNavigationProperties":[ { "@odata.navigationPropertyPath":"Supplier" }, { "@odata.navigationPropertyPath":"Category" } ]}

4.11.2.5[4.7.2.5] Comparison and Logical Operators and If ExpressionThe dynamic expression edm:If and the logical expressions edm:Eq, edm:Ne, edm:Ge, edm:Gt, edm:Le, edm:Lt, edm:And, and edm:Or are represented are represented as a JSON object with a name/value pair @odata.if, @odata.eq etc. whose value is a JSON array with items that are representations of the child expressions according to the rules defined in this specification. They MAY also contain annotations.

Example 72: edm:If expression using an edm:Path expression as its condition and evaluating to one of two edm:String expressions

"@org.example.display.DisplayName":{ "@odata.if":[ { "@odata.path":"IsFemale" }, "Female", "Male" ]}

4.11.2.6[4.7.2.6] Expression ApplyThe dynamic expression edm:Apply is represented as a JSON object with an @odata.apply name/value pair whose value is an object with a function name/value pair with the function name as its string value. The child expressions are represented as a parameterValues name/value pair whose value is an array with items that are representations of the child expressions according to the rules defined in this specification.



ODATA-911

It MAY also contain annotations.

Example 73: edm:Apply expression with two edm:String expressions and one edm:Path expression as parameter values

"@Some.Computed.Url":{ "@odata.apply":{ "function":"odata.concat", "parameterValues":[ "Products(", { "@odata.path":"ID" }, ")" ] }}

4.11.2.7[4.7.2.7] Expressions Cast and IsOfThe dynamic expressions edm:Cast and edm:IsOf are represented as JSON objects with a name/value pair @odata.cast or @odata.isOf whose value is a string with a qualified type name. The facet attributes are represented as name/value pairs maxLength, precision, scale, and srid. The child expression is represented as the value of a value name/value pair according to the rules defined in this specification.They MAY also contain annotations.

Example 74: edm:IsOf expression using an edm:Path expression as its parameter

"@For.Testing":{ "@odata.isOf":"Edm.Binary", "value":{ "@odata.path":"ImageData" }}

4.11.2.8[4.7.2.8] Expression LabeledElementThe dynamic expression edm:LabeledElement is represented as a JSON object with an @odata.labeledElement name/value pair whose value is a string with the qualified name of the labeled element. Its single child expression is represented as a value name/value pair whose value is the representation of the child expression according to the rules defined in this specification. It MAY also contain annotations.

Example 75: edm:LabeledElement expression

{ "@odata.labeledElement":"Model.MyReusableAnnotation", "value":…,}

4.11.2.9[4.7.2.9] Expression LabeledElementReferenceThe dynamic expression edm:LabeledElementReference is represented as a JSON object with an @odata.labeledElementReference name/value pair whose value is a string with the qualified name of the referenced labeled element.

Example 76: edm:LabeledElementReference expression

{


"@odata.labeledElementReference":"Model.MyReusableAnnotation"}

4.11.2.10[4.7.2.10] Expression NotThe dynamic expression edm:Not is represented as a JSON object with an @odata.not name/value pair whose value is the representation of the child expression according to the rules defined in this specification.It MAY also contain annotations.

Example 77: edm:Not expression

"@Some.Term": { "@odata.not":{ "@odata.path":"IsHappy" }}

4.11.2.11[4.7.2.11] Expression NullThe dynamic expression edm:Null can appear in positions that are represented as array items or values of name/value pairs in JSON, so it has to be represented as a single JSON primitive or object.If the dynamic expression edm:Null does not contains annotations, it is represented simply as the JSON null value.

Example 78: edm:Null expression without nested annotations

"@Some.Term":null,

If it does contain annotations, it is represented as a JSON object with an @odata.null name/value pair whose value is an object that contains the annotations.Otherwise it is represented just as the JSON null value.

Example 79: edm:Null expression with nested annotations

"@Some.Term":{ "@odata.null":{ "@Within.Null":true }}

4.11.2.12[4.7.2.12] Expression UrlRefThe dynamic expression edm:UrlRef is represented as a JSON object with an @odata.urlRf name/value pair whose value is either a string containing the URL or an object representing the non-constant child expression according to the rules defined in this specification.It MAY also contain annotations.

Example 80: edm:UrlRef expressions with edm:String value and with edm:Path value

"@Good.Reference#one":{ "@odata.urlRef":"http://www.odata.org"},"@Good.Reference#two":{ "@odata.urlRef":{ "@odata.path":"DocumentationUrl" }}



ODATA-911


ODATA-911


ODATA-911

4.11.2.13[4.7.2.13] Annotation Core.DescriptionThe annotation Core.Description (see [OData-VocCore]) semantically corresponds to the OpenAPI Specification keyword description, so unqualified annotations with Core.Description that have a constant string value are represented with this keyword. Qualified annotations and annotations with dynamic values are represented as other annotations.

Example 81: unqualified constant Core.Description as description

"org.example.Size": { "enum": [ "S", "M", "L" ], "[email protected]": "Small", "[email protected]": "Medium", "[email protected]": "Large", "description": "T-Shirt Size", "@Core.Description#alt": "Size (S, M, L)", "@Core.LongDescription": "Size, expressed with letters familiar from e.g. T-Shirt sizes", },


5 Extensions to the OpenAPI Specification5.1 The edm.json DocumentThe edm.json document defines reuse types for CSDL JSON documents as well as the syntax of the OData extension keywords.The definitions object contains one name/value pair per reuse type, e.g. the OData primitive types and the standard OData error response, as well as types used for describing the extension keywords. The properties object contains one name/value pair per extension keyword whose value is a Schema Object.The parameters object contains one name/value pair per OData system query option referring to the formal specification of that query option.

5.2 KeywordsOData CSDL contains many concepts that cannot be translated into OpenAPI concepts, these are represented using the custom keywords. On the document root level these are

x-actions x-entityContainer x-functions x-odata-version x-references x-schemas x-terms

Schema Objects of type object MAY use the keywords x-abstract x-keys x-mediaEntity x-openType x-relationship

Schema Objects for primitive types MAY use the keywords x-nullable x-precision x-scale x-srid

5.3 FormatsNot all constraints on values of OData primitive types can be expressed with OpenAPI means, and the format keyword of the OpenAPI specification allows defining new values. CSDL JSON documents use the following formats:

Format OData Type Comment

base64url Edm.Binary OData-specific format

date Edm.Date OpenAPI format, was part of JSON Schema Draft 03

decimal Edm.Decimal OData-specific format

double Edm.Double OpenAPI format extended with -INF, INF, NaN


Format OData Type Comment

duration Edm.Duration OData-specific format

int16 Edm.Int16 OData-specific format

int32 Edm.Int32 OpenAPI format

int64 Edm.Int64 OpenAPI format

int8 Edm.SByte OData-specific format

single Edm.Single OData-specific format

time Edm.TimeOfDay OData-specific format, was part of JSON Schema Draft 03

uint8 Edm.Byte OData-specific format

uuid Edm.Guid OData-specific format


6 ExtensibilityVocabularies and annotations already allow defining additional characteristics or capabilities of metadata elements, such as a service, entity type, property, function, action or parameter, and [OData-CSDL] defines which model elements can be annotated. This document specifies how these metadata annotations are represented in CSDL JSON documents.



Add new section on payload validation, ODATA-890

7 CSDL ExamplesFollowing are two basic examples of valid OData models as represented in CSDL JSON. These examples demonstrate many of the topics covered above. They represent the same documents as the XML examples in chapter 16 of [OData-CSDL].

7.1 Products and Categories Example Example 82:

{ "x-odata-version":"4.0", "swagger":"2.0", "info":{ "title":"OData Service for namespace ODataDemo", "description":"This OData service is located at http://localhost/service-root/\n\n## References\n- [Org.OData.Core.V1](http://localhost/swagger-ui/?url=http://localhost/examples/Org.OData.Core.V1.openapi.json)\n- [Org.OData.Measures.V1](http://localhost/swagger-ui/?url=http://localhost/examples/Org.OData.Measures.V1.openapi.json)", "version":"0.1.0" }, "host":"localhost", "schemes": [ "http" ], "basePath":"/service-root", "consumes":[ "application/json" ], "produces":[ "application/json" ], "definitions":{ "ODataDemo.Product":{ "type":"object", "x-mediaEntity":true, "x-keys":[ "ID" ], "properties":{ "ID":{ "type":"string" }, "Description":{ "type":[ "string", "null" ], "x-nullable":true, "x-annotations":{ "@Core.IsLanguageDependent":true } }, "ReleaseDate":{ "type":[ "string", "null" ], "x-nullable":true,


"format":"date" }, "DiscontinuedDate":{ "type":[ "string", "null" ], "x-nullable":true, "format":"date" }, "Rating":{ "type":[ "integer", "null" ], "x-nullable":true, "format":"int32" }, "Price":{ "type":[ "number", "string", "null" ], "x-nullable":true, "format":"decimal", "multipleOf":1, "x-annotations":{ "@Org.OData.Measures.V1.ISOCurrency":{ "@odata.path":"Currency" } } }, "Currency":{ "type":[ "string", "null" ], "x-nullable":true, "maxLength":3 }, "Category":{ "$ref":"#/definitions/ODataDemo.Category", "x-relationship":{ "partner":"Products" } }, "Supplier":{ "$ref":"#/definitions/ODataDemo.Supplier", "x-nullable":true, "x-relationship":{ "partner":"Products" } } } }, "ODataDemo.Category":{ "type":"object", "x-keys":[ "ID" ], "properties":{ "ID":{ "type":"integer",


"format":"int32" }, "Name":{ "type":"string", "x-annotations":{ "@Core.IsLanguageDependent":true } }, "Products":{ "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" }, "x-relationship":{ "partner":"Category", "onDelete":{ "action":"Cascade" } } } } }, "ODataDemo.Supplier":{ "type":"object", "x-keys":[ "ID" ], "properties":{ "ID":{ "type":"string" }, "Name":{ "type":[ "string", "null" ], "x-nullable":true }, "Address":{ "$ref":"#/definitions/ODataDemo.Address" }, "Concurrency":{ "type":"integer", "format":"int32" }, "Products":{ "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" }, "x-relationship":{ "partner":"Supplier" } } } }, "ODataDemo.Country":{ "type":"object", "x-keys":[ "Code" ], "properties":{ "Code":{ "type":"string",


"maxLength":2 }, "Name":{ "type":[ "string", "null" ], "x-nullable":true } } }, "ODataDemo.Address":{ "type":"object", "properties":{ "Street":{ "type":[ "string", "null" ] , "x-nullable":true }, "City":{ "type":[ "string", "null" ] , "x-nullable":true }, "State":{ "type":[ "string", "null" ] , "x-nullable":true }, "ZipCode":{ "type":[ "string", "null" ] , "x-nullable":true }, "CountryName":{ "type":[ "string", "null" ] , "x-nullable":true }, "Country":{ "$ref":"#/definitions/ODataDemo.Country", "x-nullable":true, "x-relationship":{ "referentialConstraints":{ "CountryName":{ "referencedProperty":"Name" } } } } } } }, "x-schemas":{


"Org.OData.Core.V1":{ "uri":"http://docs.oasis-open.org/odata/odata/v4.0/Org.OData.Core.V1.json" }, "Core":{ "aliasFor":"Org.OData.Core.V1" }, "Org.OData.Measures.V1":{ "uri":"http://docs.oasis-open.org/odata/odata/v4.0/Org.OData.Measures.V1.json" }, "UoM":{ "aliasFor":"Org.OData.Measures.V1" }, "ODataDemo":{ } }, "x-functions":{ "ODataDemo.ProductsByRating":[ { "parameters":[ { "name":"Rating", "parameterType":{ "type":[ "integer", "null" ] , "x-nullable":true, "format":"int32" } } ], "returnType":{ "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" } } } ] }, "x-entityContainer":{ "name":"DemoService", "resources":{ "Products":{ "kind":"EntitySet", "entityType":"ODataDemo.Product", "navigationPropertyBindings":{ "Category":"Categories" } }, "Categories":{ "kind":"EntitySet", "entityType":"ODataDemo.Category", "navigationPropertyBindings":{ "Products":"Products" } }, "Suppliers":{ "kind":"EntitySet", "entityType":"ODataDemo.Supplier", "navigationPropertyBindings":{ "Products":"Products", "Address/Country":"Countries"


}, "@Core.OptimisticConcurrency":[ { "@odata.propertyPath":"Concurrency" } ] }, "MainSupplier":{ "kind":"Singleton", "type":"ODataDemo.Supplier", "navigationPropertyBindings":{ "Products":"Products" } }, "Countries":{ "kind":"EntitySet", "entityType":"ODataDemo.Country" }, "ProductsByRating":{ "kind":"FunctionImport", "entitySet":"Products", "function":"ODataDemo.ProductsByRating" } } }, "paths":{ "Products":{…}, "Products('{ID}'}":{…}, "Categories":{…}, "Categories({ID}}":{…}, "Suppliers":{…}, "Suppliers('{ID}'}":{…}, "MainSupplier":{…}, "Countries":{…}, "Countries('{Code}'}":{…}, "ProductsByRating(Rating={Rating}}":{…}}, "parameters":{ "top":{…}, "skip":{…}, "count":{…}, "filter":{…}, "search":{…}, … }}

7.2 Annotations for Products and Categories Example Example 83: schema Annotations contains annotations for referenced schema ODataDemo with terms from vocabulary Some.Vocabulary.V1

{ "x-odata-version":"4.0", "swagger":"2.0", "info":{ "title":"OData CSDL Document for namespace External.Annotations", "description":"\n\n## References\n- [ODataDemo](http://localhost/swagger-ui/?url=http://host/service/$metadata)\n- [Some.Vocabulary.V1](http://localhost/swagger-ui/?url=http://somewhere/Vocabulary/V1)", "version":"0.1.0" },


"x-schemas":{ "ODataDemo":{ "uri":"http://host/service/$metadata" }, "Some.Vocabulary.V1":{ "uri":"http://somewhere/Vocabulary/V1" }, "Vocabulary1":{ "aliasFor":"Some.Vocabulary.V1" }, "External.Annotations":{ "annotations":{ "ODataDemo.Supplier":{ "@Vocabulary1.EMail":null, "@Vocabulary1.AccountID":{ "@odata.path":"ID" }, "@Vocabulary1.Title":"Supplier Info", "@Vocabulary1.DisplayName":{ "@odata.apply":"odata.concat", "parameterValues":[ { "@odata.path":"Name" }, " in ", { "@odata.path":"Address/CountryName" } ] } }, "ODataDemo.Product":{ "@Self.Tags":[ "MasterData" ] } } } }, "paths":{ }}


8 ConformanceOData is designed as a set of conventions that can be layered on top of existing standards to provide common representations for common functionality. Not all services will support all of the conventions defined in the protocol; services choose those conventions defined in OData as the representation to expose that functionality appropriate for their scenarios.This extension specification defines how to describe the functionality of an OData service with the means of the OpenAPI Specification. It does not require a specific conformance level for OData services as a precondition to conform to this extension specification.

8.1 OData Service ConformanceConforming OData services MUST describe all functionality they expose according to the rules in sections 3 and 4 of this specification.If a service chooses to publish metadata at $metadata according to [OData-CSDL], its OpenAPI description MUST describe the same functionality that is described in the XML $metadata document.

8.2 OData Client ConformanceConforming OData clients MUST be able to consume OData services that use any or all of the constructs defined in sections 3 and 4 of this specification, and any or all constructs defined in the referenced version of the OpenAPI Specification [OpenAPI].



TAB-1375


TAB-1377

Appendix A. AcknowledgmentsThe contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol], are gratefully acknowledged.


Appendix B. Revision HistoryRevision Date Editor Changes Made

Committee Specification Draft 01

2015-11-20 Ralf Handl Initial version

Committee Specification Draft 02

2016-05-18 Ralf Handl Now based on OpenAPI Specification



Adapt