context (odata.context)metadataEtag (odata.metadataEtag)type (odata.type)count (odata.count)nextLink (odata.nextLink)delta (odata.delta)deltaLink (odata.deltaLink)id (odata.id)editLink and readLink (odata.editLink and odata.readLink)etag (odata.etag)navigationLink and associationLink (odata.navigationLink and odata.associationLink)media* (odata.media*)removed (odata.removed)collectionAnnotations (odata.collectionAnnotations)context (odata.context)metadataEtag (odata.metadataEtag)type (odata.type)count (odata.count)nextLink (odata.nextLink)delta (odata.delta)deltaLink (odata.deltaLink)id (odata.id)editLink and readLink (odata.editLink and odata.readLink)etag (odata.etag)navigationLink and associationLink (odata.navigationLink and odata.associationLink)media* (odata.media*)removed (odata.removed)collectionAnnotations (odata.collectionAnnotations)mediaContentType can be nullClient libraries MUST retain the order of objects within an array in JSON responses.
URLs represented as a string within a JSON payload, including batch requests, must follow standard OData encoding rules as defined in OData-URL.
+For relative URLs this means that colons (:) in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the scheme separator. Colons within the query part, i.e. after the question mark character (?), need not be percent-encoded.
URLs present in a payload (whether request or response) MAY be represented as relative URLs.
Relative URLs, other than those in type, are relative to their base URL, which is
Processors expanding the URLs MUST use normal URL expansion rules as defined in RFC3986. This means that if the base URL is a context URL, the part starting with $metadata# is ignored when resolving the relative URL.
Clients that receive relative URLs in response payloads SHOULD use the same relative URLs, where appropriate, in request payloads (such as bind operations and batch requests) and in system query options (such as $id).
URLs represented as a string within a JSON payload, including batch requests, must follow standard OData encoding rules. For relative URLs this means that colons in the path part, especially within key values, MUST be percent-encoded to avoid confusion with the scheme separator. Colons within the query part, i.e. after the question mark character (?), need not be percent-encoded.
Example 2:
{
@@ -609,7 +615,7 @@ 4.3 Relati
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 services) 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 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.
streaming format parameter was prefixed with odata.. Payloads with an OData-Version header equal to 4.0 MUST include the odata. prefix. Payloads with an OData-Version header equal to 4.01 or greater SHOULD NOT include the odata. prefix.
In addition to the “pure data” a message body MAY contain annotations and control information that is represented as name/value pairs whose names start with @.
In requests and responses with an OData-Version header with a value of 4.0 control information names are prefixed with @odata., e.g. @odata.context. In requests and responses without such a header the odata. prefix SHOULD be omitted, e.g. @context.
In some cases, control information is required in request payloads; this is called out in the following subsections.
Receivers that encounter unknown annotations in any namespace or unknown control information MUST NOT stop processing and MUST NOT signal an error.
context (odata.context)context (odata.context)The context control information returns the context URL (see OData-Protocol) for the payload. This URL can be absolute or relative. The fragment portion of the context URL MUST NOT be percent-encoded.
The context control information is not returned if metadata=none is requested. Otherwise it MUST be the first property of any JSON response that allows this control information (this excludes for example error responses).
metadataEtag (odata.metadataEtag)metadataEtag (odata.metadataEtag)The metadataEtag control information 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. If an ETag is returned when requesting the metadata document, then the service SHOULD set the metadataEtag control information to the metadata document's ETag in all responses when using metadata=minimal or metadata=full. If no ETag is returned when requesting the metadata document, then the service SHOULD NOT set the metadataEtag control information in any responses.
For details on how ETags are used, see OData-Protocol.
type (odata.type)type (odata.type)The type control information specifies the type of a JSON object or name/value pair. Its value is a URI that identifies the type of the property or object. For built-in primitive types the value is the unqualified name of the primitive type. For payloads described by an OData-Version header with a value of 4.0, this name MUST be prefixed with the hash symbol (#); for non-OData 4.0 payloads, built-in primitive type values SHOULD be represented without the hash symbol, but consumers of 4.01 or greater payloads MUST support values with or without the hash symbol. For all other types, the URI may be absolute or relative to the type of the containing object. The root type may be absolute or relative to the root context URL.
If the URI references a metadata document (that is, it’s not just a fragment), it MAY refer to a specific version of that metadata document using the $schemaversion system query option defined in OData-Protocol.
count (odata.count)count (odata.count)The count control information occurs only in responses and can annotate any collection, see OData-Protocol section 11.2.5.5 System Query Option $count. Its value is an Edm.Int64 value corresponding to the total count of members in the collection represented by the request.
nextLink (odata.nextLink)nextLink (odata.nextLink)The nextLink control information indicates that a response is only a subset of the requested collection. It contains a URL that allows retrieving the next subset of the requested collection.
The nextLink control information indicates that a response is only a subset of the requested collection. It contains a URL that allows retrieving the next subset of the requested collection.
This control information can also be applied to expanded to-many navigation properties.
delta (odata.delta)delta (odata.delta)The delta control information is applied to a collection-valued navigation property within an added/changed entity in a delta payload to represent changes in membership or value of nested entities.
deltaLink (odata.deltaLink)deltaLink (odata.deltaLink)The deltaLink control information contains a URL that can be used to retrieve changes to the current set of results. The deltaLink control information MUST only appear on the last page of results. A page of results MUST NOT have both a deltaLink control information and a nextLink control information.
The deltaLink control information contains a URL that can be used to retrieve changes to the current set of results. The deltaLink control information MUST only appear on the last page of results. A page of results MUST NOT have both a deltaLink control information and a nextLink control information.
id (odata.id)id (odata.id)The id control information contains the entity-id, see OData-Protocol. By convention the entity-id is identical to the canonical URL of the entity, as defined in OData-URL.
The id control information MUST appear in responses if metadata=full is requested, or if metadata=minimal is requested and any of a non-transient entity’s key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity after
editLink and readLink (odata.editLink and odata.readLink)editLink and readLink (odata.editLink and odata.readLink)The editLink control information contains the edit URL of the entity; see OData-Protocol.
The editLink control information contains the edit URL of the entity; see OData-Protocol.
The readLink control information contains the read URL of the entity or collection; see OData-Protocol.
The editLink and readLink control information is ignored in request payloads and not written in responses if metadata=none is requested.
The default value of both the edit URL and read URL is the entity's entity-id appended with a cast segment to the type of the entity if its type is derived from the declared type of the entity set. If neither the editLink nor the readLink control information is present in an entity, the client uses this default value for the edit URL.
etag (odata.etag)etag (odata.etag)The etag control information MAY be applied to an entity or collection in a response. The value of the control information 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 or collection has changed.
For details on how ETags are used, see OData-Protocol.
The etag control information is ignored in request payloads for single entities and not written in responses if metadata=none is requested.
navigationLink and associationLink (odata.navigationLink and odata.associationLink)navigationLink and associationLink (odata.navigationLink and odata.associationLink)The navigationLink control information in a response contains a navigation URL that can be used to retrieve an entity or collection of entities related to the current entity via a navigation property.
The navigationLink control information in a response contains a navigation URL that can be used to retrieve an entity or collection of entities related to the current entity via a navigation property.
The default computed value of a navigation URL is the value of the read URL appended with a segment containing the name of the navigation property. The service MAY omit the navigationLink control information if metadata=minimal has been specified on the request and the navigation link matches this computed value.
The associationLink control information in a response contains an association 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.
The default computed value of an association URL is the value of the navigation URL appended with /$ref. The service MAY omit the associationLink control information if the association link matches this computed value.
The navigationLink and associationLink control information is ignored in request payloads and not written in responses if metadata=none is requested.
media* (odata.media*)media* (odata.media*)For media entities and stream properties at least one of the control information mediaEditLink and mediaReadLink MUST be included in responses if they don't follow standard URL conventions as defined in OData-URL, sections 4.6 Addressing a property and 4.14 Addressing the Media Stream of a Media Entity, or if metadata=full is requested.
The mediaEditLink control information contains a URL that can be used to update the binary stream associated with the media entity or stream property. It MUST be included for updatable streams if it differs from standard URL conventions relative to the edit link of the entity.
The mediaEditLink control information contains a URL that can be used to update the binary stream associated with the media entity or stream property. It MUST be included for updatable streams if it differs from standard URL conventions relative to the edit link of the entity.
The mediaReadLink control information contains a URL that can be used to read the binary stream associated with the media entity or stream property. It MUST be included if its value differs from the value of the associated mediaEditLink, if present, or if it doesn’t follow standard URL conventions relative to the read link of the entity and the associated mediaEditLink is not present.
The mediaContentType control information MAY be included; its value SHOULD match the media type of the binary stream represented by the mediaReadLink URL. This is only a hint; the actual media type will be included in the Content-Type header when the resource is requested. The presence of mediaContentType with value null MAY be used to indicate the absence of a binary stream.
The mediaEtag control information MAY be included; its value is the ETag of the binary stream represented by this media entity or stream property.
removed (odata.removed)removed (odata.removed)The removed control information is used in delta payloads and indicates that the represented entity is (to be) deleted.
collectionAnnotations (odata.collectionAnnotations)collectionAnnotations (odata.collectionAnnotations)The collectionAnnotations control information can be applied to a collection containing primitive members in order to annotate such primitive members. The value of the collectionAnnotations control information is an array of JSON objects containing an integer property index, specifying the zero-based ordinal index of the primitive item within the collection, along with any annotations that are to be applied to that primitive collection member.
odata control information defined according to the OData-Version header of the payload (section 4.5)odata control information defined according to the OData-Version header of the payload (section 4.6)OData-Version header of the payload (section 20)streaming=true in the Content-Type header (section 4.4)streaming=true in the Content-Type header (section 4.5)OData-Version header value of 4.0.
odata. prefix, where defined, on format parameters and control informationapplication/json media type in the Accept header (section 3)odata.metadata=full (section 3.1.2)odata.nextLink control information in partial results for entity collections (section 4.5.5)odata.nextLink control information in partial results for entity collections (section 4.6.5)$format system query option (section 3)odata.streaming=true parameter in the Accept header (section 4.4)odata.streaming=true parameter in the Accept header (section 4.5)odata.metadata (section 3.1.2)omit-values preference is specified in the Prefer request header and the omit-values preference is included in the Preference-Applied response headerOData-MaxVersion header value of 4.0