OData JSON Format Version 1.0 - OASIS€¦  · Web viewOData JSON Format Version 1.0. Working...

25
OData JSON Format Version 1.0 Working Draft 01 27 30 September 2012 Technical Committee: OASIS Open Data Protocol (OData) TC Chairs: Barbara Hartel ([email protected]), SAP AG Ram Jeyaraman ([email protected]), Microsoft Editor: Ralf Handl ([email protected]), SAP AG Christopher Woodruff ([email protected]), Perficient, Inc Susan Malaika ([email protected]), IBM Mark Biamonte ([email protected]), Progress Software Additional artifacts: This prose specification is one component of a Work Product which also includes: XML schemas: (list file names or directory name) Other parts (list titles and/or file names) Related work: This specification replaces or supersedes: Specifications replaced by this specification (hyperlink, if available) This specification is related to: Related specifications (hyperlink, if available) Declared XML namespaces: list namespaces declared within this specification Abstract: The OData protocol is comprised of a set of specifications for representing and interacting with structured content. The core specification for the protocol is in [OData-Core]; this document is an extension of the core protocol. This document defines representations for the OData requests and responses using a verbose JSON format. 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. odata-json-format-v1.0-wd01 Working Draft 01 27 30 September 2012 Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 1 of 25

Transcript of OData JSON Format Version 1.0 - OASIS€¦  · Web viewOData JSON Format Version 1.0. Working...

OData JSON Format Version 1.0

Working Draft 01

27 30 September 2012

Technical Committee:OASIS Open Data Protocol (OData) TC

Chairs:Barbara Hartel ([email protected]), SAP AGRam Jeyaraman ([email protected]), Microsoft

Editor:Ralf Handl ([email protected]), SAP AGChristopher Woodruff ([email protected]), Perficient, IncSusan Malaika ([email protected]), IBMMark Biamonte ([email protected]), Progress Software

Additional artifacts:This prose specification is one component of a Work Product which also includes:

XML schemas: (list file names or directory name) Other parts (list titles and/or file names)

Related work:This specification replaces or supersedes:

Specifications replaced by this specification (hyperlink, if available)This specification is related to:

Related specifications (hyperlink, if available)Declared XML namespaces:

list namespaces declared within this specificationAbstract:

The OData protocol is comprised of a set of specifications for representing and interacting with structured content. The core specification for the protocol is in [OData-Core]; this document is an extension of the core protocol. This document defines representations for the OData requests and responses using a verbose JSON format.

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.

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

odata-json-format-v1.0-wd01 Working Draft 01 30 September 2012Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 1 of 22

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-format-v1.0-wd01 Working Draft 01 30 September 2012Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 2 of 22

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

1.1 Terminology....................................................................................................................................... 51.2 Normative References....................................................................................................................... 51.3 Non-Normative References.............................................................................................................65

2 Requesting Verbose JSON Formats.................................................................................................762.1 Client/Service Format Compatibility and Versions...........................................................................76

3 Common Payload Format................................................................................................................. 873.1 Representing an Entity.................................................................................................................... 87

3.1.1 Entity Metadata........................................................................................................................873.1.1.1 Entity Metadata for Media Link Entries...............................................................................................983.1.1.2 Entity Metadata for Actions.................................................................................................................983.1.1.3 Entity Metadata for Functions.............................................................................................................98

3.2 Representing a Navigation Property................................................................................................983.2.1 Example Deferred Navigation Property..................................................................................1093.2.2 Example Expanded Navigation Property................................................................................1093.2.3 Representing a Deferred Navigation Property........................................................................1093.2.4 Representing an Expanded Navigation Property...................................................................109

3.3 Representing Navigation Property Metadata...............................................................................11103.4 Representing a Named Resource Stream Value.........................................................................11103.5 Representing a Primitive Value...................................................................................................11103.6 Representing a Complex Type Value..........................................................................................12113.7 Representing a Set of Links........................................................................................................12113.8 Representing Annotations...........................................................................................................1211

