\(\hbox{}\)

This stage:

https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd02/odata-json-format-v4.02-csd02.md (Authoritative)
https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd02/odata-json-format-v4.02-csd02.html
https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd02/odata-json-format-v4.02-csd02.pdf

Previous stage:

https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.md (Authoritative)
https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.html
https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd01/odata-json-format-v4.02-csd01.pdf

Latest stage:

https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.md (Authoritative)
https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html
https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.pdf

Technical Committee:

OASIS Open Data Protocol (OData) TC

Chairs:

Ralf Handl (ralf.handl@sap.com), SAP SE
Michael Pizzo (mikep@microsoft.com), Microsoft

Editors:

Ralf Handl (ralf.handl@sap.com), SAP SE
Michael Pizzo (mikep@microsoft.com), Microsoft
Heiko Theißen (heiko.theissen@sap.com), SAP SE

Related work:

This specification replaces or supersedes:

• OData JSON Format Version 4.01. Edited by Michael Pizzo, Ralf Handl, and Mark Biamonte. OASIS Standard. Latest stage: https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html.
• OData JSON Format Version 4.0. Edited by Ralf Handl, Michael Pizzo, and Mark Biamonte. OASIS Standard. Latest stage: http://docs.oasis-open.org/odata/odata-json-format/v4.0/odata-json-format-v4.0.html.

This specification is related to:

• OData Version 4.02. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes:
  • OData Version 4.02 Part 1: Protocol. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html
  • OData Version 4.02 Part 2: URL Conventions. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html
  • ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases. https://docs.oasis-open.org/odata/odata/v4.02/csd02/abnf/
• OData Vocabularies Version 4.0. Edited by Michael Pizzo, Ralf Handl, and Ram Jeyaraman. Latest stage: https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html
• OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-json/v4.02/odata-csdl-json-v4.02.html
• OData Common Schema Definition Language (CSDL) XML Representation Version 4.02. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html

Abstract:

The Open Data Protocol (OData) for representing and interacting with structured content is comprised of a set of specifications. The core specification for the protocol is in OData Version 4.02 Part 1: Protocol. This document extends the core specification by defining representations for OData requests and responses using a JSON format.

Status:

This document was last revised or approved by the OASIS Open Data Protocol (OData) TC on the above date. The level of approval is also listed above. Check the “Latest stage” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=e7cac2a9-2d18-4640-b94d-018dc7d3f0e2#technical.

TC members should send comments on this specification to the TC’s email list. Any individual may submit comments to the TC by sending email to Technical-Committee-Comments@oasis-open.org. Please use a Subject line like “Comment on OData JSON Format”.

This specification is provided under the RF on RAND Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/odata/ipr.php).

Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product’s prose narrative document(s), the content in the separate plain text file prevails.

Key words:

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here.

Citation format:

When referencing this specification the following citation format should be used:

[OData-JSON-Format-v4.02]

OData JSON Format Version 4.02. Edited by Ralf Handl, Michael Pizzo, and Heiko Theißen. 28 February 2024. OASIS Committee Specification Draft 02. https://docs.oasis-open.org/odata/odata-json-format/v4.02/csd02/odata-json-format-v4.02-csd02.html. Latest stage: https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html.

Notices

Copyright © OASIS Open 2024. All Rights Reserved.

Distributed under the terms of the OASIS IPR Policy.

The name “OASIS” is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs.

For complete copyright information please see the full Notices section in an Appendix below.

1985 Section 18| Allow common expressions in action payloads| 341

The amount of control information needed (or desired) in the payload depends on the client application and device. The 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.

Other Accept header parameters (e.g., streaming) are orthogonal to the 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 metadata=minimal. If computation is more critical than wire size or the client is incapable of computing control information, metadata=full directs the service to inline the control information that normally would be computed from metadata expressions in the payload. metadata=none is an option for clients that have out-of-band knowledge or don’t require control information.

In addition, the client may use the include-annotations preference in the Prefer header to request additional control information. Services supporting this MUST NOT omit control information required by the chosen metadata parameter, and services MUST NOT exclude the nextLink, deltaLink, and count if they are required by the response type.

If the client includes the OData-MaxVersion header in a request and does not specify the metadata format parameter in either the Accept header or $format query option, the service MUST return at least the minimal control information.

Note that in OData 4.0 the metadata 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.

The IEEE754Compatible=true format parameter indicates that the service MUST serialize Edm.Int64 and Edm.Decimal numbers (including the count, if requested) as strings. This is in conformance with RFC7493.

If not specified, or specified as IEEE754Compatible=false, all numbers MUST be serialized as JSON numbers.

This enables support for JavaScript numbers that are defined to be 64-bit binary format IEEE 754 values (see ECMAScript, section 4.3.1.9) resulting in integers losing precision past 15 digits, and decimals losing precision due to the conversion from base 10 to base 2.

OData JSON request and response payloads that format Edm.Int64 and Edm.Decimal values as strings MUST specify this format parameter in the media type sent in the Content-Type header.

Services producing responses without format parameter IEEE754Compatible=true which are unable to produce exact JSON numbers MAY serialize Edm.Int64 and Edm.Decimal numbers with a rounded/inexact value as a JSON number and annotate that value with an instance annotation with term Core.ValueException defined in OData-VocCore containing the exact value as a string. This situation can for example happen if the client only accepts application/json without any format parameters and the service is written in JavaScript.

For payloads with an OData-Version header equal to 4.0 the ExponentialDecimals=true format parameter indicates that the service MAY serialize Edm.Decimal numbers in exponential notation (e.g. 1e-6 instead of 0.000001).

The sender of a request MUST specify ExponentialDecimals=true in the Content-Type header if the request body contains Edm.Decimal values in exponential notation.

If not specified, or specified as ExponentialDecimals=false, all Edm.Decimal values MUST be serialized in long notation, using only an optional sign, digits, and an optional decimal point followed by digits.

