Odata JSON Format

OData JSON Format Version 4.0

Working Draft 01

192 March 2013

Technical Committee:

OASIS Open Data Protocol (OData) TC

Chairs:

Barbara Hartel (), SAP AG

Ram Jeyaraman (), Microsoft

Editor:

Ralf Handl (), SAP AG

Mike Pizzo (), Microsoft

Christopher Woodruff (), Perficient, Inc

Susan Malaika (), IBM

Mark Biamonte (), 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 is related to:

· OData Core Part 1: Protocol

· OData Core Part 2: URL Conventions

· OData Core Part 3: Common Schema Definition Language

· OData ABNF Construction Rules

· OData ATOM Format

This specification replaces or supersedes:

· None

Declared XML namespaces:

· None

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-Protocol]; this document is an extension of the core protocol. This document defines representations for the OData requests and responses using a 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.

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

1 Introduction 5

1.1 Terminology 5

1.2 Normative References 5

1.3 Non-Normative References 6

2 JSON Format Design 7

3 Requesting the JSON Format 8

3.1 Controlling the Amount of Control Information in Responses 8

3.1.1 odata.metadata=minimal 8

3.1.2 odata.metadata=full 8

3.1.3 odata.metadata=none 9

4 Payload Format 10

4.1 The Content-Type Header 10

4.2 Payload Ordering Constraints 10

4.3 Message Body 11

4.4 Control Information 11

4.4.1 The odata.metadata Annotation for the Metadata URL 11

4.4.2 Relative URLs 14

4.4.3 The odata.type Annotation 14

4.4.4 The odata.count Annotation 15

4.4.5 The odata.nextLink Annotation 15

4.4.6 The odata.deltaLink Annotation 15

4.4.7 The odata.id Annotation 15

4.4.8 The odata.set Annotation 15

4.4.9 The odata.editLink and odata.readLink Annotations 15

4.4.10 The odata.kind Annotation 16

4.4.11 The odata.etag Annotation 16

4.4.12 The odata.navigationLink and odata.associationLink Annotations 16

4.4.13 The odata.media* Annotations 16

4.5 Representing the Service Document 17

4.6 Representing an Entity 17

4.7 Representing a Resource Reference 18

4.8 Representing a Media Entity 18

4.9 Representing a Navigation Property 19

4.9.1 Representing a Deferred Navigation Property 19

4.9.2 Representing Bind Operations 19

4.9.3 Representing an Expanded Navigation Property 19

4.9.4 Deep Inserts 20

4.10 Representing a Named Stream Property 20

4.11 Representing a Primitive Value 21

4.12 Representing a Complex Type Value 21

4.13 Representing a Collection of Complex Type or Primitive Values 21

4.14 Representing an Individual Property 22

4.15 Representing Multiple Entities in a Response 22

4.16 Representing Changes (Deltas) in a Response 23

4.16.1 Representing Added/Changed Entities 24

4.16.2 Representing Deleted Entities 24

4.16.3 Representing Links 24

4.16.4 Representing Deleted Links 25

4.17 Representing Annotations 25

4.17.1 Annotate a Value Represented as a JSON Object 26

4.17.2 Annotate a Value Represented as a JSON Array or Primitive 26

4.18 Advertisement for a Function or Action 26

4.19 Action Parameters 27

4.20 Representing Errors in a Response 27

4.21 Action Parameters 28

5 Conformance 29

Appendix A. Acknowledgments 30

Appendix B. Non-Normative Text 31

B.1 Subsidiary section 31

B.1.1 Sub-subsidiary section 31

Appendix C. Revision History 32

odata-json-format-v4.0-wd01 Working Draft 01 12 19 March 2013

1 Introduction

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 or entity reference

· a sequence of entities

· a sequence of changes

· a service document describing the entity sets exposed by the service

· an error

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

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

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

[OData-Protocol] OData Version 4.0 Part 1: Protocol. DD Month 2013. OASIS Committee Specification Draft 01. http://docs.oasis-open.org/odata/odata-core/v4.0/csd01/odata-v4.0-csd01-part1-protocol.doc.

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997. http://www.ietf.org/html/rfc2119.

[RFC3986] T. Berners-Lee, R. Fielding, L Masinter, “Uniform Resource Identifier (URI): Generic Syntax”, IETF RFC3986, January 2005. http://www.ietf.org/html/rfc3986.

[RFC3987] M. Duerst, M. Suignard, “Internationalized Resource Identifiers (IRIs)”, IETF RFC3987, January 2005. http://www.ietf.org/html/rfc3987.

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

1.3 Non-Normative References

[ECMAScript] ECMAScript Language Specification Edition 5,1. June 2011. Standard ECMA-262. http://www.ecma-international.org/publications/standards/Ecma-262.htm.

NOTE: The proper format for citation of technical work produced by an OASIS TC (whether Standards Track or Non-Standards Track) is:

[Citation Label]

Work Product title (italicized). Approval date (DD Month YYYY). OASIS Stage Identifier and Revision Number (e.g., OASIS Committee Specification Draft 01). Principal URI (version-specific URI, e.g., with filename component: somespec-v1.0-csd01.html).

For example:

[OpenDoc-1.2] Open Document Format for Office Applications (OpenDocument) Version 1.2. 19 January 2011. OASIS Committee Specification Draft 07. http://docs.oasis-open.org/office/v1.2/csd07/OpenDocument-v1.2-csd07.html.

[CAP-1.2] Common Alerting Protocol Version 1.2. 01 July 2010. OASIS Standard. http://docs.oasis-open.org/emergency/cap/v1.2/CAP-v1.2-os.html.

2 JSON Format Design