3.8.1 Annotate a Value Represented as a JSON Object...............................................................13123.8.2 Annotate a Value Represented as a JSON Array or Primitive..............................................1312

3.9 Advertisement for a Function or Action........................................................................................13124 Request Specifics......................................................................................................................... 1413

4.1 Representing a Property in a Request.........................................................................................14134.2 Representing Multiple Entities in a Request................................................................................14134.3 Representing a Collection of Complex Type or Primitive Values in a Request............................1413

5 Response Specifics....................................................................................................................... 15145.1 Response Body........................................................................................................................... 15145.2 MIME Type.................................................................................................................................. 15145.3 Representing a Property in a Response......................................................................................15145.4 Representing Multiple Entities in a Response.............................................................................1514

5.4.1 Representing Actions Bound to Multiple Entities..................................................................16155.4.2 Representing Functions Bound to Multiple Entities..............................................................1615

5.5 Representing a Set of Links in a Response.................................................................................16155.6 Representing a Collection of Complex Type or Primitive Values in a Response.........................17165.7 Representing Errors in a Response.............................................................................................17165.8 Representing the Service Document...........................................................................................1817

6 Conformance................................................................................................................................. 1918Appendix A. Acknowledgments........................................................................................................2019

odata-json-format-v1.0-wd01 Working Draft 01 30 September 2012Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 3 of 22

Appendix B. Non-Normative Text.....................................................................................................2120B.1 Subsidiary section....................................................................................................................... 2120

B.1.1 Sub-subsidiary section.........................................................................................................2120Appendix C. Revision History...........................................................................................................2221

odata-json-format-v1.0-wd01 Working Draft 01 30 September 2012Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 4 of 22

1 IntroductionThe OData protocol is comprised of a set of specifications for representing and interacting with structured content. The core specification for the protocol is in core; this document is an extension of the core protocol. This document defines representations for the OData requests and responses using the JavaScript Object Notation (JSON), see [RFC4627].An OData JSON payload may represent:

a single primitive value a sequence of primitive values a single complex type a sequence of complex types a single entity a sequence of entities a service document describing the entity sets exposed by the service an error a batch of requests to be executed in a single request a set of responses returned from a batch request

Most payloads are represented identically in requests and responses. There are some differences. This document first defines the common formats, then discusses details that are specific to request or response.This document contains many example JSON payloads or partial JSON payloads. These examples are informative only. The text shall be taken as the normative specification.

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-Core] OData Protocol Version 1.0. DD Month 2012. OASIS Committee Specification

Draft 01. http://docs.oasis-open.org/odata/odata/v1.0/csd01/odata-v1.0-csd01.doc.

[OData-ABNF] OData ABNF Construction Rules Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-abnf-construction-rules/v1.0/csd01/odata-abnf-construction-rules-v1.0-csd01.doc.

[OData-CSDL] OData Common Schema Definition Language (CSDL) Version 1.0. DD Month 2012. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-csdl/v1.0/csd01/odata-csdl-v1.0-csd01.doc.