Payloads with an OData-Version header equal to 4.01 or greater always allow exponential notation for numbers and the ExponentialDecimals format parameter is not needed or used.

Requests and responses with a JSON message body 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 include the metadata parameter to specify the amount of metadata included in the response.

Requests and responses MUST include the IEEE754Compatible parameter if Edm.Int64 and Edm.Decimal numbers are represented as strings.

Requests and responses MAY add the streaming parameter with a value of true or false, see section 4.5.

Each message body is 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 is 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 objects that represent changes to a previous result.

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, section 2.1.

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

• the context URL of the same JSON object, if one exists, otherwise
• the context URL of the enclosing object, if one exists, otherwise
• the context URL of the next enclosing object, if one exists, etc. until the document root, otherwise
• the request URL.

For context URLs, these rules apply starting with the second bullet point.

Within the type control information, relative URLs are relative to the base type URL, which is

• the type of the enclosing object, if one exists, otherwise
• the type of the next enclosing object, if one exists, etc. until the document root, otherwise
• the context URL of the document root, if one exists, otherwise
• the request URL.

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

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  …
  "@editLink": "Customers('ALFKI')",
  …
  "Orders@navigationLink": "Customers('ALFKI')/Orders",
  …
}

http://host/service/Customers('ALFKI')
http://host/service/Customers('ALFKI')/Orders

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.

Clients may specify the streaming=true parameter in the Content-Type header of requests to indicate that the request body follows the payload ordering constraints. In the absence of this parameter, the service must assume that the JSON properties in the request are unordered.

Processors MUST only assume streaming support if it is explicitly indicated in the Content-Type header via the streaming=true parameter.

Content-Type: application/json;metadata=minimal;streaming=true

Content-Type: application/json;metadata=minimal

JSON producers are encouraged to follow the payload ordering constraints whenever possible (and include the streaming=true media 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 context control information MUST be the first property in the JSON object.
• For 4.01 deleted entities, the removed control information MUST appear after context, if present, and before any other property or control information.
• The type control information, if present, MUST appear next in the JSON object.
• The id and etag control information MUST appear before any property, property annotation, or property control information.
• All annotations or control information for a structural or navigation property MUST appear as a group immediately before the property itself. The one exception is the nextLink of a collection which MAY appear after the collection it annotates.
• All other control information can appear anywhere in the payload as long as it does not violate any of the above rules.
• For 4.0 payloads, annotations and control information for navigation properties MUST appear after all structural properties. 4.01 clients MUST NOT assume this ordering.

Note that in OData 4.0 the 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": "http://host/service/$metadata#Customers/$entity",
  "@metadataEtag": "W/\"A1FF3E230954908F\"",
  …
}

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  "@type": "#Model.VipCustomer",
  "ID": 2,
  "DynamicValue@type": "Date",
  "DynamicValue": "2016-09-22",
  …
}

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  "@type": "http://host/alternate/$metadata#Model.VipCustomer",
  "ID": 2,
  …
}

{
  "@context": "http://host/service/$metadata#Employees/$entity",
  "@mediaReadLink": "Employees(1)/$value",
  "@mediaContentType": "image/jpeg",
  "ID": 1,
  …
}

{
  "@context": "http://host/service/$metadata#Employees/$entity",
  "ID": 1,
  "EmailAddresses@collectionAnnotations": [
    {
      "index": 0,
      "@OfficeCommunication.emailType": "Personal"
    },
    {
      "index": 2,
      "@OfficeCommunication.emailType": "Work"
    }
  ],
  "EmailAddresses": [
    "Julie@Swansworth.com",
    "JulieSwa@live.com",
    "Julie.Swansworth@work.com"
  ],
  …
}

Primitive values are represented following the rules of RFC8259.

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 -INF, INF, and NaN which are represented as strings, and except when the IEEE754Compatible format parameter demands representation of Edm.Int64 and Edm.Decimal 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 are represented as JSON strings whose content satisfies the rules binaryValue, dateValue, dateTimeOffsetValue, durationValue, guidValue, and timeOfDayValue respectively, in OData-ABNF.

Primitive values that cannot be represented, for example due to server conversion issues or IEEE754 limitations on the size of an Edm.Int64 or Edm.Decimal value, are annotated with the Core.ValueException term. In this case, the payload MAY include an approximation of the value and MAY specify a string representation of the exact value in the value property of the annotation.

Enumeration values are represented as JSON strings whose content satisfies the rule enumValue in OData-ABNF. The preferred representation is the enumerationMember. If no enumerationMember (or combination of named enumeration members) is available, the enumMemberValue representation may be used.

Geography and geometry values are represented as geometry types as defined in RFC7946.

Geography and geometry types have the same representation in a JSON payload. Whether the value represents a geography type or geometry type is inferred from its usage or specified using the type control information. RFC7946 does not define means for expressing instance-specific Coordinate Reference Systems.

{
  "NullValue": null,
  "TrueValue": true,
  "FalseValue": false,
  "BinaryValue": "T0RhdGE",
  "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] }
}

A complex value is represented as a single JSON object containing one name/value pair for each property that makes up the complex type. Each property value is formatted as appropriate for the type of the property.

It MAY have name/value pairs for instance annotations and control information.

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  …
  "Address": {
    "Street": "Obere Str. 57",
    "City": "Berlin",
    "Region": null,
    "PostalCode": "D-12209"
  }
}

A complex value with no selected properties, or no defined properties (such as an empty open complex type or complex type with no structural properties) is represented as an empty JSON object.

A collection of primitive values is represented as a JSON array; each element in the array is the representation of a primitive value. A JSON literal null represents a null value within the collection. An empty collection is represented as an empty array.

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  …
  "EmailAddresses": [
    "Julie@Swansworth.com",
    "Julie.Swansworth@work.com"
  ],
  "EmailAddresses@nextLink": "…"
}

A collection of complex values is represented as a JSON array; each element in the array is the representation of a complex value. A JSON literal null represents a null value within the collection. An empty collection is represented as an empty array.

