OData JSON Format for Common Schema Definition …



OData JSON Format for Common Schema Definition Language (CSDL) Version 4.0Working Draft 0130 October 2014Technical Committee:OASIS Open Data Protocol (OData) TCChairs:Ram Jeyaraman (Ram.Jeyaraman@), MicrosoftRalf Handl (ralf.handl@), SAP AGEditors:Ralf Handl (ralf.handl@), SAP AGHubert Heijkers (hubert.heijkers@nl.), IBMMike Pizzo (mikep@), MicrosoftMartin Zurmuehl (martin.zurmuehl@), SAP AGAdditional artifacts:This prose specification is one component of a Work Product that also includes:edm.jsonRelated work:This specification replaces or supersedes:NoneThis specification is related to:OData Version 4.0 Part 3: Common Schema Definition Language (CSDL)OData JSON Format Version 4.0Declared XML namespaces:NoneAbstract: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 re-approve it any number of times as a Committee Draft.URI patterns:Initial publication URI: “Latest version” URI:(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.Table of Contents TOC \o "1-4" \h \z \u 1Introduction PAGEREF _Toc402473607 \h 41.1 Terminology PAGEREF _Toc402473608 \h 41.2 Normative References PAGEREF _Toc402473609 \h 41.3 Typographical Conventions PAGEREF _Toc402473610 \h 42JSON CSDL Format Design PAGEREF _Toc402473611 \h 51Requesting the JSON CSDL Format PAGEREF _Toc402473612 \h 62CSDL Documents PAGEREF _Toc402473613 \h 72.1 Definitions PAGEREF _Toc402473614 \h 72.1.1 Entity Types and Complex Types PAGEREF _Toc402473615 \h 72.1.2 Properties and Navigation Properties PAGEREF _Toc402473616 \h 82.1.3 Enumeration Types PAGEREF _Toc402473617 \h 92.1.4 Type Definitions PAGEREF _Toc402473618 \h 92.1.5 Primitive Types PAGEREF _Toc402473619 \h 92.2 Schemas PAGEREF _Toc402473620 \h 92.2.1 Actions and Functions PAGEREF _Toc402473621 \h 92.2.2 Entity Container PAGEREF _Toc402473622 \h 102.2.3 Terms PAGEREF _Toc402473623 \h 102.2.4 Annotations PAGEREF _Toc402473624 \h 102.3 References PAGEREF _Toc402473625 \h 102.3.1 Includes PAGEREF _Toc402473626 \h 102.3.2 IncludeAnnotations PAGEREF _Toc402473627 \h 103The edm.json Schema PAGEREF _Toc402473628 \h 113.1 Keywords PAGEREF _Toc402473629 \h 113.2 Formats PAGEREF _Toc402473630 \h 124Validation PAGEREF _Toc402473631 \h 135Extensibility PAGEREF _Toc402473632 \h 146CSDL Examples PAGEREF _Toc402473633 \h 156.1 Products and Categories Example PAGEREF _Toc402473634 \h 156.2 Annotations for Products and Categories Example PAGEREF _Toc402473635 \h 207Conformance PAGEREF _Toc402473636 \h 22Appendix A.Acknowledgments PAGEREF _Toc402473637 \h 23Appendix B.Revision History PAGEREF _Toc402473638 \h 24IntroductionOData 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]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].Normative References[JSON Schema]JSON Schema.. [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.[RFC2119]Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. . [RFC7159]Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format”, RFC 7159, March 2014. . [ECMAScript]ECMAScript Language Specification Edition 5,1. June 2011. Standard ECMA-262. . 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 styleNon-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.JSON CSDL Format DesignJSON, 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 areJSON CSDL is valid JSON Schema JSON CSDL can be used to by standard JSON Schema validators to validate messages from and to the serviceJSON CSDL contains the same information as XML CSDL JSON CSDL uses JSON Schema concepts that correspond to CSDL conceptsJSON CSDL uses [OData-JSON] concepts where it goes beyond JSON SchemaJSON.parse() of JSON CSDL creates a JavaScript object graph that Appeals to JavaScript programmers by following common naming conventionsSatisfies basic access patternsCan easily be augmented with client-side post-processing to satisfy more sophisticated access patternsRequesting the JSON CSDL FormatThe JSON CSDL format can be requested in Metadata Document Requests (see [ODataProtocol]) 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:IEEE754Compatibleodata.streamingThese are defined in [OData-JSON].CSDL DocumentsA CSDL document in JSON is represented as a JSON Format document with additional keywords.It must contain the property $schema, and it may contain references, definitions, schemas, and references.The value of the $schema property is the canonical URL of the edm schema.Example 2: Structure of CSDL document{ "$schema" : "", "definitions" : …, "schemas" : …, "references" : …}DefinitionsThe definitions object contains one property 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 document-local, so they are meaningless for referencing documents.Example 3: Definitions "definitions" : { "ODataDemo.Product" : …, "ODataDemo.Category" : …, "ODataDemo.Supplier" : …, "ODataDemo.Country" : …, "ODataDemo.Address" : … }Entity Types and Complex TypesEach entity type and complex type is represented as a name/value pair of the standard JSON Schema definitions object. The name of the property is the qualified name of the entity type or complex type. The value is a JSON Schema object. In addition to the standard properties it may contain the properties abstract, baseType, openType, properties, and navigationProperties. The object for an entity type may in addition contain the properties keys and hasStream.The properties abstract, openType, and hasStream have Boolean values. If not present, their value is false.The property baseType has a string value which is the qualified name of the base type.Inheritance: use base type and allow additional propertiesOpen types: have to allow additional properties in JSON Schema for instance annotations, so no standard way. Do we want this for strict OData-specific validation? It would break model versioning, because services are allowed to add properties, so validation with a slightly outdated $metadata snapshot would fail against a compatibly extended service.The object may contain annotations.Example 4: Customer entity type "definitions" : { "ODataDemo.Customer" : { "abstract" : true, "keys" : …, "properties" : …, "@Some.Term" : … }, … },Properties and Navigation PropertiesEach property and navigation property is represented as a name/value pair of the standard JSON Schema properties object.Use “type” with JSON Schema type, add “odataType” extension keword with the more specific typeOnly add the "odataType" attribute in cases where it differs from the default type for the specified json type (i.e., it wouldn't appear for Edm.String, etc…)Don’t use @odata.type because this forces to use [“…”] notation in JavaScript. The chosen keyword allows writing $metadata.definitions.Customer.properties.ID.odataType for accessing the EDM typeNullable -> type:[x,null]DefaultValue -> default Scale=3 -> multipleOf:0.001Precision=5, Scale=3 -> minimum:-99.999, maximum:99.999Example 5: properties of Supplier entity type "properties":{ "ID":{ "type":"string" }, "Name":{ "type":"string" }, "Description" : { "type" : ["string", "null"], "@Core.IsLanguageDependent" : {} }, "Address":{ "$ref":"#/definitions/ODataDemo.Address", }, "LastRatedDate" : { "anyOf":[ { "$ref":"" }, { "type":"null" } ] }, "Rating" : { "anyOf":[ { "$ref":"" }, { "type":"null" } ] }, "Products":{ "kind":"navigation", "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" }, "partner":"Category", "onDelete":{ "action":"Cascade" } },Enumeration TypesEnumType -> enum without type, Member and Value, null for NullableType DefinitionsSimilar to primitive propertiesPrimitive Typesdefine Edm primitive types in edm schema and $ref thempattern for Guid, Date, DateTimeOffset, TimeOfDay, Binaryformat: custom formats allowed, could use xs:date etc. in addition to minimal validation via patternSchemasThe value of the schemas property is an object with one property per defined schema. The name of the property is the namespace of the schema. Its value is an object with an alias property whose value is the alias of the namespace, or null if no alias is defined. The object may contain the properties actions, functions, and entityContainer. It also may contain annotations. "schemas" : { "Some.Model" : { "alias" : "This", "entityTypes" : …, "complexTypes" : …, "enumTypes" : …, "typeDefinitions" : …, "actions" : …, "functions" : …, "terms" : …, "entityContainer" : …, "@Some.Term" : … }Actions and FunctionsEntity ContainerTermsAnnotationsAnnotations are represented similar to instance annotations in [OData-JSON]. The constant expressions edm:Bool, edm:Decimal, edm:Float, edm:Int, and edm:String are represented as plain JSON values. The other constant expressions and the dynamic expressions are represented as JSON objects.Core.Description -> title, Core.LongDescription -> description?ReferencesThe value of the references property is an object with one property per referenced CSDL document. The name of the property is the URI of the CSDL document. Its value is an object that may contain the properties includes and includeAnnotations. It also may contain annotations.Alternative/addition: Use JSON Schema references to mimic edmx:References "references" : { "" : { "includes" : …, "@Some.Term" : … }, "" : { "includeAnnotations" : … } },IncludesThe value of the includes property is an object with one property per included namespace. The name of the property is the namespace. Its value is an object that may have an alias property whose value is the alias of the included namespace. If no alias is defined, the object is empty. "includes" : { "Org.OData.Measures.V1" : { "alias" : "Core" }, "Another.Namespace" : {} },IncludeAnnotationsThe value of the includeAnnotations property is an array of objects. Each object has a termNamespace property and may have a targetNamespace property or a qualifier property. The values of these properties are strings.IncludeAnnotations: uniqueItems:true "includeAnnotations" : [ { "termNamespace" : "Name.Space", "targetNamespace" : "Target.Space" }, { "termNamespace" : "Name.Space", "targetNamespace" : "Target.Space", "qualifier" : "SomeName" }, { "termNamespace" : "NameSpace", "qualifier" : "SomeName" }, { "termNamespace" : "Name.Space" } ]The edm.json SchemaThe 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]{ "id":"", "$schema":"", "description":"JSON Schema of OData JSON Format for CSDL Version 4.0", "definitions": …, "allOf":[ { "$ref":"" }, { "properties":{ "schemas":{ "@TODO":"define" }, "references":{ "@TODO":"do we need this, or can we replace it with a JSON Schema construct" } } } ]}DefinitionsEdm primitive types: Guid, Date, TimeOfDay, DateTimeOffset, Geo, Stream, Binary, DurationOData Error Response "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" }, "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" } },KeywordsUse own key words for stuff that doesn’t fit into JSON Schema, e.g. odataEntityContainer, odataActions, odataFunctions, referential constraints, IncludeAnnotationsAlternatively define just one keyword "odata" with a hash of sub-propertiesUse 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 futureFormatspattern, patternProperties: ECMA 262 regexp, insufficient for SimpleIdentifier etc.Approximation of SimpleIdentifier: ^[^\s$@/0-9][^$.@/]*$Specific formats for SimpleIdentifier, QualifiedName, Path constructs, …ValidationA 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 5: a schema for validating messages containing a single Prodct entity{ "$schema":"", "allOf" : [{ "$ref" : "csdl-16.1.json#/definitions/ODataDemo.Product" } ]}Extensibility…CSDL ExamplesFollowing 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].Products and Categories Example Example 5:{ "$schema":"", "definitions":{ "ODataDemo.Product":{ "kind":"EntityType", "hasStream":true, "keys":{ "ID":"ID" }, "properties":{ "ID":{ "type":"string" }, "Description":{ "type":[ "string", "null" ], "@Core.IsLanguageDependent":{ } }, "ReleaseDate":{ "anyOf":[ { "$ref":"" }, { "type":"null" } ] }, "DiscontinuedDate":{ "anyOf":[ { "$ref":"" }, { "type":"null" } ] }, "Rating":{ "anyOf":[ { "$ref":"" }, { "type":"null" } ] }, "Price":{ "type":[ "number", "null" ], "@Org.OData.Measures.V1.ISOCurrency":{ "@odata.type":"Edm.Path", "value":"Currency" } }, "Currency":{ "type":[ "string", "null" ], "maxLength":3 }, "Category":{ "kind":"navigation", "$ref":"#/definitions/ODataDemo.Category", "nullable":false, "partner":"Products" }, "Supplier":{ "kind":"navigation", "$ref":"#/definitions/ODataDemo.Supplier", "partner":"Products" } } }, "ODataDemo.Category":{ "kind":"EntityType", "keys":{ "ID":"ID" }, "properties":{ "ID":{ "$ref":"" }, "Name":{ "type":"string", "@Core.IsLanguageDependent":{ } }, "Products":{ "kind":"navigation", "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" }, "partner":"Category", "onDelete":{ "action":"Cascade" } } } }, "ODataDemo.Supplier":{ "kind":"EntityType", "keys":{ "ID":"ID" }, "properties":{ "ID":{ "type":"string" }, "Name":{ "type":[ "string", "null" ] }, "Address":{ "$ref":"#/definitions/ODataDemo.Address" }, "Concurrency":{ "$ref":"" }, "Products":{ "kind":"navigation", "type":"array", "items":{ "$ref":"#/definitions/ODataDemo.Product" }, "partner":"Supplier" } } }, "ODataDemo.Country":{ "kind":"EntityType", "keys":{ "Code":"Code" }, "properties":{ "Code":{ "type":"string", "maxLength":2 }, "Name":{ "type":[ "string", "null" ] } } }, "ODataDemo.Address":{ "kind":"ComplexType", "properties":{ "Street":{ "type":[ "string", "null" ] }, "City":{ "type":[ "string", "null" ] }, "State":{ "type":[ "string", "null" ] }, "ZipCode":{ "type":[ "string", "null" ] }, "CountryName":{ "type":[ "string", "null" ] }, "Country":{ "kind":"navigation", "$ref":"#/definitions/ODataDemo.Country", "referentialConstraints":{ "CountryName":{ "referencedProperty":"Name" } } } } } }, "schemas":{ "ODataDemo":{ "alias":null, "functions":[ { "name":"ProductsByRating", "parameters":{ "Rating":{ "type":"Edm.Int32" } }, "returnType":{ "type":"Collection(ODataDemo.Product)" } } ], "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":"Edm.PropertyPath", "value":"Concurrency" } ] }, "Countries":{ "entityType":"ODataDemo.Country" } }, "singletons":{ "Contoso":{ "type":"Self.Supplier", "navigationPropertyBindings":{ "Products":{ "target":"Products" } } } }, "functionImports":{ "ProductsByRating":{ "entitySet":"Products", "function":"ODataDemo.ProductsByRating" } } } } }, "references":{ "":{ "includes":{ "Org.OData.Core.V1":{ "alias":"Core" } } }, "":{ "includes":{ "Org.OData.Measures.V1":{ "alias":"UoM" } } } }} Annotations for Products and Categories Example Example 6:{ "$schema":"", "schemas":{ "Annotations":{ "alias":null, "annotations":[ { "target":"ODataDemo.Supplier", "@Vocabulary1.EMail":{ "@odata.type":"Edm.Null" }, "@Vocabulary1.AccountID":{ "@odata.type":"Edm.Path", "value":"ID" }, "@Vocabulary1.Title":"Supplier Info", "@Vocabulary1.DisplayName":{ "@odata.type":"Edm.Apply", "function":"odata.concat", "value":[ { "@odata.type":"Edm.Path", "value":"Name" }, " in ", { "@odata.type":"Edm.Path", "value":"Address/CountryName" } ] } }, { "target":"ODataDemo.Product", "@Self.Tags":[ "MasterData" ] } ] } }, "references":{ "$metadata":{ "includes":{ "ODataDemo":{ } } }, "":{ "includes":{ "Some.Vocabulary.V1":{ "alias":"Vocabulary1" } } } }} ConformanceConforming 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.AcknowledgmentsThe contributions of the OASIS OData Technical Committee members, enumerated in [ODataProtocol], are gratefully acknowledged.Revision HistoryRevisionDateEditorChanges MadeWorking Draft 01[Rev Date][Modified By][Summary of Changes] ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download