[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.

[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON)”, RFC 4627, July 2006. http://tools.ietf.org/html/rfc4627.

[RFC5646] Phillips, A., “Tags for Identifying Languages”, BCP 47, RFC 5646, September 2009. http://tools.ietf.org/html/rfc5646.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 5 of 22

1.3 Non-Normative References[Reference] [Full reference citation]

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 6 of 22

2 Requesting Verbose JSON FormatsISSUE: In the July 2012 F2F we decided that this document will describe both (New / Light / Standard / Default) JSON and Verbose JSON. The contributed document only covers Verbose JSON, which is reflected in its document structure. We could either keep a common top-level structure “3 Common / 4 Request / 5 Response” with subsections for the two flavors, or have two top-level sections “3 Standard JSON / 4 Verbose JSON” and use “Common / Request / Response” for the second level of each part.Verbose JSON is not the default OData format. To receive responses in Verbose JSON, the client MUST explicitly ask for them.To request this format using $format, use the value jsonverbose. To request this format using the Accept header, use the MIME type application/json;odata=verbose.

2.1 Client/Service Format Compatibility and VersionsPrior to version 3.0, Verbose JSON format was simply the only OData JSON format. In version 3.0 and later, JSON is the default JSON format.A request with Accept header application/json or with a $format value of json MUST be treated as a request for the service’s default JSON format.Therefore, such a request on a version 1.0 or 2.0 service, or if specified with a MaxDataServiceVersion header of 1.0 or 2.0 will result in Verbose JSON. However, a request for default JSON on a version 3.0 or higher service, or if specified with a MaxDataServiceVersion of 3.0 or higher will result in JSON.Clients and services SHOULD prefer the new JSON format as long as they both support it. To maximize compatibility, clients MAY use one of the following sets of headers.If the client does not understand OData version 3.0:

MaxDataServiceVersion: 2.0Accept: application/json

If the client understands OData version 3.0 but only supports Verbose JSON:

MaxDataServiceVersion: 3.0Accept: application/json;odata=verbose

If the client fully supports OData version 3.0:

MaxDataServiceVersion: 3.0Accept: application/json;odata=light;q=1,application/json;odata=verbose;q=0.5

Optionally, Atom can be added as a further fallback in case the service supports neither JSON format.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 7 of 22

3 Common Payload FormatThis section describes the representation for OData values in Verbose JSON. A request or response body consists of several parts. It contains OData values as part of a larger document. See Request Formats and Response Formats for the specification of request and response bodies.

3.1 Representing an EntityAn instance of an entity type MUST be serialized as a JSON object.Each property to be transmitted MUST be represented as a name/value pair within the object. See Representing a Property in a Request for details. The order properties appear within the object MUST be considered insignificant. Name/value pairs not representing a property defined on the entity type SHOULD NOT be included.An entity in a payload MAY be a complete entity, a projected entity (see [OData-Core, section 10.2.3.2 The $select System Query Option]), or a partial entity update (see [OData-Core, section 10.3.1.2. Differential Update]). A complete entity MUST transmit every property, including navigation properties. A projected entity MUST transmit the requested properties and MAY transmit other properties. A partial entity MUST transmit the properties that it intends to change; it MUST NOT transmit any other properties.The name in a property’s name/value MUST NOT be __metadata (two leading underscores). There is no JSON Verbose representation for a property named __metadata.

An entity JSON object MAY include a name/value pair named __metadata. This name/value pair does not represent a property. It specifies the metadata for the entity. The ordering of this name/value pair with respect to name/value pairs that represent properties MUST be considered insignificant.

3.1.1 Entity MetadataThe value of the __metadata property MUST be a JSON object.

In OData 1.0 and OData 2.0, the value of the __metadata property contains up to seven name/value pairs: uri, type, etag, edit_media, media_src, media_etag, and content_type. In OData 3.0, four more name/value pairs are added: properties, actions, functions, and id. The order of these name/value pairs MUST be considered insignificant.If the entity is not a Media Link Entry, then the edit_media, media_src, media_etag, and content_type name/value pairs MUST NOT be included.

The value of the uri name/value pair MUST be present and MUST be the canonical URI identifying the entity.The type name/value pair MUST be included if the entity’s type is part of an inheritance hierarchy, as described in [OData-CSDL, section 7.1.2 The edm:BaseType Attribute]. If the entity type is not part of an inheritance hierarchy, then the type name/value pair MAY be included. The value of the type name/value pair MUST be the namespace qualified name of the entity’s type.The etag name/value pair MAY be included. When included, it MUST represent the concurrency token associated with the entity ETag. When present, this value MUST be used instead of the ETag HTTP header.The id name/value pair MAY be included if the service is using OData 2.0 and MUST be included if the service is using OData 3.0.The value of the properties name/value pair MUST be a JSON object. It SHOULD contain a name/value pair for each navigation property. See Representing Navigation Property Metadata for details.The actions name/value pair MAY be included in a response if the service is advertising actions. See Entity Metadata for Actions for details.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 8 of 22

The functions name/value pair MAY be included in a response if the service is advertising functions. See The name MUST specify an action that is bindable to the current entity type; i.e. it is defined with an overload that takes the current entity type as a binding parameter. for details.The actions and functions name/value pairs MAY be included in request payloads. In requests they are without meaning and MUST be ignored by the service.

3.1.1.1 Entity Metadata for Media Link EntriesIf the entity is a media link entity (MLE), the media_src name/value pair MUST be included and the edit_media, content_type, and media_etag name/value pairs MAY be included.

PROPOSAL: Add a glossary for typical abbreviations, or always spell them out. Having a glossary might be a good idea even if we abstain from abbreviations.The value of the media_src name/value pair MUST be the source URI for the data corresponding to this MLE.The value of the content_type name/value pair SHOULD be the MIME type of the data corresponding to this MLE. This is only a hint. The actual content type will be included in a header when the resource is requested.The value of the edit_media name/value pair MUST be the edit URI for the data corresponding to this MLE.The value of the media_etag name/value pair MUST be the concurrency token for the data corresponding to this MLE.

3.1.1.2 Entity Metadata for ActionsStarting in the OData 3.0 protocol, the actions name/value pair MAY be included in __metadata. The value is a JSON object that contains action advertisement name/value pairs. See Advertisement for a Function or Action for details.The name MUST specify an action that is bindable to the current entity type; i.e. it is defined with an overload that takes the current entity type as a binding parameter.

3.1.1.3 Entity Metadata for FunctionsStarting in the OData 3.0 protocol, the functions name/value pair MAY be included in __metadata. The value is a JSON object that contains function advertisement name/value pairs. See Advertisement fora Function or Action for details.The name MUST only identify functions that are bindable to the current entity type. If overloads exist that cannot be bound to the current entity type, the name SHOULD address a specific function overload.If all function overloads can be bound to the current entity type, the service SHOULD advertise a single function Metadata URL that identifies all of the overloads.

3.2 Representing a Navigation PropertyA navigation property represents a reference from a source entity to zero or more other entities.There are two representations for a navigation property: deferred and expanded. The deferred representation represents each related entity with a URI. The expanded representation represents each related entity with its expanded contents.By default, a service SHOULD represent each navigation property in the deferred format. This conserves resources.A client MAY request that a navigation property be expanded, using a combination of $expand and $select. The service MUST represent each navigation property so requested in the expanded format.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 9 of 22

3.2.1 Example Deferred Navigation Property{ "CustomerID": "ALFKI", "Orders": { "__deferred": { "uri": "Customers(\'ALFKI\')/Orders" } }, "__metadata": { "properties" : { "Orders" : { "associationuri" : "Customers(\'ALFKI\')/$links/Orders" } } }}

3.2.2 Example Expanded Navigation Property{ "CustomerID": "ALFKI", "Orders": { "resultsd": [ { "__metadata": { ... }, "OrderID": 1, ... }, { ... } ], }, "__metadata": { "properties" : { "Orders" : { "associationuri" : "Customers(\'ALFKI\')/$links/Orders" } } }}

3.2.3 Representing a Deferred Navigation PropertyA deferred navigation property is represented as a name/value pair. The name MUST be the name of the property. The value must be a JSON object.The value must contain a single name/value pair. This name MUST be __deferred. The inner value MUST be another JSON object.The inner JSON Object must contain a single name/value pair. The name must be uri. The value must be the URI for the navigation property (this is not the NavigationLink URI).See Example Deferred Navigation Property for an example.

3.2.4 Representing an Expanded Navigation PropertyAn expanded navigation property is represented as a name/value pair. The name MUST be the name of the property.The value MUST be the correct representation of the related entity or entity set. See Representing an Entity, Representing Multiple Entities in a Response, or Representing Multiple Entities in a Request for details.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 10 of 22

Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101

See Example Expanded Navigation Property for an example.

3.3 Representing Navigation Property MetadataMetadata for a navigation property is represented as a name/value pair.The name MUST be the property’s name.The value MUST be a JSON object containing a single name/value pair. The name must be associationuri. The value must be a string containing the NavigationLink URI for that property.

See Example Deferred Navigation Property for an example.

3.4 Representing a Named Resource Stream ValueThe value of a named resource stream property is represented like in the following example.

{ "__mediaresource": { "edit_media": "http://server/uploads/Thumbnail546.jpg", "media_src": "http://server/Thumbnail546.jpeg", "content-type": "img/jpeg", "media_etag": "####" }}

This would typically show up in the definition of an entity, as in the following example:

{ "__metadata": {...}, "ID": 3, "Thumbnail": { "__mediaresource": {...} }, "PrintReady": { "__mediaresource": {...} },}

The named stream value MUST be represented as a JSON object. That object MUST contain a single name/value pair. The name MUST be __mediaresource. The value MUST be a JSON object.

The JSON object contains up to 4 name/value pairs. Each pair is described below.The media_src name/value pair MUST be included. The value of the name/value pair MUST be a URI that can be used to retrieve the stream of bytes with a GET request.

The content_type name/value pair MUST be included. If the edit_media name/value pair is present the value of the content_type name/value pair MUST specify the content type of the binary stream represented by the edit_media URI. The value of the content_type name/value pair MAY match the content type of the binary stream represented by the media_src URI.

The edit_media name/value pair MAY be included. This name/value pair MUST be supplied if the named resource stream instance can be updated. The value of the edit_media name/value pair MUST be a URI that can be used to replace the existing stream with a HTTP PUT request.

The media_etag name/value pair MAY be included. When included, the value MUST be the value of the ETag for the named resource stream last PUT to the edit_media URI.

3.5 Representing a Primitive ValueThe representation for primitives in JSON Verbose is specified in the [OData-ABNF].

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 11 of 22

3.6 Representing a Complex Type ValueIn the following example, Address is a property with a complex type value.

{ "CustomerID": "ALFKI", "Address": { "Street": "57 Contoso St", "City": "Seattle" }}

A complex type value MUST be represented as a single JSON object. It MUST have one name/value pair for each property that makes up the complex type. Each property MUST be formatted as appropriate for the property. See Representing a Property in a Request for details.The object representing a complex type value SHOULD NOT contain any other name/value pairs.

3.7 Representing a Set of LinksA set of links expresses a relation from one entity to zero or more related entities.The following example shows a set of links represented as appropriate for a request.

[ {"uri": "http://host/service.svc/Orders(1)"}, {"uri": "http://host/service.svc/Orders(2)"}]

A set of links MUST be represented as a single JSON array. This array MUST contain one item per link.Each link item MUST be represented as a single JSON object. This object MUST contain a single name/value pair. The name MUST be uri. The value MUST be a URI for the related entity.

There are additional considerations for representing a set of links in a response. See Representing a Set of Links in a Response for details.

3.8 Representing AnnotationsAnnotations MAY be applied to any name/value pair in a JSON payload that represents a value of any type from the entity data model (see [OData-CSDL]).The following example shows annotations applied to many different constructs.

{ "@resultsd": { "com.constoso.customer.setkind" : "VIPs" }, "resultsd" : [ { "__metadata": { ... }, "com.constoso.customer.kind" : "VIP", "com.constoso.display.order" : 1, "CustomerID": "ALFKI", "@CompanyName" : { "com.contoso.display" : { "title" : true, "order" : 1 } } "CompanyName": "Alfreds Futterkiste", "Orders": { "com.contoso.purchaseorder.priority" : 1, "__deferred": { "uri": "Customers('ALFKI')/Orders" } } } ]}

In general, it is possible to express an annotation internally or externally to a value. However, an annotation is always a name/value pair. Therefore, it can only be expressed within a JSON object. Some odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 12 of 22

Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101

entity data model constructs are not represented with JSON objects. Therefore some types may only be annotated externally.Annotations are always expressed as name/value pairs. For entity data model constructs represented as JSON objects the annotation name/value pairs are placed within the object; for constructs represented as JSON arrays or primitives they are placed next to the annotated model construct. See the specific subsections of this section for normative rules about how to represent annotations on various types.

3.8.1 Annotate a Value Represented as a JSON ObjectThis section applies when annotating a name/value pair for which the value is represented as a JSON object.Each annotation MUST be applied internally. Each annotation MUST be represented as a single name/value pair.This section applies when annotating a name/value pair for which the value is represented as a JSON object. Each annotation MUST be applied within the object. Each annotation MUST be represented as a single name/value pair.The name MUST be the fully-scoped name of the annotation. This name MUST include namespace and name, separated by a period (.).

The value MUST be the appropriate value for the annotation.

3.8.2 Annotate a Value Represented as a JSON Array or PrimitiveThis section applies when annotating a name/value pair for which the value is not represented as a JSON object.The set of all annotations that apply to this name/value pair MUST be applied externally. This set of annotations is represented as a single name/value pair.This section applies when annotating a name/value pair for which the value is not represented as a JSON object. The set of all annotations that apply to this name/value pair MUST be placed next to the annotated model construct. This set of annotations is represented as a single name/value pair.The name MUST be the same as the name of the name/value pair being annotated, prefixed with the “at” sign (@).

The value MUST be a JSON object. Each annotation in the set MUST be represented as a single name/value pair within this object.The name MUST be the fully-scoped name of the annotation. This name MUST include namespace and name, separated by a period (.).

The value MUST be the appropriate value for the annotation.

3.9 Advertisement for a Function or ActionA function or action is advertised via a name/value pair. The name MUST be a Metadata URL. The value MUST be an array of JSON objects.Any number of JSON objects is allowed in this array. Each object in this array MUST have at least two name/value pairs: title and target. The order of these name/value pairs MUST be considered insignificant.The target name/value pair MUST contain a bound action target URL.

The title name/value pair MUST contain the action title as a string.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 13 of 22

Mark Biamonte, 09/30/12,
Editorial: Modified inserted text from what was accepted slightly. The word be was repeated twice. I removed the repeated word.
Mark Biamonte, 09/30/12,
Applying Proposed change for ODATA-98
Mark Biamonte, 09/30/12,
Applying Proposed change for ODATA-98
Mark Biamonte, 09/30/12,
Applying Proposed change for ODATA-98

4 Request SpecificsThis section describes additional payload semantics that only apply to request payloads.

4.1 Representing a Property in a RequestA Property is represented as a name/value pair. The name is the property’s name.The value for a primitive, complex type, collection, or named stream property is the property’s value. It MUST be formatted appropriately for its type.A property’s representation is always contained within a JSON object. If the request does not already contain a wrapping JSON object, then one is wrapped around the described name/value pair.

4.2 Representing Multiple Entities in a RequestA collection of entities MUST be represented as a JSON array. Each element MUST be a correctly formatted entity (see Representing an Entity).An empty entity set or collection of entities (one that contains no entity type instances) MUST be represented as an empty JSON array.

4.3 Representing a Collection of Complex Type or Primitive Values in a Request

A collection of complex type or primitive values MUST be represented as a JSON array. Each element in the array MUST be the representation for a value. See Representing a Primitive Value or Representing a Complex Type Value for details.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 14 of 22

5 Response SpecificsThis section describes additional payload semantics that only apply to response payloads.

5.1 Response BodyAll JSON Verbose responses are wrapped in a single object for security reasons.Each response body MUST be represented as a single JSON object. This object contains a single name/value pair. The name MUST be d. The value MUST be the correct representation for the data being returned.

5.2 MIME TypeVerbose JSON is represented with a Content-Type of “application/json;odata=verbose”.

In OData 1.0 and 2.0, it was also represented with a Content-Type of “applicaton/json”. However, in OData 3.0, “application/json” has been redefined to mean JSON.

ISSUE ODATA-6: This introduces an avoidable incompatibility for clients wishing to talk OData 2.0PROPOSAL: Respond with a Content-Type of “application/json” to client requests with a MaxDataServiceVersion of 1.0 or 2.0 and an Accept header listing “application/json” without the suffix “;odata=verbose”.

Respond with a Content-Type of “application/json;odata=verbose” in all other cases.

5.3 Representing a Property in a ResponseIn OData 1.0, a property in a response is formatted just like in a request. See Representing a Property in a Request for details.Additionally, any property that is being represented as part of a larger item is represented as in a request.The rest of this section applies only to representing a top-level property in OData 2.0 and 3.0.A property is represented as in the following example.

{ "resultsd": { "CustomerName": "the value of the property" }}

A property is represented as a JSON object with a single name/value pair. The name is resultsd. The value is a JSON object.The object contains the representation that would be used for this property in a request. See Representing a Property in a Request for details.

5.4 Representing Multiple Entities in a ResponseIn OData 1.0, a collection of entities in a response is formatted just like in a request. See Representing Multiple Entities in a Request for details.The rest of this section applies to OData 2.0 and 3.0 only.A collection of entities is represented as in the following example.

{ "__metadata": { ... }, "__count": 37,

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 15 of 22

Mark Biamonte, 09/30/12,
The changes in this section were not in the description or comments of ODATA-101. They should be looked at in accepting the applied changes.
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101

"resultsd": [ { ... }, { ... }, { ... } ], "__next": "/next?$skiptoken=342r89",}

A collection of entities MUST be represented as a JSON object. This object MUST contain a results d name/value pair. It MAY contain __count, __next, or __metadata name/value pairs.

The results d value MUST be a JSON array. Each element MUST be a correctly formatted entity (see Representing an Entity).The __count name/value pair represents the inlinecount. Its value MUST be an integer corresponding to the total count of members in the collection represented by the request. If present, this name/value pair MUST come before the results d name/value pair. See [OData-Core, section 10.2.3.6 The $inlinecount System Query Option] for details on when it is required and when it is prohibited. The __next name/value pair MAY be included. If provided, its value MUST be a string containing a URL. If provided, then the response MUST be interpreted as a partial result. The client MAY request this URL if it wishes to receive the next part of the collection or entity set.The __metadata name/value pair MAY be included. If provided, its value MUST be a JSON object. This object represents the metadata for the set of entities.An empty collection of entities (one that contains no entity type instances) MUST be represented as a JSON object with a results d name/value pair. The results d name/value pair MUST be an empty JSON array.

5.4.1 Representing Actions Bound to Multiple EntitiesIn the ODATA 3.0 protocol, it is possible to advertise actions that are bound to the definition of a set of entities.Actions are advertised in the metadata for a set of entities. The metadata object MAY contain an actions name/value pair. The value is a JSON object that contains action advertisement name/value pairs. See Advertisement for a Function or Action for details.

5.4.2 Representing Functions Bound to Multiple EntitiesIn the ODATA 3.0 protocol, it is possible to advertise functions that are bound to the definition of a set of entities.Functions are advertised in the metadata for a set of entities. The metadata object MAY contain a functions name/value pair. The value is a JSON object that contains function advertisement name/value pairs. See Advertisement for a Function or Action for details.The function metadata URL MUST identify only functions that are bindable to the current feed definition. If overloads exist that cannot be bound to the current feed definition, the name SHOULD address a specific function overload.If all function overloads can be bound to the current feed definition, the service SHOULD advertise a single function metadata URL that identifies all of the overloads.

5.5 Representing a Set of Links in a ResponseIn OData 1.0 responses, a set of links is represented exactly as described in Representing a Set of Links.In OData 2.0 and 3.0 responses, a set of links is represented as shown in the following example.

{ "resultsd": [ {"uri": "http://host/service.svc/Orders(1)"},

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 16 of 22

Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101

{"uri": "http://host/service.svc/Orders(2)"} ]}

A set of links MUST be formatted as a single JSON object. This object MUST contain a name/value pair. The name MUST be resultsd. The value MUST be the JSON array used to represent that set of links in a request. See Representing a Set of Links for details.The outer JSON object MAY contain additional name/value pairs. One such example is the inlinecount, see Representing Multiple Entities in a Response.

5.6 Representing a Collection of Complex Type or Primitive Values in a Response

In OData 1.0, a collection of complex type or primitive values in a response is formatted just like in a request. See Representing a Collection of Complex Type or Primitive Values in a Request for details.The rest of this section applies to OData 2.0 and 3.0 only.A collection of complex type or primitive values MUST be represented as a JSON object. This object MUST contain a results d name/value pair. It MAY contain a __metadata name/value pair.

The results d value MUST be a JSON array. Each element MUST be a correctly formatted value (see Representing a Complex Type Value or Representing a Primitive Value).The __metadata name/value pair MAY be included. If provided, its value MUST be a JSON object. This object represents the metadata for the collection of complex type values.An empty collection (one that contains no instances) MUST be represented as a JSON object with a results d name/value pair. The results d name/value pair MUST be an empty JSON array.

5.7 Representing Errors in a ResponseTop-level errors in JSON Verbose responses MUST be represented as in the following example.

{ "error": { "code": "A custom error code", "message": { "lang": "en-us", "value": "A custom long message for the user." }, "innererror": { "trace": [...], "context": {...} } }}

The error response MUST be a single JSON object. This object MUST have a single name/value pair. The name MUST be error. The value must be a JSON object.

This object can have two or three name/value pairs. It MUST contain name/value pairs with the names code and message, and it MAY contain a name/value pair with the name innererror. The innererror name/value pair SHOULD only be used in development environments in order to guard against potential security concerns around information disclosure.The value for the code name/value pair MUST be a string. Its value MUST be a service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.The value for the message name/value pair MUST be an object. This object MUST have two name/value pairs, with names lang and message. The message name/value pair MUST contain a human-readable representation of the error. The lang name/value pair MUST contain the language code from [RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON)”, RFC 4627, July

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 17 of 22

Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101
Mark Biamonte, 09/30/12,
Applying proposed change for ODATA-101

2006. http://tools.ietf.org/html/rfc4627. corresponding to the language in which the value for message is written.The value for the innererror name/value pair MUST be an object. The contents of this object are service-defined. Usually this object contains information that will help debug the service.

5.8 Representing the Service DocumentThe root URL of an OData service MUST identify a service document. This document is represented as shown in the following example.

{ "EntitySets": [ "Customers", "Orders", "OrderDetails" ]}

The service document MUST consist of a single JSON object. This object MUST have a single name/value pair. The name MUST be EntitySets. The value MUST be a JSON Array.

There MUST be one element in this array for each entity set exposed by the service. Each element MUST be a JSON string with a value equal to the name of the entity set.

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 18 of 22

6 ConformanceThe last numbered section in the specification must be the Conformance section. Conformance Statements/Clauses go here. [Remove # marker]

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 19 of 22

Appendix A. AcknowledgmentsThe following individuals have participated in the creation of this specification and are gratefully acknowledged:Participants:

[Participant Name, Affiliation | Individual Member][Participant Name, Affiliation | Individual Member]

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 20 of 22

Appendix B. Non-Normative Texttext

B.1 Subsidiary sectiontext

B.1.1 Sub-subsidiary sectiontext

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 21 of 22

Appendix C. Revision HistoryRevision Date Editor Changes Made

01 2012-08-13 Ralf Handl Translated contribution into OASIS format

odata-json-format-v1.0-wd01 Working Draft 01Standards Track Draft Copyright © OASIS Open 2012. All Rights Reserved. Page 22 of 22