{
  "PhoneNumbers": [
    {
      "Number": "425-555-1212",
      "Type": "Home"
    },
    {
      "@type": "#Model.CellPhoneNumber",
      "Number": "425-555-0178",
      "Type": "Cell",
      "Carrier": "Sprint"
    }
  ],
  "PhoneNumbers@nextLink": "…"
}

OData 4.01 adds the built-in abstract types Edm.Untyped and Collection(Edm.Untyped)that services can use to advertise in metadata that there is a property of a particular name present, but there is no type to describe the structure of the property’s values.

The value of an Edm.Untyped property MAY be a primitive value, a structural value, or a collection. If a collection, it may contain any combination of primitive values, structural values, and collections.

The value of a property of type Collection(Edm.Untyped)MUST be a collection, and it MAY contain any combination of primitive values, structural values, and collections. Enumeration values within an untyped collection SHOULD be represented as a string, using the enumerationMember.

Untyped values are the only place where a collection can directly contain a collection, or a collection can contain a mix of primitive values, structural values, and collections.

All children of an untyped property are assumed to be untyped unless they are annotated with the type control information, in which case they MUST conform to the type described by the control information.

A primitive value within an untyped collection is interpreted as an Edm.Boolean, Edm.String, or Edm.Decimal value, depending on the JavaScript type.

Collections directly contained within an untyped collection are themselves untyped.

The navigation link for a navigation property is represented as a navigationLink control information on the navigation property. Its value is an absolute or relative URL that allows retrieving the related entity or collection of entities.

The navigation link for a navigation property is only represented if the client requests metadata=full or the navigation link cannot be computed, e.g. if it is within a collection of complex type instances. If it is represented it MUST immediately precede the expanded navigation property if the latter is represented.

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  …
  "Orders@navigationLink": "Customers('ALFKI')/Orders",
  …
}

The association link for a navigation property is represented as an associationLink control information on the navigation property. Its value is an absolute or relative URL that can be used to retrieve the reference or collection of references to the related entity or entities.

The association link for a navigation property is only represented if the client requests metadata=full or the association link cannot be computed by appending /$ref to the navigation link. If it is represented, it MUST immediately precede the navigation link if the latter is represented, otherwise it MUST immediately precede the expanded navigation property if it is represented.

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  …
  "Orders@associationLink": "Customers('ALFKI')/Orders/$ref",
  …
}

An expanded navigation property is represented as a name/value pair where the name is the name of the navigation property, and the value is the representation of the related entity or collection of entities.

If at most one entity can be related, the value is the representation of the related entity, or null if no entity is currently related.

If a collection of entities can be related, it is represented as a JSON array. Each element is the representation of an entity or the representation of an entity reference. An empty collection of entities (one that contains no entities) is represented as an empty JSON array. The navigation property MAY include context, type, count, or nextLink control information. If a navigation property is expanded with the suffix /$count, only the count control information is represented.

{
  "@context": "http://host/service/$metadata#Customers/$entity",
  "Orders@count": 42,
  "Orders": [ … ],
  "Orders@nextLink": "…",
  …
}

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.

{
  "ID": 11643,
  "Amount": 100,
  …,
  "Customer": {
    "ID": "ANEWONE",
    …
  },
  "Items": [
    {
      "Product": { "@id": "Products(28)" },
      "Quantity": 1,
      …
    },
    {
      "Product": { "@id": "Products(39)" },
      "Quantity": 5,
      …
    }
  ]
}

When inserting or updating an entity, relationships of navigation properties MAY be inserted or updated via bind operations.

For requests containing an OData-Version header with a value of 4.0, a bind operation is encoded as a property control information odata.bind on the navigation property it belongs to and has a single value for single-valued navigation properties or an array of values for collection navigation properties. For nullable single-valued navigation properties the value null may be used to remove the relationship.

PATCH http://host/service/Products(42) HTTP/1.1
Content-Type: application/json

{
  "Category@odata.bind": "Categories(6)"
}

The values are the ids of the related entities. They MAY be absolute or relative URLs.

For requests containing an OData-Version header with a value of 4.01, a relationship is bound to an existing entity using the same representation as for an expanded entity reference.

PATCH http://host/service/Products(42) HTTP/1.1
Content-Type: application/json

{
  "Category": { "@id": "Categories(6)" }
}

PATCH http://host/service/Categories(6) HTTP/1.1
Content-Type: application/json

{
  "Name": "UpdatedCategory",
  "Products": [
    {
      "@id": "Products(42)"
    },
    {
      "@id": "Products(57)",
      "Name": "Widgets"
    },
    {
      "Name": "Wedges"
    }
  ]
}

OData 4.01 services MUST support both the OData 4.0 representation, for requests containing an OData-Version header with a value of 4.0, and the OData 4.01 representation, for requests containing an OData-Version header with a value of 4.01. Clients MUST NOT use @odata.bind in requests with an OData-Version header with a value of 4.01.

For insert operations collection navigation property bind operations and deep insert operations can be combined. For OData 4.0 requests, 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.

The ETag for a collection of related entities is represented as etag control information on the navigation property. Its value is an opaque string that can be used in a subsequent request to determine if the collection has changed.

Services MAY include this control information as appropriate.

{
  "@context": "http://host/service/$metadata#Orders/$entity",
  "@id": "Orders(1234)",
  "@etag": "W/\"MjAxMy0wNS0yN1QxMTo1OFo=\"",
  "ID": 1234,
  "Items@etag": "W/\"MjAxOS0wMy0xMlQxMDoyMlo=\""
  …
}

Note: the collection ETag for a navigation property may or may not be identical to the ETag of the containing entity, the example shows a different ETag for the Items collection.

Responses from a delta request are returned as a JSON object.

The JSON object for a delta response to a single entity is either an added, changed, or deleted entity.

