OData JSON Format for Common Schema Definition Language
(CSDL) Version 4.0
Working Draft 01
11 November 2014
Technical Committee:
OASIS Open Data Protocol (OData) TC
Chairs:
Ram Jeyaraman ([email protected]), Microsoft
Ralf Handl ([email protected]), SAP AG
Editors:
Ralf Handl ([email protected]), SAP AG
Hubert Heijkers ([email protected]), IBM
Mike Pizzo ([email protected]), Microsoft
Martin Zurmuehl ([email protected]), SAP AG
Additional artifacts:
This prose specification is one component of a Work Product that also includes:
 edm.json
Related work:
This specification replaces or supersedes:

None
This specification is related to:


OData JSON Format Version 4.0. OASIS Standard. 24 February 2014. http://docs.oasisopen.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.oasisopen.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.oasisopen.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.oasisopen.org/odata/odata/v4.0/os/vocabularies/
Declared XML namespaces:
 None
Abstract:
The Open Data Protocol (OData) for representing and interacting with structured content is
comprised of a set of specifications. This document extends the specification OData Version 4.0
Part 3: Conceptual Schema Definition Language (CSDL) by defining a JSON format for
representing OData CSDL documents. This JSON format for CSDL is based on JSON Schema.
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 reapprove it any number of times as a Committee Draft.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 1 of 27
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
(Managed by OASIS TC Administration; please don’t modify.)
Copyright © OASIS Open 2014. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual
Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that
comment on or otherwise explain it or assist in its implementation may be prepared, copied, published,
and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice
and this section are included on all such copies and derivative works. However, this document itself may
not be modified in any way, including by removing the copyright notice or references to OASIS, except as
needed for the purpose of developing any document or deliverable produced by an OASIS Technical
Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must
be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors
or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS
DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 2 of 27
Table of Contents
1
2
1
2
3
Introduction ........................................................................................................................................... 4
1.1 Terminology ........................................................................................................................................ 4
1.2 Normative References ........................................................................................................................ 4
1.3 Typographical Conventions ................................................................................................................ 4
JSON CSDL Format Design ................................................................................................................. 5
Requesting the JSON CSDL Format.................................................................................................... 6
CSDL Documents ................................................................................................................................. 7
2.1 Definitions ........................................................................................................................................... 7
2.1.1 Entity Types and Complex Types................................................................................................ 7
2.1.2 Properties and Navigation Properties ......................................................................................... 8
2.1.3 Enumeration Types ..................................................................................................................... 9
2.1.4 Type Definitions ........................................................................................................................... 9
2.2 Schemas ............................................................................................................................................. 9
2.2.1 Actions and Functions ............................................................................................................... 10
2.2.2 Entity Container ......................................................................................................................... 10
2.2.3 Terms ........................................................................................................................................ 10
2.2.4 Annotations................................................................................................................................ 10
2.3 References........................................................................................................................................ 13
2.3.1 Includes ..................................................................................................................................... 13
2.3.2 IncludeAnnotations .................................................................................................................... 13
The edm.json Schema ..................................................................................................................... 14
3.1 Definitions ......................................................................................................................................... 14
3.2 Keywords .......................................................................................................................................... 15
3.3 Formats ............................................................................................................................................. 15
4
Validation ............................................................................................................................................ 16
5
Extensibility......................................................................................................................................... 17
6
CSDL Examples ................................................................................................................................. 18
6.1 Products and Categories Example ................................................................................................... 18
6.2 Annotations for Products and Categories Example .......................................................................... 23
7
Conformance ...................................................................................................................................... 25
Appendix A.
Acknowledgments ............................................................................................................. 26
Appendix B.
Revision History ................................................................................................................ 27
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 3 of 27
1 Introduction
OData 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]
1.1 Terminology
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD
NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described
in [RFC2119].
1.2 Normative References
[JSON Schema]
[OData-CSDL]
[OData-JSON]
[OData-Protocol]
[OData-URL]
[RFC2119]
[RFC7159]
[ECMAScript]
JSON Schema.
http://json-schema.org/.
OData Version 4.0 Part 3: Common Schema Definition Language (CSDL).
See link in “Related work” section on cover page.
OData JSON Format Version 4.0.
See link in “Related work” section on cover page.
OData Version 4.0 Part 1: Protocol.
See link in “Additional artifacts” section on cover page.
OData Version 4.0 Part 2: URL Conventions.
See link in "Related work" section on cover page.
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.
Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format”,
RFC 7159, March 2014. http://tools.ietf.org/html/rfc7159.
ECMAScript Language Specification Edition 5,1. June 2011. Standard ECMA262. http://www.ecma-international.org/publications/standards/Ecma-262.htm.
1.3 Typographical Conventions
Keywords 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.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 4 of 27
2 JSON CSDL Format Design
JSON, as described in [RFC7159], defines a text format for serializing structured data. Objects are
serialized as an unordered collection of name-value pairs. JSON Schema, as described in
[JSON Schema], is an emerging standard that defines a JSON format for describing JSON formats.
JSON Schema is gaining traction, so we want to use it as the starting point for a JSON format for CSDL.
JSON Schema is extensible, so we can add CSDL concepts that cannot be translated into JSON Schema
concepts. The guiding design principles are

