Odata JSON Format Version 1.0

OData JSON Format Version 1.0

Working Draft 01

1308 August 2012

Technical Committee:

OASIS Open Data Protocol (OData) TC

Chairs:

Barbara Hartel (), SAP AG

Ram Jeyaraman (), Microsoft

Editor:

Ralf Handl (), SAP AG

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

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 5

2 Requesting Verbose JSON Formats 6

2.1 Client/Service Format Compatibility and Versions 6

3 Common Payload Format 7

3.1 Representing an Entity 7

3.1.1 Entity Metadata 7

3.1.1.1 Entity Metadata for Media Link Entries 8

3.1.1.2 Entity Metadata for Actions 8

3.1.1.3 Entity Metadata for Functions 8

3.2 Representing a Navigation Property 8

3.2.1 Example Deferred Navigation Property 8

3.2.2 Example Expanded Navigation Property 9

3.2.3 Representing a Deferred Navigation Property 9

3.2.4 Representing an Expanded Navigation Property 9

3.3 Representing Navigation Property Metadata 10

3.4 Representing a Named Resource Stream Value 10

3.5 Representing a Primitive Value 10

3.6 Representing a Complex Type Value 10

3.7 Representing a Set of Links 11

3.8 Representing Annotations 11

3.8.1 Annotate a Value Represented as a JSON Object 12

3.8.2 Annotate a Value Represented as a JSON Array or Primitive 12

3.9 Advertisement for a Function or Action 12

4 Request Specifics 13

4.1 Representing a Property in a Request 13

4.2 Representing Multiple Entities in a Request 13

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

5 Response Specifics 14

5.1 Response Body 14

5.2 MIME Type 14

5.3 Representing a Property in a Response 14

5.4 Representing Multiple Entities in a Response 14

5.4.1 Representing Actions Bound to Multiple Entities 15

5.4.2 Representing Functions Bound to Multiple Entities 15

5.5 Representing a Set of Links in a Response 15

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

5.7 Representing Errors in a Response 16

5.8 Representing the Service Document 17

6 Conformance 18

Appendix A. Acknowledgments 19

Appendix B. Non-Normative Text 20

B.1 Subsidiary section 20

B.1.1 Sub-subsidiary section 20

Appendix C. Revision History 21

odata-json-format-v1.0-wd01 Working Draft 01 02 August 2012

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

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

[RFC5646] Phillips, A., “Tags for Identifying Languages”, BCP 47, RFC 56462119, September 20096. http://toolswww.ietf.org/htmlrfc/rfc54646.txt.

1.3 Non-Normative References

Reference] ion]

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 Requesting Verbose JSON Formats

ISSUE: 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 Versions

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

ISSUE ODATA-17: Version numbering: Which number do we use for the OData version specified in the OASIS set of documents? 3.0, 4.0 or 1.0? If not 4.0, how do we refer to the OSP versions 1.0, 2.0, and 3.0?

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.

PROPOSAL for typographical conventions: Use text style Keyword for media types, HTTP header names, system query option names, URI fragments, HTTP request/response fragments within prose text and paragraph style Code as separate paragraphs.

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

Accept: application/json

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

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

MaxDataServiceVersion: 3.0

Accept: application/json;odata=verbose

If the client fully supports OData version 3.0:

MaxDataServiceVersion: 3.0

Accept: 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.

3 Common Payload Format

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

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

The 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 6.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.

The functions name/value pair MAY be included in a response if the service is advertising functions. See Entity Metadata for Functions 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 Entries

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

CHANGE: Added abbreviation (MLE) after first occurrence of term to make section more readable.

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.