The JSON object for a delta response to a collection of entities MUST contain an array-valued property named value containing all added, changed, or deleted entities, and MAY contain additional, unchanged entities. A flattened OData 4.0 delta response may also include added or deleted links, while these are generally represented as nested delta payloads in OData 4.01 and greater.

If the response from the delta link contains count control information, the returned number MUST include the count of all top-level added, changed, or deleted entities to be returned, as well as added or deleted links in an OData 4.0 delta response.

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.

The last page of a delta response SHOULD contain a delta link in place of the next link for retrieving subsequent changes once the current set of changes has been applied to the initial set.

{
  "@context": "http://host/service/$metadata#Customers/$delta",
  "@count":3,
  "value": [
    {
      "@id": "Customers('BOTTM')",
      "ContactName": "Susan Halvenstern"
    },
    {
      "@removed": {
        "reason": "deleted"
      },
      "@id": "Customers('ANTON')"
    },
    {
      "@id": "Customers('ALFKI')",
      "ContactName": "Blake Smithe"
    }
  ],
  "@deltaLink": "Customers?$deltatoken=8015"
}

{
  "@odata.context": "http://host/service/$metadata#Customers/$delta",
  "@odata.count": 3,
  "value": [
    {
      "@odata.id": "Customers('BOTTM')",
      "ContactName": "Susan Halvenstern",
    },
    {
      "@odata.context": "#Customers/$deletedEntity",
      "@odata.id": "Customers('ANTON')"
    },
    {
      "@odata.id": "Customers('ALFKI')",
      "ContactName": "Blake Smithe"
    }
  ],
  "@odata.deltaLink": "Customers?$deltatoken=8015"
}

Added or changed entities within a delta payload are represented as entities. All entities within a delta response payload MUST include the control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity.

When using a delta payload in an update request, an alternate key (see OData-URL, section 4.3.5) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

Any entity in an update request that has neither the id control information, nor the primary or alternate key values of an existing entity, are treated as an added entity.

Added entities MUST include all available 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 available selected properties that have changed, and MAY include additional properties.

Added or changed entities MAY include ETags.

Entities include control information for selected navigation links based on metadata.

Deleted entities in JSON are returned as deleted-entity objects. Delta responses MUST contain a deleted-entity object for each deleted entity, including deleted expanded entities that are not related through a containment navigation property. The service MAY additionally include expanded entities related through a containment navigation property in which case it MUST include those in any returned count of enumerated changes.

The representation of deleted-entity objects differs between OData 4.0 and OData 4.01.

In OData 4.0 payloads the deleted-entity object MUST include the following properties, regardless of the specified metadata value:

• Control information context — The context URL fragment MUST be #{entity-set}/$deletedEntity, where {entity-set} is the entity set of the deleted entity
• id — The id of the deleted entity (same as the id returned or computed when calling GET on resource), which may be absolute or relative

In OData 4.0 payloads the deleted-entity object MAY include the following optional property, regardless of the specified metadata value, and MAY include annotations:

• reason — 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).

{
  "@context": "#Customers/$deletedEntity",
  "reason": "deleted",
  "id": "Customers('ANTON')"
}

In OData 4.01 payloads the deleted-entity object MUST include the following properties, regardless of the specified metadata value. For ordered payloads, this control information MUST follow the payload ordering constraints.

• Control information removed, whose value is an object that MAY contain a property named reason. If present, the value of reason MUST be either deleted if the entity was deleted (destroyed), or changed if the entity was removed from membership in the result either due to change in value such that the entity no longer matches the defining query or because the entity was removed from the collection. The object MAY include annotations, and clients SHOULD NOT error due to the presence of additional properties that MAY be defined by future versions of this specification.

• Control information id or all of the entity’s primary key fields. The id control information MUST appear if any of the entity’s primary key fields are omitted from the response or the entity-id is not identical to the canonical URL of the entity. When using a delta payload in an update request, an alternate key (see OData-URL, section 4.3.5) MAY be used in place of the entity’s primary key. A delta response from an update request using alternate keys SHOULD include all fields of the alternate key used in the request, in which case it MAY omit the id control information and other primary key fields.

For full metadata the context control information MUST be included. It also MUST be included if the entity set of the deleted entity cannot be determined from the surrounding context.

The deleted-entity object MAY include additional properties of the entity, as well as annotations, and MAY include related entities, related deleted entities, or a delta or full representation of a related collection of entities, to represent related entities that have been modified or deleted.

{
  "@context": "#Customers/$deletedEntity",
  "@removed": {
    "reason": "deleted",
    "@myannoation.deletedBy": "Mario"
  },
  "@id": "Customers('ANTON')"
}

{
  "@removed": {},
  "ID": "ANTON"
}

Changes to related entities are represented differently in OData 4.0 and OData 4.01.

In OData 4.01, changes to relationships and related entities are generally represented as expanded navigation properties.

In OData 4.0, changes to relationships and related entities are represented as a flat array of added, deleted, or changed entities, along with added or deleted links.

{
  "@context": "http://host/service/$metadata#Customers/$delta",
  "@count":3,
  "value": [
    {
      "@id": "Customers('ALFKI')",
      "Orders@delta": [
        {
          "@removed": {
            "reason": "changed"
          },
          "@id": "Orders(10643)"
        },
        {
          "@id": "Orders(10645)",
          "ShippingAddress": {
            "Street": "23 Tsawassen Blvd.",
            "City": "Tsawassen",
            "Region": "BC",
            "PostalCode": "T2F 8M4"
          }
        }
      ]
    },
    {
      "@removed": {
        "reason": "deleted"
      },
      "@id": "Customers('ANTON')"
    },
    {
      "@id": "Customers('ALFKI')",
      "ContactName": "Blake Smithe"
    }
  ],
  "@deltaLink": "Customers?$expand=Orders&$deltatoken=8015"
}

{
  "@context": "http://host/service/$metadata#Customers/$entity/$delta",
  …
  "Orders@count": 42,
  "Orders": [ … ],
  "Orders@nextLink": "…",
  …
  "@deltaLink": "Customers('ALFKI')?$expand=Orders&$deltatoken=9711"
}