JSON CSDL is valid JSON Schema

JSON CSDL can be used to by standard JSON Schema validators to validate messages from
and to the service

JSON CSDL contains the same information as the XML format for CSDL defined in
[OData-CSDL]

JSON CSDL uses JSON Schema concepts that correspond to CSDL concepts

JSON CSDL uses [OData-JSON] concepts where it goes beyond JSON Schema

JSON.parse() of JSON CSDL creates a JavaScript object graph that
o
Appeals to JavaScript programmers by following common naming conventions
o
Satisfies basic access patterns
o
Can easily be augmented with client-side post-processing to satisfy more sophisticated
access patterns
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 5 of 27
1 Requesting the JSON CSDL Format
The JSON CSDL format can be requested in Metadata Document Requests (see [OData-Protocol])
using the $format query option in the request URL with the MIME types application/schema+json
or application/json, optionally followed by format parameters, or the case-insensitive abbreviation
json which MUST NOT be followed by format parameters.
Alternatively, this format can be requested using the Accept header with the MIME type
application/json, optionally followed by format parameters.
If specified, $format overrides any value specified in the Accept header.
Possible format parameters are:


IEEE754Compatible
odata.streaming
These are defined in [OData-JSON].
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 6 of 27
2 CSDL Documents
A CSDL document in JSON is represented as a JSON Format document with additional keywords.
It must contain a name/value pair with name $schema, and it may contain definitions, schemas, and
references.
The value of $schema is the canonical URL of the edm schema.
Example 2: Structure of CSDL document
{
"$schema" : "http://odata.org/schemas/v4.0/edm.json#",
"definitions" : …,
"schemas" : …,
"references" : …
}
2.1 Definitions
The definitions object contains one name/value pair per entity type, complex type, enumeration type,
and type definition, using 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 documentlocal, so they are meaningless for referencing documents.
Example 3: Definitions
"definitions" : {
"ODataDemo.Product" : …,
"ODataDemo.Category" : …,
"ODataDemo.Supplier" : …,
"ODataDemo.Country" : …,
"ODataDemo.Address" : …
}
2.1.1 Entity Types and Complex Types
Each structured type is represented as a name/value pair of the standard JSON Schema definitions
object. The name is the namespace-qualified name of the entity type or complex type. The value is a
JSON Schema of type object.
In addition to the standard JSON Schema name/value pairs it may contain an odata name/value pair
whose value is an object. The odata object may contain name/value pairs abstract, baseType,
hasStream, keys, kind, and openType.
The kind is either entity or complex.
The abstract, openType, and hasStream name/value pairs have Boolean values. If not present, their
value is false.
The baseType name/value pair has a string value which is the qualified name of the base type.
The value of keys is an object with one name/value pair per key property, using the key property name
as name and its alias as value. If no alias is defined, it defaults to the key property name.

Inheritance: allOf:[{$ref:base type},{schema with additional properties}]

