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 the JavaScript
Object Notation (JSON), see [RFC4627].
An OData JSON payload may represent:
This document contains many example JSON payloads or partial
JSON payloads. These examples are non-normative and informative only.
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].
[GeoJSON] Butler,
H., Daly, M., Doyle, A., Gillies, S., Schaub, T.,
Schmidt, C., "The GeoJSON Format Specification", Revision 1.0, June 2008.
http://geojson.org/geojson-spec.html.
[OData-ABNF] OData
ABNF Construction Rules Version 4.0.
See link in “Related work” section on cover page.
[OData-CSDL] OData
Version 4.0 Part 3: Common Schema Definition Language (CSDL).
See link in “Related work” section on cover page.
[OData-Protocol] OData
Version 4.0 Part 1: Protocol.
See link in “Related work” 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. http://www.ietf.org/rfc/rfc2119.txt.
[RFC3986] Berners-Lee,
T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic
Syntax”, IETF RFC3986, January 2005. http://www.ietf.org/rfc/rfc3986.txt.
[RFC3987] Duerst,
M. and, M. Suignard, “Internationalized Resource Identifiers (IRIs)”, RFC 3987,
January 2005. http://www.ietf.org/rfc/rfc3987.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., Ed.,
and M. Davis, Ed., “Tags for Identifying Languages”, BCP 47, RFC 5646,
September 2009. http://tools.ietf.org/html/rfc5646.
[ECMAScript] ECMAScript
Language Specification Edition 5,1. June 2011. Standard ECMA-262. http://www.ecma-international.org/publications/standards/Ecma-262.htm.
JSON, as described in [RFC4627], defines a text format for serializing structured data.
Objects are serialized as an unordered collection of name-value pairs.
JSON does not define any semantics around the name/value
pairs that make up an object, nor does it define an extensibility mechanism for
adding control information to a payload.
OData’s JSON format extends JSON by defining general
conventions for name-value pairs that annotate a JSON object, property or
array. OData defines a set of canonical annotations for control information
such as ids, types, and links, and custom annotations MAY be used to add
domain-specific information to the payload.
A key feature of OData’s JSON format is to allow omitting
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.
Annotations are used in JSON to capture control information
that cannot be predicted (e.g., the next link of a collection of entities) as well
as a mechanism to provide values where a computed value would be wrong (e.g.,
if the media read link of one particular entity does not follow the standard
URL conventions). Computing values from metadata expressions is compute
intensive and some clients might opt for a larger payload size to avoid
computational complexity; to accommodate for this the Accept
header allows the client to control the amount of control information added to
the response.
To optimize streaming scenarios, there are a few restrictions
that MAY be imposed on the sequence in which name/value pairs appear within
JSON objects. For details on the ordering requirements see Payload Ordering Constraints.
3
Requesting the JSON Format
The OData JSON format MAY be requested using the $format query option in the request URL with the MIME
type application/json, optionally followed by
format parameters, or the case-insensitive abbreviation json.
Alternatively, this format MAY 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.
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 or don't require control
information.
3.1.1 odata.metadata=minimal
The client MAY specify odata.metadata=minimal
to indicate that the server SHOULD remove computable control information from
the payload wherever possible. This is the default value for the odata parameter and will be assumed if no other value is
specified in the Accept header or $format query option. The response payload MUST contain
at least the following common annotations:
·
odata.metadata: the metadata URL of the payload.
·
odata.etag: the ETag of the entity.
·
odata.count:
the inline count of a set of entities or collection of entity references, if
requested.
·
odata.nextLink:
the next link of a set of entities or collection of entity references.
·
odata.deltaLink: the delta link
for obtaining changes to the result, if requested.
In addition, 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.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 for a collection,
entity, primitive value, or service document.
·
odata.count:
the inline count of a set of entities or collection of entity references, if
requested.
·
odata.nextLink:
the next link of a set of entities or collection of entity references.
·
odata.deltaLink: the delta link for
obtaining changes to the result, if requested.
·
odata.id: the ID of the entity.
·
odata.etag: the ETag of the entity.
·
odata.kind: the kind of object (entry, deleted-entry,
link, or deleted-link) represented by the entry. If omitted, the entry
represents an entity.
·
odata.readLink:
the link used to read the entity, if the odata.id does not represent a URL that
can be used to read the entity.
·
odata.editLink:
the link used to edit/update the entry, if the entity is updatable and the
odata.id does not represent a URL that can be used to edit the entity.
·
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 be 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 MAY specify odata.metadata=none
in order to request that the service omit control information. In this case,
the service MAY omit odata.* annotations other than
odata.nextLink,
odata.count
and odata.deltaLink.
These annotations MUST continue to be included, as applicable, even in the odata.metadata=none case.
3.2 Controlling the Representation
of Numbers
The client MAY specify the format parameter IEEE754Compatible for the application/json
format. If specified the producer MUST serialize Edm.Int64
and Edm.Decimal numbers as strings.
This is due to the fact that JavaScript numbers are 64-bit
binary format IEEE 754 values [ECMAScript]
(see section
4.3.1.9), so integers lose precision past 15 digits, and decimals lose
precision due to the conversion from base 10 to base 2.
OData JSON payloads that format Edm.Int64
and Edm.Decimal values as strings MUST specify this
format parameter in the media type returned in the Content-Type
header.
This section describes common characteristics of 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 structured almost identical; the few existing differences
will be explicitly called out in the respective subsections.
4.1 Header Content-Type
Requests and responses in JSON MUST have a Content-Type header value 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.
Requests and responses MAY add the odata.streaming
parameter with a value of true or false, see section Payload Ordering Constraints.
4.2 Message Body
Each message body MUST be represented as a single JSON
object. This object is either the representation of an entity, an entity reference or a complex type instance, or it contains a
name/value pair whose name MUST be value and whose
value MUST be the correct representation for a primitive value, a collection of primitive values, a collection of complex values, a collection of entities, or a collection of entries
that represent changes to a
previous result.
4.3 Relative URLs
URLs present in a payload (whether request or response) MAY
be represented as relative URLs to the metadata URL. Processors expanding
the URLs MUST use normal URL expansion rules and use the metadata URL as a
base. The reference resolution rules defined in [RFC3986]
imply that the part starting with $metadata# is
ignored when resolving the relative URL.
Example:
{
"odata.metadata": "http://host/service/$metadata#Customers/@Element",
...
"odata.editLink":
"Customers('ALFKI')",
...
"Orders@odata.navigationLink":"Customers('ALFKI')/Orders",
...
}
The resulting
absolute URLs are http://host/service/Customers('ALFKI')
and http://host/service/Customers('ALFKI')/Orders.
4.4 Payload
Ordering Constraints
Ordering constraints MAY be imposed on the JSON payload in
order to support streaming scenarios. These ordering constraints MUST only be
assumed if explicitly specified as some clients (and servers) might not be able
to control, or might not care about, the order of the JSON properties in the
payload.
Clients can request that a JSON response conform to these
ordering constraints by specifying a media type of application/json with the odata.streaming=true
parameter in the Accept header
or $format query option.
Services MUST return 406 Not Acceptable
if the client only requests streaming and the service does not support it.
Processors MUST only assume streaming support if it is
explicitly indicated in the Content-Type header via
the odata.streaming=true parameter. A payload with
Content-Type:
application/json;odata.metadata=minimal;odata.streaming=true
can thus be assumed to support streaming whereas a payload
with
Content-Type:
application/json;odata.metadata=minimal
cannot be assumed to support streaming.
JSON producers are encouraged to follow the payload ordering
constraints whenever possible (and include the odata.streaming=true
content type parameter) to support the maximum set of client scenarios.
To support streaming scenarios the following payload
ordering constraints have to be met:
- If present, the odata.metadata
annotation MUST be the first property in the JSON object.
- The odata.type annotation, if
present, MUST appear next in the JSON object.
- The odata.id and odata.etag annotations MUST appear before any
property or property annotation.
- All property annotations for property MUST appear as a
group immediately before the property they annotate. The one exception is
the odata.nextlink annotation of an expanded
collection which MAY appear after the navigation property it annotates.
- All other odata.* annotations MAY
appear anywhere in the payload (as long as they are not violating any of
the above rules).
- Annotations for navigation properties MUST appear after
all structural properties.
4.5 Control Information
In addition to the “pure data” a message body MAY contain
control information that is represented as annotations
whose names start with odata followed by a dot.
Clients that encounter unknown
annotations in any namespace,
including the odata namespace, MUST NOT stop processing and MUST NOT signal an
error.
4.5.1 Annotation odata.metadata
The odata.metadata
annotation returns the metadata URL (see [OData-Protocol])
for the payload. The odata.metdata
annotation MUST be the first property of any JSON response that does not
specify odata.metadata=none.
The odata.metadata
annotation MUST also be included for entities whose entity set cannot be
determined from the metadata URL of the collection. This URL MAY be absolute or
relative to the metadata URL of the collection.
The odata.metadata
annotation MUST also be applied to navigation links for navigation properties
not described in the metadata of the containing type. In this case the metadata
URL MAY be relative to the metadata URL describing the parent entity and
becomes the root metadata URL for the related entity or collection.
For more information on the format of the metadata URL, see [OData-Protocol].
Request payloads in JSON do not require metadata URLs.
However, if the request does include the metadata URL, relative
URLs MAY be used in the request payload.
Response payloads MUST NOT contain the metadata URL if odata.metadata=none is
requested.
Example:
{
"odata.metadata": "http://host/service/$metadata#Customers/@Element",
"odata.metadataEtag": "A1FF3E230954908F",
...
}
4.5.2 Annotation odata.metadataEtag
The odata.metadataEtag annotation
MAY appear in a response in order to specify the entity tag (ETag) that can be
used to determine the version of the metadata of the response.
For details on how ETags are used, see [OData-Protocol].
4.5.3 Annotation odata.type
The annotation odata.type MUST
appear if the type cannot be heuristically determined, as described below, and
one of the following is true:
·
The type is derived from the type specified for the (set of)
entities or (collection of) complex type instances, or
·
The type is for a property whose type is not declared in $metadata.
The following heuristics are used to determine the primitive
type of a dynamic property in the absence of the odata.type
annotation:
- Boolean values have a first-class representation in JSON
and do not need any additional annotations.
- Numeric values have a first-class representation in JSON
and do not need any additional annotations. If the value of a property is
represented as a number without a dot (.), e or E embedded, the
type should be interpreted as an integer value.
- Similarly, decimal, double, and single values use the same
representation and do not need any additional annotations. If the value of
a property is represented as a number with a single dot (.), and/or a single e
or E embedded, the type
should be interpreted as a decimal, double, or single value. The values NaN, INF, and -INF are serialized as strings and MUST have an odata.type
annotation to specify the numeric type.
- String values do have a first class representation in
JSON, but there is an obvious collision: OData also encodes a number of
other primitive types as strings, e.g. DateTimeOffset,
Int64,in the presence of the IEEE754Compatible format
parameter etc. If a property appears in JSON string format,
it should be treated as a string value unless the property is known (from
the metadata document) to have a different type.
If the odata.type annotation is
present, its value MUST be the namespace- or alias-qualified name of the
instance’s type, in which case the type MUST be defined by the root of the current
metadata URL, otherwise it MUST be a full URL to a metadata document with the
namespace- or alias-qualified name of the instance’s type appended as a URL
fragment.
For more information on namespace- and alias-qualified
names, see Error! Reference source not found..
For example, the following represents an entity whose type
is Model.VipCustomer, defined
within the http://host/service/$metadata
document:
{
"odata.metadata":
"http://host/service/$metadata#Customers/@Element",
"odata.type":
"Model.VipCustomer",
"ID":
2,
...
}
The
following represents an entity whose type is Model.VipCustomer,
defined within the http://host/alternate/$metadata
document:
{
"odata.metadata":
"http://host/service/$metadata#Customers/@Element",
"odata.type":
"http://host/alternate/$metadata#Model.VipCustomer",
"ID":
2,
...
}
The odata.count annotation
contains the inlinecount of a set of
entities or a collection of entity
references, see [OData-Protocol,
section 10.2.3.7 The $inlinecount System Query Option]. Its value MUST be
an Edm.Int64 value corresponding
to the total count of members in the collection represented by the request.
4.5.5
Annotation odata.nextLink
The odata.nextLink annotation
indicates that a response is only a subset of the requested set of entities or
collection of entity references. It contains a URL that allows retrieving the
next subset of the requested set or collection.
Expanded to-many
navigation properties MAY be also annotated with this annotation.
4.5.6 Annotation odata.deltaLink
The odata.deltaLink annotation
contains a URL that can be used to retrieve changes to the current set of
results. The odata.deltaLink annotation MUST only
appear on the last page of results. A page of results MUST NOT have both an odata.deltaLink annotation and an odata.nextLink
annotation.
4.5.7 Annotation
odata.id
The odata.id annotation contains
a durable, opaque, globally unique identifier for an entity or set of entities.
Its content MUST be an IRI as defined in [RFC3987]. Services
are encouraged to use a dereferenceable URL for the id, but consumers MUST NOT
assume this IRI can be de-referenced, nor assume any semantics from its
structure.
By convention its value is identical to the canonical URL of
the entity, as defined in [OData-URL]. The
annotation odata.id will only appear in minimal metadata and no metadata cases if its value deviates from the
canonical URL of the entity.
4.5.8
Annotation odata.editLink and odata.readLink
The odata.editLink annotation
contains a URL that can be used to read, update, or delete the entity. It MUST
appear for updatable entities if odata.metadata=full is requested
or if its value differs from the value of the odata.id.
The odata.readLink annotation
contains a URL that can be used to read the entity. It MUST appear if odata.metadata=full
is requested and its value differs from the value of the odata.id
and the odata.editlink is not
present.
4.5.9 Annotation odata.kind
The odata.kind
annotation is used to differentiate the kind of entry represented by the JSON
object according to the table below. Where the object represents an entity, or
entity reference, the odata.kind
annotation is optional and generally not included.
4.5.10 Annotation odata.etag
The odata.etag annotation MAY be applied to an entity. The value of the annotation is an entity tag (ETag)
which is an opaque string value that can be used in a subsequent request to
determine if the value of the entity has changed.
For details on how ETags are used, see [OData-Protocol].
4.5.11 Annotation odata.navigationLink and odata.associationLink
The odata.navigationLink
annotation contains a URL that can be used to retrieve an entity or collection
of entities related to the current entity via a navigation property.
The odata.associationLink:
annotation contains a URL that can be used to retrieve a reference to an entity
or a collection of references to entities related to the current entity via a
navigation property.
4.5.12 Annotation odata.media*
For media entities and named stream properties that don't follow standard
URL conventions as defined in [OData-URL], at
least one of the annotations odata.mediaEditLink and
odata.mediaReadLink MUST be included.
The odata.mediaEditLink
annotation contains a URL that can be used to update the binary stream
associated with the media entity or named stream property. It MUST be included
for updatable media entries if it differs from the value of the odata.id, and for updatable named
stream properties if it differs from standard URL conventions.
The odata.mediaReadLink
annotation contains a URL that can be used to read the binary stream associated
with the media entity or named stream property. It MUST be included if its
value differs from the value of the associated odata.mediaEditLink,
if present, or the value of the odata.id
for media entities if the associated odata.mediaEditLink
is not present.
The odata.mediaContentType annotation
MAY be included; its value SHOULD match the content type of the binary stream
represented by the odata.mediaReadLink URL. This is
only a hint; the actual content type will be included in a header when the
resource is requested.
The odata.mediaEtag annotation
MAY be included; its value MUST be the ETag of the binary stream represented by
this media entity or named stream property.
Example:
{
"odata.metadata":
"http://host/service/$metadata#Employees/@Element",
"odata.mediaReadLink":
"Employees(1)/$value",
"odata.mediaContentType":
"image/jpeg",
"EmployeeID":
1,
...
}
A service document in JSON is represented as a single JSON
object with at least two properties; odata.metadata
and odata.value.
The value of the odata.metadata
property MUST be the URL of the metadata document, without any fragment part.
The value of the value property
MUST be a JSON Array containing one element for each entity set and function
import with an explicit or default value of true
for the attribute IncludeInServiceDocument and each
named entity exposed by the service, see [OData-CSDL].
Each element MUST be a JSON object with at least two
name/value pairs, one with name name containing the
name of the entity set, function import, or named entity, and one with name url containing the URL of the entity set, which may be
absolute or relative to the metadata URL. It MAY contain a name/value pair with
name title containing a human-readable,
language-dependent title for the object.
JSON objects representing an entity set MAY contain an
additional name/value pair with name kind and a
value of EntitySet.
JSON objects representing a function or action import MUST
contain this name/value pair with a value of FunctionImport
or ActionImport, respectively.
JSON objects representing a named entity MUST contain this
name/value pair with a value of Entity.
JSON objects representing a related service document MUST
contain this name/value pair with a value of ServiceDocument.
Clients that
encounter unknown values of the kind name/value
pair not defined in this version of the specification MUST NOT stop processing and MUST NOT signal an error.
Service documents MAY contain annotations.
Example:
{
"odata.metadata": "http://host/service/$metadata",
"value": [
{
"name": "Orders",
"kind": "EntitySet",
"url": "Orders"
},
{
"name": "OrderDetails",
"title": "Order Details",
"url": "OrderDetails"
},
{
"name": "TopProducts",
"title": "Best-Selling Products",
"kind": "FunctionImport",
"kind": "FunctionImport",
"url": "TopOrders"
},
{
"name": "Contoso",
"title": "Contoso Ltd.",
"kind": "Entity",
"url": "Contoso"
},
{
"name": "Human Resources",
"kind": "ServiceDocument",
"url": "http://host/HR/"
}
]
}
An entity MUST be serialized as a JSON object.
Each property to be transmitted
MUST be represented as a name/value pair within the object. The order
properties appear within the object MUST be considered insignificant.
An entity in a payload MAY be a complete entity, a projected
entity (see [OData-Protocol, section 10.2.3.2
The $select System Query Option]), or a partial entity update (see [OData-Protocol, section 10.3.1.2. Differential
Update]). A complete entity MUST transmit every property, with the
exception of unexpanded 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.
An entity representation can be (modified and) round-tripped
to the server directly. The metadata URL can but does not have to be removed;
the server will ignore it if it is present.
Example:
{
"odata.metadata":
"http://host/service/$metadata#Customers/@Element",
"CustomerID": "ALFKI",
"CompanyName": "Alfreds Futterkiste",
"ContactName": "Maria Anders",
"ContactTitle": "Sales Representative",
"Phone": "030-0074321",
"Fax": "030-0076545",
"Address": {
"Street": "Obere Str. 57",
"City": "Berlin",
"Region": null,
"PostalCode": "12209",
"Country": "Germany"
}
}
A property within an entity or complex type instance is
represented as a name/value pair. The name MUST be the name of the property,
the value is represented depending on its type as a primitive
value, a complex value, a collection of primitive values, or a collection
of complex values.
7.1 Primitive Value
Primitive values are represented following the rules of [RFC4627].
Null values are represented as the JSON literal null.
Values of type Edm.Boolean are
represented as the JSON literals true and false
Values of types Edm.Byte, Edm.SByte, Edm.Int16, Edm.Int32, Edm.Int64, Edm.Single, Edm.Double, and Edm.Decimal are represented as JSON numbers, except for NaN, INF, and –INF which are represented as strings.
Values of type Edm.String are
represented as JSON strings, using the JSON string escaping rules.
Values of type Edm.Binary, Edm.Date, Edm.DateTimeOffset, Edm.Duration, Edm.Guid, and Edm.TimeOfDay as well as enumeration values are
represented as JSON strings whose content satisfies the rules binaryValue, dateValue, dateTimeOffsetValue, durationValue,
guidValue, timeOfDayValue,
and enumValue, respectively, in [OData-ABNF].
Geography and geometry values are represented as defined in [GeoJSON].
Example:
{
"NullValue": null,
"TrueValue": true,
"FalseValue": false,
"IntegerValue": -128,
"DoubleValue": 3.1415926535897931,
"SingleValue": "INF",
"DecimalValue": "34.95",
"StringValue": "Say
\"Hello\",\nthen go",
"DateValue": "2012-12-03",
"DateTimeOffsetValue": "2012-12-03T07:16:23Z",
"DurationValue": "P12DT23H59M59.999999999999S",
"TimeOfDayValue": "07:59:59.999",
"GuidValue": "01234567-89ab-cdef-0123-456789abcdef",
"Int64Value": "0",
"ColorEnumValue": "Yellow",
"GeographyPoint":
{"type":"point","coordinates":[142.1,64.1]}
}
7.2 Complex
Value
A complex 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 type of the
property.
It MAY have name/value pairs for instance annotations,
including odata.* annotations.
Example:
{
"odata.metadata":
"http://host/service/$metadata#Customers/@Element",
...
"Address": {
"Street": "Obere Str. 57",
"City": "Berlin",
"Region": null,
"PostalCode": "12209",
"Country": "Germany"
}
}
Collection
of Primitive Values
7.3
Collection of Primitive Values
A collection of primitive values MUST be represented as a
JSON array, and each element in the array MUST be the representation of a primitive value.
Example:
{
"odata.metadata":
"http://host/service/$metadata#Customers/@Element",
...
"EmailAddresses": [
"Julie@Swansworth.com",
"Julie.Swansworth@work.com"
]
}
7.4 Collection of Complex Values
A collection of complex values MUST be represented as a JSON
array, and each element in the array MUST be the representation of a complex value.
Example:
{
"PhoneNumbers": [
{
<data:Number>425-555-1212</data:Number>
<data:PhoneType>Home</data:PhoneType>
},
{
<metadata:element metadata:type="Person.CellPhoneNumber">
<data:Number>425-555-0178</data:Number>
<data:PhoneType>Cell</data:PhoneType>
<data:CellCarrier>Sprint</data:CellCarrier>
}
]
}
A navigation property represents a reference from a source
entity to zero or more related entities.
8.1 Navigation
Link
The navigation link for a navigation property is represented
as a name/value pair. The name MUST be the name of the property, followed by @odata.navigationLink. The value MUST be a URL that
allows retrieving the related entity or collection of entities. It MAY be
relative to the odata.metadata URL.
The navigation link for a navigation property is only
represented if the client requests odata.metadata=full
or if the client explicitly selects the navigation property in $select.
Example:
{
"odata.metadata": "http://host/service/$metadata#Customers/@Element",
...
"Orders@odata.navigationLink":"Customers('ALFKI')/Orders",
...
}
8.2
Association Link
The association link for a navigation property is
represented as a name/value pair. The name MUST be the name of the property,
followed by @odata.associationLink. The value MUST
be a URL that can be used to retrieve the reference or collection of references
to the related entity or entities. It MAY be relative to the odata.metadata URL.
The association link for a navigation property is only
represented if the client requests odata.metadata=full
or if the client explicitly selects the navigation property in $select.
Example:
{
"odata.metadata": "http://host/service/$metadata#Customers/@Element",
...
"Orders@odata.associationLink":"Customers('ALFKI')/Orders/$ref",
...
}
An expanded navigation property is represented as a
name/value pair. The name MUST be the name of the navigation property, the
value MUST be the correct representation of the related entity or collection of
entites.
If at most one entity can be related, the value MUST be the
representation of the related entity, or null if no
entity is currently related.
If a collection of entities can be related, it MUST be
represented as a JSON array. Each element MUST be the representation of an entity or the representation of an entity reference. An
empty set of entities (one that contains no entities) MUST be represented as an
empty JSON array. The navigation property MAY be annotated with odata.count or odata.nextlink.
Example:
{
"odata.metadata": "http://host/service/$metadata#Customers/@Element",
...
"Orders@odata.count": "42",
"Orders": [ ... ],
"Orders@odata.nextLink": "...",
...
"CustomerDemographics": { ... },
...
}
8.4
Deep Inserts
When inserting a new entity with a POST
request, related new entities MAY be specified using the same representation as
for an expanded navigation property.
Deep inserts are not allowed in update operations using PUT or PATCH requests.
Example for inserting a new order with order details and a
new customer:
{
"Customer": {
"CustomerID":
"ANEWONE",
...
},
"Details": [
{
"ProductID": 28,
"ProductID": 28,
...
},
{
"ProductID": 39,
"ProductID": 39,
...
}
],
"OrderID": 11643,
"CustomerID":
"ANEWONE",
"EmployeeID":
6,
...
}
When inserting or updating an entity, relationships of
navigation properties MAY be inserted or updated via bind operations. A bind
operation is encoded as a property annotation odata.bind
on the navigation property it belongs to and has a single value for singleton
navigation properties or an array of values for collection navigation
properties.
The values MUST be the ids
of the related entities. They MAY be relative URLs.
For insert operations collection navigation property bind
operations and deep insert operations MAY be combined. In this case, the bind
operations MUST appear before the deep insert operations in the payload.
For update operations a bind operation on a collection
navigation property adds additional relationships, it does not replace existing
relationships, while bind operations on an entity navigation property update
the relationship.
Example for assigning an existing product to an existing category
with a partial update request:
PATCH
http://host/service/Products(42) HTTP/1.1
{
"Category@odata.bind": "Categories(6)"
"Category@odata.bind":
"Categories(6)"
}
An entity MAY
have one or more named stream properties. The actual stream data is not
contained in the entity. Instead stream property data is read and edited via
URLs. The value for a named stream property contains the URLs for reading and
editing the stream data along with other metadata for the stream.
The value of a named stream property is represented as a set
of odata.media*
annotations like in the following example.
{
"odata.metadata": "http://server/HR/$metadata#Employees/@Element",
...
"Thumbnail@odata.mediaReadLink": “http://server/Thumbnail546.jpg",
"Thumbnail@odata.mediaEditLink": “http://server/uploads/Thumbnail546.jpg",
"Thumbnail@odata.mediaContentType": "image/jpeg",
"Thumbnail@odata.mediaEtag": "####",
...
}
Media entities are entities that describe a media resource,
for example a photo. They are represented as other entities and in addition
contain odata.media* annotations.
Example:
{
"odata.metadata":
"http://host/service/$metadata#Employees/@Element",
"odata.mediaReadLink": "Employees(1)/$value",
"odata.mediaContentType": "image/jpeg",
"EmployeeID": 1,
...
}
If the message represents an individual property, it is
represented as a JSON object,
A property that is of a primitive type is represented as an
object with a single name/value pair whose name is value
and whose value is a primitive value,
A property that is of a collection type is represented
similarly as an object with a single name/value pair whose name is value. Its value is the JSON representation of a collection of complex
type or primitive values.
A property that is of complex type are represented as a complex value. A complex value is a JSON object, so
no “wrapper object” is required,
Examples:
{
"odata.metadata":
"http://host/service/$metadata#Edm.String",
"value":
"Pilar Ackerman"
}
{
"odata.metadata":
"http://host/service/$metadata#Collection(Edm.String)",
"value":
["gazpacho", "tomato", "vegetarian"]
}
{
"odata.metadata":
"http://host/service/$metadata#Model.BillingAddress",
"Line1":
"12345 Grant Street",
"Line2":
null,
"City":
"Taft",
"State":
"Ohio",
"ZipCode":
"98052"
}
Note that in requests the metadata URL is optional.
12
Collections of Entities
A collection of entities MUST be represented as a JSON
object. This object MUST contain a value name/value
pair. It MAY contain odata.metadata, odata.count,
odata.nextLink,
or odata.deltaLink
annotations.
If present, the odata.metadata
annotation MUST be the first name/value pair in the response.
The odata.count name/value pair
represents the inlinecount. If present, it MUST come before the value name/value pair.
The value value MUST be a JSON
array. Each element MUST be a correctly formatted representation of an entity or a representation
of an entity reference. An empty collection MUST be represented as an empty
JSON array.
The odata.nextLink annotation
MUST be included if the response represents a partial response. If provided, it
MUST be the last name/value pair in the response.
Functions or actions that are bindable to this set of
entities are advertised in the “wrapper object” in the same way as functions or actions are advertised in the
object representing a single entity.
Example:
{
"odata.metadata": "...",
"odata.count": 37,
"value": [
{
... },
{
... },
{
... }
],
"odata.nextLink": "...?$skiptoken=342r89",
}
A resource reference is a reference to an entity or a
property of an entity. Resource references referring to an entity are called
entity references.
An entity reference MAY take the place of an entity instance
in a JSON payload, based on the client request.
A resource reference
MUST be serialized as a JSON object.
The first name/value pair of the JSON object MUST be named odata.ref and MUST contain the id of the referenced entity.
The following example shows an entity reference to order
10643:
{
"odata.ref":"http://host/service/Orders(10643)"
}
Responses from a delta request are returned as a JSON
object. The JSON object MUST contain an array-valued property named
"value" containing all added,
changed, or deleted entities, as well as added or deleted links between entities, and MAY
contain additional, unchanged entities.
If the delta response contains a partial list of changes, it
MUST include a next link for the client
to retrieve the next set of changes.
Changes are generally ordered by the service according to
when the last change occurred to an entity, but MUST be ordered such that
applying all changes across all pages, in order, to the initial set yields a
consistent result.
The last page of a delta response SHOULD contain a delta link for retrieving subsequent changes once
the current set of changes has been applied to the initial set.
If the response from the delta link contains an inlinecount, the returned count is the count of added,
changed, or deleted entities. $count
and $inlinecount returned from a
delta link do not include added or deleted links.
The following example shows the following ordered changes:
1. ContactName
for customer 'BOTTM' was changed to "Susan Halvenstern"
2. Order
10643 was removed from customer 'ALFKI'
3. Order
10645 was added to customer 'BOTTM'
4.
The shipping information for order 10643 was updated
5.
Customer 'ANTON' was deleted
{
"odata.metadata":"http://DeltaService.svc/$metadata#Customers/@Delta
",
"value":
[
{
"odata.id":"http://DeltaService.svc/Customers('BOTTM')'",
"ContactName":"Susan Halvenstern"
},
{
"odata.kind" : "deletedLinkEntry",
"source":"http://DeltaService.svc/Customers(ALFKI)'",
"relationship":"Orders",
"target":"http://DeltaService.svc/Orders(10643)",
"when":"2012-11-07T15:38"
},
{
"odata.kind" : "linkEntry",
"source":"http://DeltaService.svc/Customers('BOTTM')",
"relationship":"Orders",
"target":"http://DeltaService.svc/Orders(10645)",
"when":"2012-11-07T15:38"
},
{
"odata.type" : "Northwind.Order",
"odata.id":"http://DeltaService.svc/Orders(10645)",
"odata.metadata":"#Orders",
"ShipName":"Bottom-Dollar Markets",
"ShipAddress":"23 Tsawassen Blvd.",
"ShipRegion":"BC",
"ShipPostalCode":"T2F 8M4",
"ShipCountry":"Canada"
},
{
"odata.kind":"deletedEntry",
"id":"http://DeltaService.svc/Customers('ANTON')",
"when":"2012-11-07T15:38",
"reason": "deleted"
}
],
"odata.deltaLink":
"http://DeltaService.svc/Customers?$expand=orders&$deltatoken=8015"
}
14.1
Added/Changed Entity
Added or changed entities within a delta response are
represented as entities.
Added entities MUST include all selected properties and MAY
include additional, unselected properties. Collection-valued properties are
treated as atomic values; any collection-valued properties returned from a
delta request MUST contain all current values for that collection.
Changed entities MUST include all selected properties that
have changed and MAY include additional properties.
Entities that are not part of the set specified by the
Metadata URL MUST include the odata.metadata attribute to
specify the set of the entity.
Entities MUST include annotations for selected navigation
links but MUST NOT include expanded navigation properties inline.
14.2 Deleted Entity
Deleted Entries in JSON are returned as deleted-entry
objects. Delta responses MUST contain a deleted-entry for each deleted entity.
The deleted-entry object has the following properties:
odata.kind
– The odata.kind property MUST be the first property
and MUST be "deletedEntry"
id
– The id of the deleted entity (same as the odata.id
returned or computed when calling GET on resource)
reason
– An optional string value; either "deleted",
if the entity was deleted (destroyed), or "changed"
if the entity was removed from membership in the result (i.e., due to a data
change).
when
– An optional Datetime value indicating when the element was deleted.
14.3 Link
Links within a delta response are represented as link-entry
objects.
Delta responses MUST contain a link-entry for each added
link that corresponds to a $expand
path in the initial request.
The link-entry object has the following properties:
odata.kind
– The odata.kind
property MUST be the first property and MUST be "linkEntry"
source
– The id of the entity from which the relationship is defined
relationship
- the name of the relationship property on the parent object
target
– The id of the related entity
when
– An optional datetime value indicating when the link was created
The link-entry MUST contain a source property specifying the odata.id
of the entity from which the link exists, a relationship property specifying
the name of the navigation property for which the link was specified, and a target
attribute containing the odata.id of the related resource.
The link-entry MAY include an optional when
attribute specifying when the link was created.
14.4 Deleted Link
Deleted links within a delta response are represented as
deleted-link-entry objects.
Delta responses MUST contain a deleted-link-entry for each
deleted link that corresponds to a $expand
path in the initial request, unless either of the following is true:
·
The source or target entity has been deleted
·
The maximum cardinality of the related entity is one and there is
a subsequent link-entry that
specifies the same source and relationship.
The deleted-link-entry has the following properties:
odata.kind
– The odata.kind
property MUST be the first property and MUST be "deletedLinkEntry"
source
– The id of the entity from which the relationship is defined
relationship
- the name of the relationship property on the parent object
target
– The id of the related entity
when
– An optional datetime value indicating when the link was created
The deleted-link-entry MUST contain a source
property specifying the odata.id of the entity from which
the link was deleted, a relationship property specifying
the name of the navigation property for which the link was specified, and a target
attribute containing the odata.id of the related resource.
The deleted-link-entry MAY include an optional when
attribute specifying when the link was created.
A function that is bindable to the current entity is
advertised via a name/value pair. The name MUST be a hash (#) character followed by the namespace- or
alias-qualified name of the function. The value MUST be a JSON object.
Functions that are bindable to a set of entities are
advertised in representations of a collection of entities.
If function overloads exist that cannot be bound to the
current entity type, the name SHOULD address a specific function overload by
appending a parentheses-enclosed, comma-separated list of parameter names, each
name followed by a colon and its namespace- or alias-qualified type, see rule qualifiedFunctionName in [OData-ABNF].
If odata.metadata=full is requested, each value object
MUST have at least the two name/value pairs title
and target. It MAY contain annotations. The order of the name/value
pairs MUST be considered insignificant.
The target name/value pair MUST
contain a bound function or action URL.
The title name/value pair MUST
contain the function or action title as a string.
If odata.metadata=minimal is requested, the target name/value pair MUST be included if its value
differs from the canonical function or action URL.
Example for a minimal representation of a function where all
overloads are applicable:
{
"odata.metadata": "http://host/service/$metadata#Employees/@Element",
"#Model.RemainingVacation":
{},
...
}
Example for a full representation of a specific overload
{
"odata.metadata": "http://host/service/$metadata#LeaveRequests/@Element",
...
"#Model. RemainingVacation(year:Edm.Int32)": {
"title":
"Remaining Vacation",
"target":
"Employees(2)/RemainingVacation"
},
...
}
An action that is bindable to the current entity is
advertised via a name/value pair. The name MUST be a hash (#) character followed by the namespace- or
alias-qualified name of the action. The value MUST be a JSON object.
Actions that are bindable to a set of entities are
advertised in representations of a collection of entities.
If odata.metadata=full is requested, each value object
MUST have at least the two name/value pairs title
and target. It MAY contain annotations. The order of these name/value
pairs MUST be considered insignificant.
The target name/value pair MUST
contain a bound function or action URL.
The title name/value pair MUST
contain the function or action title as a string.
If odata.metadata=minimal is requested, the target name/value pair MUST be included if its value
differs from the canonical function or action URL.
Examples:
{
"odata.metadata": "http://host/service/$metadata#LeaveRequests/@Element",
"#Model.Approval":
{},
...
}
{
"odata.metadata": "http://host/service/$metadata#LeaveRequests/@Element",
...
"#Model.Approval": {
"title":
"Approve Leave Request",
"target":
"LeaveRequests(2)/Approval"
},
...
}
Action parameter values MUST be encoded in a single JSON
object in the request body.
Each non-binding parameter value specified MUST be encoded
as a separate name/value pair in this JSON object. The name is the name of the
parameter. The value is the parameter value in the JSON representation appropriate
for its type.
Any parameter values not specified in the JSON object MUST
be assumed to have the default value specified in the service metadata, see [OData-CSDL].
Example:
{
"param1": 42,
"param2": {
"Street": "One Microsoft Way",
"Zip": 98052
},
"param3": [ 1, 42, 99 ],
"param4": null
}
Annotations are an extensibility mechanism that allows
servers and clients to include information other than the raw data in the
request or response. Annotations are used to include control information in
many payloads.
Annotations are easily identifiable as name/value pairs that
have a dot (.) as part of the name. All annotations
that start with odata are reserved for future
extensions of the protocol and format. Custom annotations are annotations that
have a non-empty prefix that is different from odata.
Annotations 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.
{
"odata.metadata":
"http://host/service/$metadata#Customers",
"com.contoso.customer.setkind" : "VIPs",
"value": [
{
"com.contoso.customer.kind": "VIP",
"com.contoso.display.order": 1,
"CustomerID": "ALFKI",
"CompanyName@com.contoso.display" : { "title" : true,
"order" : 1 },
"CompanyName": "Alfreds Futterkiste",
"Orders@com.contoso.purchaseorder.priority" : 1
}
]
}
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.
18.1
Annotate a JSON Object
When annotating a name/value pair
for which the value is represented as a JSON object, each annotation MUST be
placed within the object and MUST be represented as a single name/value pair.
The name MUST be the namespace- or alias-qualified 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.
When annotating a name/value pair
for which the value is represented as a JSON array or primitive value, each
annotation that applies to this name/value pair MUST be placed next to the
annotated name/value pair and MUST be represented as a single name/value pair.
The name MUST be the same as the name of the name/value pair
being annotated, followed by the “at” sign (@),
followed by the namespace- or alias-qualified 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.
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 MUST contain name/value pairs with the names code and message, and it MAY
contain name/value pairs with the names target,
details and innererror.
The value for the code name/value
pair MUST be a language-independent 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 a human-readable, language-dependent representation of the error.
The Content-Language header MUST contain the
language code from [RFC4627] Crockford, D., “The
application/json Media Type for JavaScript Object Notation (JSON)”, RFC 4627, July
2006. http://tools.ietf.org/html/rfc4627.
[RFC5646] corresponding to the
language in which the value for message is written.
The value for the target
name/value pair is the target of the particular error (for example, the name of
the property in error).
The value for the details
name/value pair MUST be an array of JSON objects that MUST contain name/value
pairs for code and message, and MAY contain a name/value
pair for target, as described
above.
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. The innererror name/value pair SHOULD only be used in development
environments in order to guard against potential security concerns around
information disclosure.
Error responses MAY contain annotations in any of its JSON objects.
Example:
{
"error": {
"code": "501",
"message": "Not supported Functionality",
"details": [
{
"code": "301",
"target":
"$search"
"message": "$search query option not supported",
}
]
"innererror": {
"trace": [...],
"context": {...}
}
}
}
Implementations MAY add custom content anywhere
allowed by Error! Reference source not found., Section 6, “Extending
Atom”, and Error! Reference source not found., Section 6.2 “Document
Extensibility”. However, custom elements and attributes MUST NOT be defined in
the OData Data Namespace nor the OData Metadata Namespace, and SHOULD not be
required to be understood by the receiving party in order to correctly
interpret the rest of the payload as the receiving party MUST ignore unknown
foreign markup according to Error! Reference source not found..
A conforming OData service MUST comply with one of the
conformance levels defined in [OData-Protocol].
The exception to this are the constructs defined in Delta Response, which are only required for
clients that request changes
In order to conform to the OData JSON format, a service:
·
MUST support the application/json
media type in the Accept header
·
SHOULD support the $format system query option
·
MAY support the odata.streaming=true parameter in
the Accept header
·
MUST return well-formed JSON payloads
·
MUST support odata.metadata=full
·
MAY return full metadata regardless of odata.metadata
·
MUST include the odata.nextLink annotation in the
feed for partial results
·
MUST NOT violate any other aspects of this OData JSON
specification
In order to
be a conforming consumer of the OData JSON format, a client or service:
·
MUST understand odata.metadata=minimal
OR explicitly specify odata.metadata=none or odata.metadata=full in request
·
MUST be prepared to consume a response with full metadata
·
MUST NOT require odata.streaming=true in the Content-Type header
·
MUST be prepared to receive all data types
o
defined in this specification (client)
o
exposed by the service (service)
·
MUST support entities returned as entity references
·
MUST interpret all odata annotations
defined according to the version of the response
·
MUST be prepared to receive any annotations, including custom annotations and
odata not defined in the OData version of the
response
Appendix A. Acknowledgments
The contributions of the OASIS OData Technical Committee members,
enumerated in [OData-Protocol], are gratefully
acknowledged.
Appendix B.
Revision History
|
Revision
|
Date
|
Editor
|
Changes Made
|
|
Working Draft 01
|
2012-08-22
|
Michael Pizzo
|
Translated Contribution to OASIS format/template
|
|
Working Draft 01.1
|
2013-1-31
|
Ralf Handl
|
Adopted new, more concise JSON format
|
|
Committee Specification Draft 01
|
2013-04-26
|
Ralf Handl
Michael Pizzo
|
Expanded error information
Added enumerations
Fleshed out descriptions and examples and addressed
numerous editorial and technical issues through processed through the TC
Added Conformance section
|