{
  "@odata.context": "http://host/service/$metadata#Customers/$delta",
  "@odata.count": 5,
  "value": [
    {
      "@odata.context": "#Customers/$deletedLink",
      "source": "Customers('ALFKI')",
      "relationship": "Orders",
      "target": "Orders(10643)"
    },
    {
      "@odata.context": "#Customers/$link",
      "source": "Customers('BOTTM')",
      "relationship": "Orders",
      "target": "Orders(10645)"
    },
    {
      "@odata.context": "#Orders/$entity",
      "@odata.id": "Orders(10645)",
      "ShippingAddress": {
        "Street": "23 Tsawassen Blvd.",
        "City": "Tsawassen",
        "Region": "BC",
        "PostalCode": "T2F 8M4"
      }
    },
    {
      "@odata.context": "#Customers/$deletedEntity",
      "@odata.id": "Customers('ANTON')"
    },
    {
      "@odata.id": "Customers('ALFKI')",
      "ContactName": "Blake Smithe"
    }
  ],
  "@odata.deltaLink": "Customers?$expand=Orders&$deltatoken=8016"
}

The body of a PATCH request to a URL identifying a collection of entities is a JSON object. It MUST contain the context control information with a string value of #$delta, and it MUST contain an array-valued property named value containing all added, changed, or deleted entities. OData 4.0 delta payloads MAY additionally include added or deleted links between entities.

PATCH /service/Customers HTTP/1.1
Host: host
Content-Type: application/json
Content-Length: ###
Prefer: return=minimal, continue-on-error

{
  "@context": "#$delta",
  "value": [
    {
      "@Org.OData.Core.V1.ContentID": "1",
      "CustomerID": "EASTC",
      "CompanyName": "Eastern Connection",
      "ContactName": "Ann Devon",
      "ContactTitle": "Sales Agent"
    },
    {
      "@Org.OData.Core.V1.ContentID": "2",
      "CustomerID": "AROUT",
      "ContactName": "Thomas Hardy",
    },
    {
      "@Org.OData.Core.V1.ContentID": "3",
      "@removed": {
        "reason": "deleted"
      },
      "CustomerID": "ANTON"
    },
    {
      "@Org.OData.Core.V1.ContentID": "4",
      "CustomerID": "ALFKI",
      "Orders@delta": [
        {
          "@Org.OData.Core.V1.ContentID": "4.1",
          "OrderID": 11011,
          "CustomerID": "ALFKI",
          "EmployeeID": 3,
          "OrderDate": "1998-04-09T00:00:00Z",
          "RequiredDate": "1998-05-07T00:00:00Z",
          "ShippedDate": "1998-04-13T00:00:00Z"
        },
        {
          "@Org.OData.Core.V1.ContentID": "4.2",
          "@id": "Orders(10692)"
        },
        {
          "@Org.OData.Core.V1.ContentID": "4.3",
          "@id": "Orders(10835)",
          "RequiredDate": "1998-01-23T00:00:00Z",
        },
        {
          "@Org.OData.Core.V1.ContentID": "4.4",
          "@removed": {
            "reason": "changed"
          },
          "OrderID": 10643
        }
      ]
    },
    {
      "@Org.OData.Core.V1.ContentID": "5",
      "CustomerID": "ANATR",
      "Orders@delta": [
        {
          "@Org.OData.Core.V1.ContentID": "5.1",
          "OrderID": 10643
        }
      ],
    },
    {
      "@Org.OData.Core.V1.ContentID": "6",
      "CustomerID": "DUMON",
      "Orders@delta": [
        {
          "@Org.OData.Core.V1.ContentID": "6.1",
          "@removed": {
            "reason": "changed"
          },
          "OrderID": 10311
        }
      ]
    }
  ]
}

HTTP/1.1 204 No Content
Preference-Applied: return=minimal, continue-on-error

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: ###
Preference-Applied: return=minimal, continue-on-error

{
  "@context": "#$delta",
  "value": [
    {
      "@Org.OData.Core.V1.ContentID": "1",
      "CustomerID": "EASTC",
      "@removed": {
        "reason": "changed"
      },
      "@Org.OData.Core.V1.DataModificationException": {
        "failedOperation": "insert",
        "responseCode": 400,
        "info": {
          "code": "incmplt",
          "message": "Required field(s) not provided",
          "target": "Address",
          "@OtherVocab.additionalTargets": [ "Industry", "VATRegistration" ],
          "severity": "error"
        }
      }
    },
    {
      "@Org.OData.Core.V1.ContentID": "2",
      "CustomerID": "AROUT",
      "@Org.OData.Core.V1.DataModificationException": {
        "failedOperation": "update",
        "responseCode": 400,
        "info": {
          "code": "r-o",
          "message": "Customer is archived and cannot be changed",
          "severity": "error"
        }
      }
    },
    {
      "@Org.OData.Core.V1.ContentID": "3",
      "CustomerID": "ANTON",
      "@Org.OData.Core.V1.DataModificationException": {
        "failedOperation": "delete",
        "responseCode": 400,
        "info": {
          "code": "ufo",
          "message": "Customer has unfinished orders and cannot be deleted",
          "severity": "error"
        }
      }
    },
    {
      "@Org.OData.Core.V1.ContentID": "4",
      "CustomerID": "ALFKI",
      "Orders@delta": [
        {
          "@Org.OData.Core.V1.ContentID": "4.3",
          "@id": "Orders(10835)",
          "@Org.OData.Core.V1.DataModificationException": {
            "failedOperation": "update",
            "responseCode": 400,
            "info": {
              "code": "b/s",
              "message": "RequiredDate cannot be changed because Order is already being shipped",
              "severity": "error"
            }
          }
        }
      ]
    },
    {
      "@Org.OData.Core.V1.ContentID": "5",
      "CustomerID": "ANATR",
      "Orders@delta": [
        {
          "@Org.OData.Core.V1.ContentID": "5.1",
          "@removed": {
            "reason": "changed"
          },
          "OrderID": 10643,
          "@Org.OData.Core.V1.DataModificationException": {
            "failedOperation": "link",
            "responseCode": 404,
            "info": null
          }
        }
      ]
    },
    {
      "@Org.OData.Core.V1.ContentID": "6",
      "CustomerID": "DUMON",
      "Orders@delta": [
        {
          "@Org.OData.Core.V1.ContentID": "6.1",
          "OrderID": 10311,
          "@Org.OData.Core.V1.DataModificationException": {
            "failedOperation": "unlink",
            "responseCode": 404
          }
        }
      ]
    }
  ]
}

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: ###