Open types: can we use additionalProperties:false or does this conflict with allOf for inheritance?
Would have to allow instance annotations via patternProperties containing an @
The schema may contain annotations.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 7 of 27
Example 4: Product entity type
"ODataDemo.Product" : {
"type" : "object",
"odata" : {
"kind" : "entity",
"hasStream" : true,
"keys" : {
"ID" : "ID"
}
},
"properties" : …,
…
},
2.1.2 Properties and Navigation Properties
Each property and navigation property is represented as a name/value pair of the standard JSON
Schema properties object. The name is the property name; the value is a schema describing the
allowed values of the property.









Properties of type Edm.String are represented as JSON Schema primitive type string.
Properties of type Edm.Boolean are represented as JSON Schema primitive type boolean.
Properties of type Edm.Decimal are represented as JSON Schema primitive type number.
with an array-valued JSON Schema type that consists of the corresponding JSON Schema
primitive type and the JSON Schema null type.
All other primitive types are represented as JSON references to definitions in the edm.json
schema.
Complex properties are represented as JSON references to definition of the complex type, either
as local references for types defined in this CSDL document, or as external references for types
defined in referenced CSDL documents
Navigation properties are represented similar to complex properties so that a standard JSON
Schema validator can validate the expanded representation of the navigation property
Nullable properties of types Edm.String, Edm.Boolean, and Edm.Decimal are represented
Other nullable structural and navigation properties are represented by a schema using the anyOf
keyword followed by a two-element array with a schema for the non-null values and a schema for
the JSON Schema null type.
Navigation properties will contain an odata name/value pair whose value is an object. The odata object
will contain a name/value pair kind with value navigation, and may contain name/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 ptoprty name as name and an object as value. This object contains the name/value
pair referencedProperty whose value is the name of the principal property. In addition this object may
contain annotations.

DefaultValue -> default

Scale=3 -> multipleOf:1e-3

Precision=5, Scale=3 -> minimum:-99.999, maximum:99.999
The schema may contain annotations.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 8 of 27
Example 5: properties of Supplier entity type
"properties" : {
"ID" : {
"type" : "string"
},
"Name" : {
"type" : [
"string",
"null"
]
},
"Address" : {
"$ref" : "#/definitions/ODataDemo.Address"
},
"Concurrency" : {
"$ref" :
"http://odata.org/schemas/v4.0/edm.json#/definitions/Edm.Int32"
},
"Products" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/ODataDemo.Product"
},
"odata" : {
"kind" : "navigation",
"partner" : "Supplier"
}
}
}
Example 6: nullable navigation property Supplier using the anyOf keyword
"Supplier" : {
"anyOf" : [{
"$ref" : "#/definitions/ODataDemo.Supplier"
}, {
"type" : "null"
}
],
"odata" : {
"kind" : "navigation",
"partner" : "Products"
}
}
2.1.3 Enumeration Types

EnumType -> enum without type, Member and Value, null for Nullable
2.1.4 Type Definitions

