diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index b8ebaa59..041937d7 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -237,24 +237,25 @@
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 null
Client 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