{
  "error": {
    "code": "incmplt",
    "message": "Required field(s) not provided",
    "target": "Customers('EASTC')/Address",
    "@OtherVocab.additionalTargets": [ "Customers('EASTC')/Industry", "Customers('EASTC')/VATRegistration" ]
  }
}

A JSON batch request body consists of a single JSON object that MUST contain the name/value pair requests and MAY contain annotations. It does not contain the context control information.

The value of requests is an array of request objects, each representing an individual request. Note: an individual request MUST NOT itself be a batch request.

A request object MUST contain the name/value pairs id, method and url, and it MAY contain the name/value pairs atomicityGroup, dependsOn, if, headers, and body.

The value of id is a string containing the request identifier of the individual request, see OData-Protocol, section 11.7.3. It MUST NOT be identical to the value of any other request identifier nor any atomicityGroup within the batch request.

Note: the id name/value pair corresponds to the Content-ID header in the multipart batch format specified in OData-Protocol, section 11.7.7.1.

The value of method is a string that MUST contain one of the literals delete, get, patch, post, or put. These literals are case-insensitive.

The value of url is a string containing the individual request URL. The URL MAY be an absolute path (starting with a forward slash /) which is appended to scheme, host, and port of the batch request URL, or a relative path (not starting with a forward slash /).

If the first segment of a relative path starts with a $ character and is not identical to the name of a top-level system resource ($batch, $crossjoin, $all, $entity, $root, $id, $metadata, or other system resources defined according to the OData-Version of the protocol specified in the request), then this first segment is replaced with the URL of the entity created by or returned from a preceding request whose id value is identical to the value of the first segment with the leading $ character removed. The id of this request MUST be specified in the dependsOn name/value pair.

Otherwise, the relative path is resolved relative to the batch request URL (i.e. relative to the service root).

The value of atomicityGroup is a string whose content MUST NOT be identical to any value of id within the batch request, and which MUST satisfy the rule request-id in OData-ABNF. All request objects with the same value for atomicityGroup MUST be adjacent in the requests array. These requests are processed as an atomic operation and MUST either all succeed, or all fail.

Note: the atomicity group is a generalization of the change set in the multipart batch format specified in OData-Protocol, section 11.7.7.1.

The value of dependsOn is an array of strings whose values MUST be values of either id or atomicityGroup of preceding request objects; forward references are not allowed. If a request depends on another request that is part of a different atomicity group, the atomicity group MUST be listed in dependsOn. In the absence of the optional if member a request that depends on other requests or atomicity groups is only executed if those requests were executed successfully, i.e. with a 2xx response code. If one of the requests it depends on has failed, the dependent request is not executed and a response with status code of 424 Failed Dependency is returned for it as part of the batch response.

The if member can specify an alternative condition for executing the dependent request. Its value MUST be URL expression (see OData-URL, section 5.1.1) that evaluates to a Boolean value. The URL expression syntax is extended and additionally allows

• $<content-id>/$succeeded to check if the referenced request has succeeded
• $<content-id> to reference the response body of the referenced request
• $<content-id>/<path> to reference a part of the response body

Services SHOULD advertise support of the if member by specifying the property RequestDependencyConditionsSupported in the Capabilities.BatchSupport term applied to the entity container, see OData-VocCap. If a service does not support request dependencies, the dependent request MUST fail with 424 Failed Dependency, and if the dependent request is part of an atomicity group, all requests in that group fail with 424 Failed Dependency with no changes applied.

The value of headers is an object whose name/value pairs represent request headers. The name of each pair MUST be the lower-case header name; the value is a string containing the header-encoded value of the header. The headers object MUST contain a name/value pair with the name content-type whose value is the media type.

The value of body can be null, which is equivalent to not specifying the body name/value pair.

For media type application/json or one of its subtypes, optionally with format parameters, the value of body is JSON.

For media types of top-level type text, for example text/plain, the value of body is a string containing the value of the request body.

For all other media types the value of body is a string containing the base64url-encoded value of the request body. In this case the body content can be compressed or chunked if this is correctly reflected in the Transfer-Encoding header.

A body MUST NOT be specified if the method is get or delete.

The request object and the headers object MUST NOT contain name/value pairs with duplicate names. This is in conformance with RFC7493.

POST /service/$batch HTTP/1.1
Host: host
OData-Version: 4.01
Content-Type: application/json
Content-Length: ###

{
  "requests": [
    {
      "id": "0",
      "method": "get",
      "url": "/service/Customers('ALFKI')"
    },
    {
      "id": "1",
      "atomicityGroup": "group1",
      "dependsOn": [ "0" ],
      "method": "patch",
      "url": "/service/Customers('ALFKI')",
      "headers": {
        "Prefer": "return=minimal"
      },
      "body": <JSON representation of changes to Customer ALFKI>
    },
    {
      "id": "2",
      "atomicityGroup": "group1",
      "method": "post",
      "url": "/service/Customers",
      "body": <JSON representation of a new Customer entity>
    },
    {
      "id": "3",
      "dependsOn": [ "group1" ],
      "method": "get",
      "url": "/service/Products"
    }
  ]
}