Similar to primitive properties
2.2 Schemas
The value of schemas is an object with one name/value pair per defined schema. The name is the
namespace of the schema. Its value is an object with an alias name/value pair whose value is the alias
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 9 of 27
of the namespace, or null if no alias is defined. The object may contain the name/value pairs actions,
functions, and entityContainer.
It also may contain annotations.
Example 7: schemas
"schemas" : {
"Some.Model" : {
"alias" : "This",
"entityTypes" : …,
"complexTypes" : …,
"enumTypes" : …,
"typeDefinitions" : …,
"actions" : …,
"functions" : …,
"terms" : …,
"entityContainer" : …,
"@Some.Term" : …
}
2.2.1 Actions and Functions
2.2.2 Entity Container
2.2.3 Terms
2.2.4 Annotations
Annotations 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- or alias-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 the namespace- or alias-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 8: annotation within an object, annotation of a non-object value, and annotation of an annotation
"@Some.Term" : …,
"[email protected]" : …,
"@Some.Term#[email protected]": …,
The constant expressions edm:Bool, edm:Int, and edm:String are represented as plain JSON
values. The other constant expressions are represented similar to individual properties or operation
responses in [OData-JSON], chapter 11, as an object with name/value pairs @odata.type and value.
The value of @odata.type is a hash (#) sign followed by the unqualified type name, the value of value
is the OData JSON representation of the annotation value defined in [OData-JSON], section 7.1. Tagging
annotations that don't specify an explicit value are represented with an empty object as their value.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 10 of 27
Example 9: a string-valued annotation, an integer- valued annotation, a Boolean-valued annotation, a floatvalued annotation, and a tagging annotation
"@Some.Term": "A plain string value,
"[email protected]": 42,
"@Some.Term#[email protected]" : true,
"@A.Float" : {
"@odata.type" : "#Double",
"value" : 1.23e4
},
"@A.Float#inf": {
"@odata.type": "#Double",
"value": "INF"
},
"@Core.IsLanguageDependent" : {}
Dynamic expressions are represented as JSON objects
The expressions edm:AnnotationPath, edm:NavigationPropertyPath, edm:Path, and
edm:PropertyPath are represented similar to the constant expressions with a JSON object
representation, using the dynamic expression name as an abstract primitive type name:
Example 10: annotation with edm:Path dynamic expression
"@Org.OData.Measures.V1.ISOCurrency":{
"@odata.type":"#Path",
"value":"Currency"
}
The 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 specified in this section.
The dynamic expression edm:Collection is represented as a JSON array. Its items are
representations of its child expressions according to the rules specified in this section.
Example 11: annotation with edm:Record dynamic expression, one Boolean edm:PropertyValue and one
with an edm:Collection value
"@Capabilities.UpdateRestrictions":{
"Updatable":true,
"NonUpdatableNavigationProperties":[
{
"@odata.type":"#NavigationPropertyPath",
"value":"Supplier"
},
{
"@odata.type":"#NavigationPropertyPath",
"value":"Category"
}
]
},
The 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 JSON objects with
name/value pairs @odata.type and value. The value of @odata.type is a hash (#) sign followed by
the dynamic expression name, the value of value is a JSON array with items that are representations of
the child expressions according to the rules specified in this section.
Example 12: 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.type":"#If",
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 11 of 27
"value":[
{
"@odata.type":"#Path",
"value":"IsFemale"
},
"Female",
"Male"
],
},
The dynamic expression edm:Apply is represented as a JSON object with an @odata.type
name/value pair whose value is #Apply. The Function attribute is represented as a function
name/value pair with the function name as its string value. The child expressions are represented as a
value name/value pair whose value is an array with items that are representations of the child
expressions according to the rules specified in this section.
Example 13: edm:Apply expression using two edm:String expressions and one edm:Path expression as its
parameters
"@Some.Computed.Url":{
"@odata.type":"#Apply",
"function":"odata.concat",
"value":[
"Products(",
{
"@odata.type":"#Path",
"value":"ID"
},
")"
],
},
The dynamic expressions edm:Cast and edm:IsOf are represented as JSON objects with an
@odata.type name/value pair whose value is is a hash (#) sign followed by the dynamic expression
name. The Type attribute is represented as a type name/value pair. The facet attributes MaxLength,
Precision, Scale, and SRID 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 specified in this section.
Example 14: edm:IsOf expression using an edm:Path expression as its parameter
"@For.Testing":{
"@odata.type":"#IsOf",
"type":"Edm.Binary",
"value":{
"@odata.type":"#Path",
"value":"ImageData"
}
},

LabeledElement(Reference), Null, Not, UrlRef
All annotations represented as JSON objects may contain annotations.

Core.Description -> title, Core.LongDescription -> description?

<edm:Annotations> element
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 12 of 27
2.3 References
The value of references is an object with one name/value pair per referenced CSDL document. The
name is the URI of the CSDL document. Its value is an object that may contain name/value pairs
includes and includeAnnotations.
It also may contain annotations.

Alternative/addition: Use JSON Schema references to mimic edmx:References
Example 15: references
"references": {
"http://tinyurl.com/Org-OData-Measures-V1": {
"includes": …,
"@Some.Term": …
},
"http://somewhere/Vocabulary/V1": {
"includeAnnotations": …
}
},
2.3.1 Includes
The value of includes is an object with one name/value pair per included namespace. The name is the
namespace, the value is an object that may have an alias name/value pair whose value is the alias of
the included namespace. If no alias is defined, the object is empty.
Example 16: includes
"includes": {
"Org.OData.Measures.V1": {
"alias": "Core"
},
"Another.Namespace": {}
},
2.3.2 IncludeAnnotations
The value includeAnnotations is an array of objects. Each object has a termNamespace
name/value pair and may have name/value pairs targetNamespace and qualifier. The values of
these name/value pairs are strings.

IncludeAnnotations: uniqueItems:true
Example 17: includeAnnotations
"includeAnnotations": [ {
"termNamespace": "Name.Space",
"targetNamespace": "Target.Space"
}, {
"termNamespace": "Name.Space",
"targetNamespace": "Target.Space",
"qualifier": "SomeName"
}, {
"termNamespace": "NameSpace",
"qualifier": "SomeName"
}, {
"termNamespace": "Name.Space"
}
]
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 13 of 27
3 The edm.json Schema
The edm.json schema is an extension of JSON Schema Draft 04. It defines the Edm primitive types,
additional keywords, and additional values for the format keyword of JSON Schema.

Extend original JSON Schema constructs by using allOf:[original,odata-addition]
Example 18: the edm.json schema
{
"id":"http://odata.org/schemas/edm-v4.0#",
"$schema":"http://json-schema.org/draft-04/schema#",
"description":"JSON Schema of OData JSON Format for CSDL Version 4.0",
"definitions": …,
"allOf":[
{
"$ref":"http://json-schema.org/draft-04/schema#"
},
{
"properties":{
"schemas":{
"@TODO":"define"
},
"references":{
"@TODO":"do we need this, or can we replace it with a JSON Schema
construct"
}
}
}
]
}
3.1 Definitions

Edm primitive types: Guid, TimeOfDay, Geo, Stream, Binary, Duration

pattern for Guid, Date, DateTimeOffset, TimeOfDay, Binary

format: custom formats allowed, could use xs:date etc. in addition to minimal validation via
pattern

OData Error Response
Example 19: definitions for Edm primitive types and the OData standard error message
"definitions":{
"Edm.Byte":{
"type":"integer",
"minimum":0,
"maximum":255
},
"Edm.Date":{
"type":"string",
"pattern":"^[0-9]{4,}-[0-9]{2}-[0-9]{2}$",
"format":"xsd:date",
"format@TODO":"list format keywords"
},
"Edm.DateTimeOffset":{
"type":"string",
"TODO":"pattern"
},
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 14 of 27
"Edm.Double":{
"type":"number",
"TODO":"-INF,INF,NaN"
},
"Edm.Int16":{
"type":"integer",
"minimum":-32768,
"maximum":32767
},
"Edm.Int32":{
"type":"integer",
"minimum":-2147483648,
"maximum":2147483647
},
"Edm.Int64":{
"type":"integer",
"minimum":-9223372036854775808,
"maximum":9223372036854775807
},
"Edm.SByte":{
"type":"integer",
"minimum":-128,
"maximum":127
},
"Edm.Single":{
"type":"number",
"TODO":"-INF,INF,NaN"
}
},
3.2 Keywords

Use own key words for stuff that doesn’t fit into JSON Schema, e.g. odataEntityContainer,
odataActions, odataFunctions, referential constraints, IncludeAnnotations

Alternatively define just one keyword "odata" with a hash of sub-properties

Use neutral names for generic, non-odata-specific things like ???

Prefer name:object pairs over name:value pairs in places where we might extend the XML CSDL
format in the future
3.3 Formats

pattern, patternProperties: ECMA 262 regexp, insufficient for SimpleIdentifier etc.
o
Approximation of SimpleIdentifier: ^[^\s$@/0-9][^$.@/]*$
o
Specific formats for SimpleIdentifier, QualifiedName, Path constructs, …
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 15 of 27
4 Validation
A JSON CSDL $metadata document contains definitions that can be used to validate request and
response messages. Depending on the request URL a small wrapper schema has to be used that refers
to the corresponding definition in the JSON $metadata document.
Example 20: a schema for validating messages containing a single Product entity
{
"$schema":"http://json-schema.org/draft-04/schema#",
"allOf": [{
"$ref": "csdl-16.1.json#/definitions/ODataDemo.Product"
}
]
}
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 16 of 27
5 Extensibility
…
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 17 of 27
6 CSDL Examples
Following are two basic examples of valid EDM models as represented in CSDL. These examples
demonstrate many of the topics covered above. They represent the same documents as the examples in
chapter 16 of [OData-CSDL].
6.1 Products and Categories Example
Example 21:
{
"$schema": "http://odata.org/schemas/v4.0/edm.json#",
"definitions": {
"ODataDemo.Product": {
"type": "object",
"odata" : {
"kind" : "entity",
"hasStream" : true,
"keys" : {
"ID" : "ID"
}
},
"properties" : {
"ID" : {
"type" : "string"
},
"Description" : {
"type" : [
"string",
"null"
],
"@Core.IsLanguageDependent" : {}
},
"ReleaseDate" : {
"anyOf" : [{
"$ref" : "http://odata.org/schemas/v4.0/edm.json#/definitions/Edm.Date"
}, {
"type" : "null"
}
]
},
"DiscontinuedDate" : {
"anyOf" : [{
"$ref" : "http://odata.org/schemas/v4.0/edm.json#/definitions/Edm.Date"
}, {
"type" : "null"
}
]
},
"Rating" : {
"anyOf" : [{
"$ref" :
"http://odata.org/schemas/v4.0/edm.json#/definitions/Edm.Int32"
}, {
"type" : "null"
}
]
},
"Price" : {
"type" : [
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 18 of 27
"number",
"null"
],
"@Org.OData.Measures.V1.ISOCurrency" : {
"@odata.type" : "#Path",
"value" : "Currency"
}
},
"Currency" : {
"type" : [
"string",
"null"
],
"maxLength" : 3
},
"Category" : {
"$ref" : "#/definitions/ODataDemo.Category",
"odata" : {
"kind" : "navigation",
"partner" : "Products"
}
},
"Supplier" : {
"anyOf" : [{
"$ref" : "#/definitions/ODataDemo.Supplier"
}, {
"type" : "null"
}
],
"odata" : {
"kind" : "navigation",
"partner" : "Products"
}
}
}
},
"ODataDemo.Category" : {
"type" : "object",
"odata" : {
"kind" : "entity",
"keys" : {
"ID" : "ID"
}
},
"properties" : {
"ID" : {
"$ref" : "http://odata.org/schemas/v4.0/edm.json#/definitions/Edm.Int32"
},
"Name" : {
"type" : "string",
"@Core.IsLanguageDependent" : {}
},
"Products" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/ODataDemo.Product"
},
"odata" : {
"kind" : "navigation",
"partner" : "Category",
"onDelete" : {
"action" : "Cascade"
}
}
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 19 of 27
}
}
},
"ODataDemo.Supplier" : {
"type" : "object",
"odata" : {
"kind" : "entity",
"keys" : {
"ID" : "ID"
}
},
"properties" : {
"ID" : {
"type" : "string"
},
"Name" : {
"type" : [
"string",
"null"
]
},
"Address" : {
"$ref" : "#/definitions/ODataDemo.Address"
},
"Concurrency" : {
"$ref" : "http://odata.org/schemas/v4.0/edm.json#/definitions/Edm.Int32"
},
"Products" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/ODataDemo.Product"
},
"odata" : {
"kind" : "navigation",
"partner" : "Supplier"
}
}
}
},
"ODataDemo.Country" : {
"type" : "object",
"odata" : {
"kind" : "entity",
"keys" : {
"Code" : "Code"
}
},
"properties" : {
"Code" : {
"type" : "string",
"maxLength" : 2
},
"Name" : {
"type" : [
"string",
"null"
]
}
}
},
"ODataDemo.Address" : {
"type" : "object",
"odata" : {
"kind" : "complex"
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 20 of 27
},
"properties" : {
"Street" : {
"type" : [
"string",
"null"
]
},
"City" : {
"type" : [
"string",
"null"
]
},
"State" : {
"type" : [
"string",
"null"
]
},
"ZipCode" : {
"type" : [
"string",
"null"
]
},
"CountryName" : {
"type" : [
"string",
"null"
]
},
"Country" : {
"anyOf" : [{
"$ref" : "#/definitions/ODataDemo.Country"
}, {
"type" : "null"
}
],
"odata" : {
"kind" : "navigation",
"referentialConstraints" : {
"CountryName" : {
"referencedProperty" : "Name"
}
}
}
}
}
}
},
"schemas" : {
"ODataDemo" : {
"alias" : null,
"functions" : [{
"name" : "ProductsByRating",
"parameters" : {
"Rating" : {
"type" : "Edm.Int32"
}
},
"returnType" : {
"type" : "Collection(ODataDemo.Product)"
}
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 21 of 27
}
],
"entityContainer" : {
"name" : "DemoService",
"entitySets" : {
"Products" : {
"entityType" : "ODataDemo.Product",
"navigationPropertyBindings" : {
"Category" : {
"target" : "Categories"
}
}
},
"Categories" : {
"entityType" : "ODataDemo.Category",
"navigationPropertyBindings" : {
"Products" : {
"target" : "Products"
}
}
},
"Suppliers" : {
"entityType" : "ODataDemo.Supplier",
"navigationPropertyBindings" : {
"Products" : {
"target" : "Products"
},
"Address/Country" : {
"target" : "Countries"
}
},
"@Core.OptimisticConcurrency" : [{
"@odata.type" : "#PropertyPath",
"value" : "Concurrency"
}
]
},
"Countries" : {
"entityType" : "ODataDemo.Country"
}
},
"singletons" : {
"Contoso" : {
"type" : "Self.Supplier",
"navigationPropertyBindings" : {
"Products" : {
"target" : "Products"
}
}
}
},
"functionImports" : {
"ProductsByRating" : {
"entitySet" : "Products",
"function" : "ODataDemo.ProductsByRating"
}
}
}
}
},
"references" : {
"http://docs.oasisopen.org/odata/odata/v4.0/cs01/vocabularies/Org.OData.Core.V1.xml" : {
"includes" : {
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 22 of 27
"Org.OData.Core.V1" : {
"alias" : "Core"
}
}
},
"http://docs.oasisopen.org/odata/odata/v4.0/cs01/vocabularies/Org.OData.Measures.V1.xml" : {
"includes" : {
"Org.OData.Measures.V1" : {
"alias" : "UoM"
}
}
}
}
}
6.2 Annotations for Products and Categories Example
Example 22:
{
"$schema" : "http://odata.org/schemas/v4.0/edm.json#",
"schemas" : {
"Annotations" : {
"alias" : null,
"annotations" : [{
"target" : "ODataDemo.Supplier",
"@Vocabulary1.EMail" : {
"@odata.type" : "#Null"
},
"@Vocabulary1.AccountID" : {
"@odata.type" : "#Path",
"value" : "ID"
},
"@Vocabulary1.Title" : "Supplier Info",
"@Vocabulary1.DisplayName" : {
"@odata.type" : "#Apply",
"function" : "odata.concat",
"value" : [{
"@odata.type" : "#Path",
"value" : "Name"
},
" in ", {
"@odata.type" : "#Path",
"value" : "Address/CountryName"
}
]
}
}, {
"target" : "ODataDemo.Product",
"@Self.Tags" : [
"MasterData"
]
}
]
}
},
"references" : {
"http://host/service/$metadata" : {
"includes" : {
"ODataDemo" : {}
}
},
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 23 of 27
"http://somewhere/Vocabulary/V1" : {
"includes" : {
"Some.Vocabulary.V1" : {
"alias" : "Vocabulary1"
}
}
}
}
}
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 24 of 27
7 Conformance
Conforming services MUST follow all rules of this specification document for the types, sets, functions,
actions, containers and annotations they expose.
Conforming clients MUST be prepared to consume a model that uses any or all of the constructs defined
in this specification, including custom annotations, and MUST ignore any elements or attributes not
defined in this version of the specification.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 25 of 27
Appendix A. Acknowledgments
The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol],
are gratefully acknowledged.
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 26 of 27
Appendix B. Revision History
Revision
Date
Editor
Changes Made
Working Draft
01
[Rev Date]
[Modified By]
[Summary of Changes]
odata-json-csdl-v4.0-wd01
Standards Track Draft
Working Draft 01
Copyright © OASIS Open 2014. All Rights Reserved.
30 October 2014
Page 27 of 27