A key feature of this format is to remove predictable parts of the wire format from the actual payload. To reconstitute this data on the receiving end, expressions are used to compute missing links, type information, and other control data. These expressions (together with the data on the wire) can be used by the client to compute predictable payload pieces as if they had been included on the wire directly.

The extensibility story of the JSON format revolves around annotations in the payload. Annotations are used to add control information to a JSON payload. Such annotations can refer to a JSON object or a JSON property and provide additional information about the instance (or property). OData defines a set of annotations, and custom annotations can be adding domain-specific control information to the payload.

Annotations are used in JSON to capture control information that cannot be predicted (e.g., the next link of a feed) as well as a mechanism to provide values where a computed value would be wrong (e.g., if the stream read link of one particular entry points to a different server than the metadata expression for all the other entries specifies). Computing values from metadata expressions is compute intensive and some clients might opt for a larger payload size to avoid computational complexity; as a result the Accept header allows the client to control the amount of control information included on the wire.

To support streaming scenarios, there are a few restrictions to the order in which data must appear on the wire. For details on the ordering requirements, see Payload Ordering Constraints.

3 Requesting the JSON Format

To request this format using $format, use the value json. To request this format using the Accept header, use the MIME type application/json. If specified, $format overrides any value specified in the Accept header.

3.1 Controlling the Amount of Control Information in Responses

The amount of control information needed (or desired) in the payload depends on the client application and device. The odata.metadata parameter can be applied to the Accept header of an OData request to influence how much control information will be included in the response. For the purpose of this section, we will take the following two assumptions:

· The media-range for the Accept header is set to application/json.

· Other Accept header parameters (e.g., odata.streaming) are orthogonal to the odata.metadata parameter and are therefore not mentioned in this section.

If a client prefers a very small wire size and is intelligent enough to compute data using metadata expressions, the Accept header should include odata.metadata=minimal. If compute is more expensive than wire size or the client is incapable of computing control information, odata.metadata=full directs the server to inline the control information that normally would be computed from metadata expressions in the payload. odata.metadata=none is an option for clients that have out-of-band knowledge of the expected payload kind and type and thus don't need any control information.

3.1.1 odata.metadata=minimal

The value odata.metadata=minimal is the default value for the odata parameter and will be assumed if no other value is specified in the Accept header. It indicates that the server should remove computable control information from the payload wherever possible. The response payload will still contain common annotations such as

· odata.metadata: the metadata URL of the payload.

· odata.count: the inline count of a set of entities or collection of entity reference links, if requested.

· odata.nextLink: the next link of a set of entities or collection of entity reference links.

· odata.deltaLink: the delta link, if requested, for obtaining changes to the result.

Note that odata.* annotations MUST appear in the payload for cases where actual values are not the same as the computed values and MAY appear otherwise. When odata.* annotations appear in the payload, they MUST be treated as exceptions to the computed values.

Media entities and named stream properties may in addition contain the following annotations:

· odata.mediaReadLink: the link used to read the stream.

· odata.mediaEditLink: the link used to edit/update the stream.

· odata.mediaEtag: the ETag of the stream.

· odata.mediaContentType: the content type of the stream.

3.1.2 odata.metadata=full

The client may specify odata.metadata=full to include all control information explicitly in the payload. The service MUST return all metadata in this case.

The full list of annotations that may appear in an odata.metadata=full response are as follows:

· odata.metadata: the metadata URL of the payload.

· odata.count: the inline count of a set of entities or collection of entity reference links, if requested.

· odata.nextLink: the next link of a set of entities or collection of entity reference links.

· odata.deltaLink: the delta link, if requested, for obtaining changes to the result.

· odata.id: the ID of the entry.

· odata.etag: the ETag of the entry.

· odata.set: the entity set of the entry.

· odata.kind: the kind of object (entry, deleted-entry, link, or deleted-link) represented by the entry.

· odata.readLink: the link used to read the entry.

· odata.editLink: the link used to edit/update the entry.

· odata.navigationLink: the link used to retrieve the values of a navigation property.

· odata.associationLink: the link used to describe the relationship between this entity and related entities.

· odata.type: the type name of the containing object or targeted property. The type annotation is only present if the type of the object or targeted property cannot heuristically determined.

Media entities and named stream properties may in addition contain the following annotations:

· odata.mediaReadLink: the link used to read the stream.

· odata.mediaEditLink: the link used to edit/update the stream.

· odata.mediaEtag: the ETag of the stream.

· odata.mediaContentType: the content type of the stream.

3.1.3 odata.metadata=none

The client can specify odata.metadata=none in order to omit the odata.* annotations.

Note that the odata.nextLink ,odata.count and odata.deltaLink annotations continue to be included, as applicable, even in the odata.metadata=none case.

4 Payload Format

This section describes the representation for OData values in JSON. A request or response body consists of several parts. It contains OData values as part of a larger document. Requests and responses are almost identical; the few existing differences will be explicitly called out in the respective subsections.

4.1 The Content-Type Header

JSON is represented with a Content-Type of application/json.

Requests MAY add the charset parameter to the content type, Allowed values are UTF-8, UTF-16, and UTF-32. If no charset parameter is present, UTF-8 MUST be assumed.

Responses MUST add the odata.metadata parameter with the same value that was specified in the Accept header of the request. If no value was specified in the Accept header, odata.metadata=minimal MUST be used.

Messages MAY add the odata.streaming parameter with a value of true or false, see next section.

4.2 Payload Ordering Constraints

To support streaming scenarios, some payload ordering constraints must be imposed. As some clients (and servers) will not be able to control the order of the JSON properties in the payload or might not care about streaming at all, the payload ordering constraints described in this section are not mandatory for JSON.