The entity returned by a preceding request can be referenced in the request URL of subsequent requests. If the Location header in the response contains a relative URL, clients MUST be able to resolve it relative to the request’s URL even if that contains such a reference.

POST /service/$batch HTTP/1.1
Host: host
OData-Version: 4.01
Content-Type: application/json
Content-Length: ###

{
  "requests": [
    {
      "id": "1",
      "method": "post",
      "url": "/service/Customers",
      "body": <JSON representation of a new Customer entity>
    },
    {
      "id": "2",
      "dependsOn": [ "1" ]
      "method": "post",
      "url": "$1/Orders",
      "body": <JSON representation of a new Order>
    }
  ]
}

All requests in an atomicity group represent a single change unit. A service MUST successfully process and apply all the requests in the atomicity group or else apply none of them. It is up to the service implementation to define rollback semantics to undo any requests within an atomicity group that may have been applied before another request in that same atomicity group failed.

The service MAY process the individual requests and atomicity groups within a batch request, or individual requests within an atomicity group, in any order that is compatible with the dependencies expressed with the dependsOn name/value pair. Individual requests and atomicity groups that do not specify the dependsOn name/value pair may be processed in parallel. Clients that are only interested in completely successful batch responses MAY specify the preference continue-on-error=false to indicate that the service need not spend cycles on further processing once an error occurs in one of the dependency chains. In this case the response MAY omit response objects for requests that have not been processed. If the preference continue-on-error is not specified, or specified with a value of true, all requests are processed according to their dependencies.

The service MUST include the id name/value pair in each response object with the value of the request identifier that the client specified in the corresponding request, so clients can correlate requests and responses.

A JSON batch response body consists of a single JSON object that MUST contain the name/value pair responses and MAY contain annotations. It does not contain the context control information.

The value of responses is an array of response objects, each representing an individual response.

A JSON batch response MAY be a partial result containing the nextLink control information. This allows services to chunk results into manageable pieces, or to return results for already processed requests and continue processing the remaining individual requests while waiting for the client to fire a GET request to the next link.

In a response to a batch request using the multipart format defined in OData-Protocol, section 11.7.7 the response objects MUST appear in the same order as required for multipart batch responses because the Content-ID header is not required outside of change sets. Response objects corresponding to requests that specify a Content-ID header MUST contain the id name/value pair, and the value of id MUST be the value of the Content-ID header of the corresponding request. This is necessarily the case for requests contained within a change set. Responses to requests within a change set MUST contain the atomicityGroup name/value pair with a value common within a change set and unique across change sets.

In a response to a batch request using the JSON batch request format specified in the preceding section the response objects MAY appear in any order, and each response object MUST contain the id name/value pair with the same value as in the corresponding request object. If the corresponding request object contains the atomicityGroup name/value pair, it MUST also be present in the response object with the same value.

If any response within an atomicity group returns a failure code, all requests within that atomicity group are considered failed, regardless of their individual returned status code. The service MAY return 424 Failed Dependency for statements within an atomicity group that fail or are not attempted due to other failures within the same atomicity group.

A response object MUST contain the name/value pair status whose value is a number representing the HTTP status code of the response to the individual request.

The response object MAY contain the name/value pair headers whose value is an object with name/value pairs representing response headers. The name of each pair MUST be the lower-case header name; the value is a string containing the header-encoded value of the header.

The response object MAY contain the name/value pair body which follows the same rules as within request objects.

If the media type is not exactly equal to application/json (i.e. it is a subtype or has format parameters), the headers object MUST contain a name/value pair with the name content-type whose value is the media type.

Relative URLs in a response object follow the rules for relative URLs based on the request URL of the corresponding request. Especially: URLs in responses MUST NOT contain $-prefixed request identifiers.

HTTP/1.1 200 OK
OData-Version: 4.01
Content-Length: ####
Content-Type: application/json

{
  "responses": [
    {
      "id": "0",
      "status": 200,
      "body": <JSON representation of the Customer entity with key ALFKI>
    },
    {
      "id": "1",
      "status": 204
    },
    {
      "id": "2",
      "status": 201,
      "headers": {
        "location": "http://host/service.svc/Customer('POIUY')"
      },
      "body": <JSON representation of the new Customer entity>
    },
    {
      "id": "3",
      "status": 404,
      "body": <Error message>
    }
  ]
}

A batch request that specifies the respond-async preference MAY be executed asynchronously. This means that the “outer” batch request is executed asynchronously; this preference does not automatically cascade down to the individual requests within the batch. After successful execution of the batch request the response to the batch request is returned in the body of a response to an interrogation request against the status monitor resource URL, see OData-Protocol, section 11.6.

A service MAY return interim results to an asynchronously executing batch. It does this by responding with 200 OK to a GET request to the monitor resource and including a nextLink control information in the JSON batch response, thus signaling that the response is only a partial result. A subsequent GET request to the next link MAY result in a 202 Accepted response with a location header pointing to a new status monitor resource.

HTTP/1.1 202 Accepted
Location: http://service-root/async-monitor-0
Retry-After: ###

HTTP/1.1 200 OK
AsyncResult: 200
OData-Version: 4.01
Content-Length: ###
Content-Type: application/json

{
  "responses": [
    {
      "id": "0",
      "status": 200,
      "body": <JSON representation of the Customer entity with key ALFKI>
    }
  ],
  "@nextLink": "…?$skiptoken=YmF0Y2gx"
}

HTTP/1.1 202 Accepted
Location: http://service-root/async-monitor-1
Retry-After: ###

HTTP/1.1 200 OK
AsyncResult: 200
OData-Version: 4.01
Content-Length: ###
Content-Type: application/json

{
  "responses": [
    {
      "id": "1",
      "status": 204
    },
    {
      "id": "2",
      "status": 201,
      "headers": {
        "location": "http://host/service.svc/Customer('POIUY')"
      },
      "body": <JSON representation of the new Customer entity>
    },
    {
      "id": "3",
      "status": 404,
      "body": <Error message>
    }
  ]
}

In addition to the above interaction pattern individual requests within a batch with no other requests depending on it and not part of an atomicity group MAY be executed asynchronously if they specify the respond-async preference and if the service responds with a JSON batch response. In this case the response array contains a response object for each asynchronously executed individual request with a status of 202, a location header pointing to an individual status monitor resource, and optionally a retry-after header.

HTTP/1.1 200 OK
OData-Version: 4.01
Content-Length: ###
Content-Type: application/json

{
  "responses": [
    {
      "id": "0",
      "status": 202,
      "headers": {
        "location": "http://service-root/async-monitor-0"
      }
    },
    {
      "id": "1",
      "status": 204
    }
  ]
}

When annotating a name/value pair for which the value is represented as a JSON object, each annotation is placed within the object and represented as a single name/value pair.

The name always starts with the “at” sign (@), followed by the annotation identifier.

The value MUST be an 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 represented as a single name/value pair and placed immediately prior to the annotated name/value pair, with the exception of the nextLink or collectionAnnotations control information, which can appear immediately before or after the annotated collection.

The name is the same as the name of the property or name/value pair being annotated, followed by the “at” sign (@), followed by the annotation identifier.

The value MUST be an appropriate value for the annotation.

Individual primitive elements within a JSON array can be annotated by applying the collectionAnnotations control information to the array containing the primitive member.

The control information must come with other annotations or control information immediately before or after the collection valued property. The name of the property representing the control information is the same as the name of the collection-valued property, followed by the “at” sign (@), followed by the collectionAnnotations identifier.

The error response MUST be a single JSON object. This object MUST have a single name/value pair named error. The value must be an OData error object.

The OData error 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 is a non-empty language-independent string. Its value is a service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response. It cannot be null.

The value for the message name/value pair is a non-empty, language-dependent, human-readable string describing the error. The Content-Language header MUST contain the language code from RFC5646 corresponding to the language in which the value for message is written. It cannot be null.

The value for the target name/value pair is a potentially empty string indicating the target of the error (for example, the name of the property in error). It can be null.

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.

Service implementations SHOULD carefully consider which information to include in production environments to guard against potential security concerns around information disclosure.

Error responses MAY contain annotations in any of its JSON objects.

{
  "error": {
    "code": "err123",
    "message": "Unsupported functionality",
    "target": "query",
    "details": [
      {
      "code": "forty-two",
      "target": "$search",
      "message": "$search query option not supported"
      }
    ],
    "innererror": {
      "trace": […],
      "context": {…}
    }
  }
}

In the case that a service encounters an error after sending a success status to the client, the service MUST leave the response malformed. This can be achieved by immediately stopping response serialization and thus omitting (among others) the end-object character of the top-level JSON object in the response.

Services MAY include the header OData-Error as a trailing header if supported by the transport protocol (e.g. with HTTP/1.1 and chunked transfer encoding, or with HTTP/2), see OData-Protocol, section 8.3.5.

The value of the OData-Error trailing header is an OData error object as defined in the preceding chapter, represented in a header-appropriate way:

• All optional whitespace (indentation and line breaks) is removed, especially (in hex notation) 09, 0A and 0D

• Control characters (00 to 1F and 7F) and Unicode characters beyond 00FF within JSON strings are encoded as \uXXXX or \uXXXX\uXXXX (see RFC8259, section 7)

OData-error: {"code":"err123","message":"Unsupported
functionality","target":"query","details":[{"code":"forty-two","target":"$search","message":"$search
query option not supported"}]}

Services may return error information within a success payload; for example, if the client has specified the continue-on-error preference.

The following documents are referenced in such a way that some or all of their content constitutes requirements of this document.

OData-ABNF

ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases.
See link in “Related work” section on cover page.

OData-CSDL

OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02.
See link in “Related work” section on cover page.

OData Common Schema Definition Language (CSDL) XML Representation Version 4.02.
See link in “Related work” section on cover page.

OData-Protocol

OData Version 4.02. Part 1: Protocol.
See link in “Related work” section on cover page.

OData-URL

OData Version 4.02. Part 2: URL Conventions.
See link in “Related work” section on cover page.

OData-VocCap

OData Vocabularies Version 4.0: Capabilities Vocabulary.
See link in “Related work” section on cover page.

OData-VocCore

OData Vocabularies Version 4.0: Core Vocabulary.
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, DOI 10.17487/RFC2119, March 1997. https://www.rfc-editor.org/info/rfc2119.

RFC3986

Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax”, STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. https://www.rfc-editor.org/info/rfc3986.

RFC3987

Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs)”, RFC 3987, DOI 10.17487/RFC3987, January 2005. https://www.rfc-editor.org/info/rfc3987.

RFC4648

Josefsson, S., “The Base16, Base32, and Base64 Data Encodings”, RFC 4648, DOI 10.17487/RFC4648, October 2006. https://www.rfc-editor.org/info/rfc4648.

RFC5646

Phillips, A., Ed., and M. Davis, Ed., “Tags for Identifying Languages”, BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009. https://www.rfc-editor.org/info/rfc5646.

RFC7493

Bray, T., Ed., “The I-JSON Message Format”, RFC 7493, DOI 10.17487/RFC7493, March 2015. https://www.rfc-editor.org/info/rfc7493.

RFC7946

Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, “The GeoJSON Format”, RFC 7946, DOI 10.17487/RFC7946, August 2016. https://www.rfc-editor.org/info/rfc7946.

RFC8174

Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017. https://www.rfc-editor.org/info/rfc8174.

RFC8259

Bray, T., Ed., “The JavaScript Object Notation (JSON) Data Interchange Format”, STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017. https://www.rfc-editor.org/info/rfc8259.

ECMAScript

ECMAScript 2023 Language Specification, 14th Edition, June 2023. Standard ECMA-262. https://www.ecma-international.org/publications-and-standards/standards/ecma-262/.

The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol, section C.2, are gratefully acknowledged.

OData TC Members: