Keywords defined by this specification use this monospaced font.

Some sections of this specification are illustrated with non-normative examples.

Non-normative examples use this paragraph style.

All examples in this document are non-normative and informative only.

All other text is normative unless otherwise labeled.

The format of a non-empty individual request or response body, alone or within a batch, MUST be specified in the Content-Type header of a request or response. The exception to this is if the body represents the media stream of a media entity or stream property, in which case the Content-Type header SHOULD be present.

The specified format MAY include format parameters. Clients MUST be prepared for the service to return custom format parameters not defined in OData and SHOULD NOT expect that such format parameters can be ignored. Custom format parameters MUST NOT start with odata and services MUST NOT require generic OData consumers to understand custom format parameters in order to correctly interpret the payload.

See OData-JSON, section 4.1 for format-specific details about format parameters within the Content-Type header.

As defined in RFC9110, the Content-Encoding header field is used as a modifier to the media-type (as indicated in the Content-Type header). When present, its value indicates what additional content codings have been applied to the entity-body. A service MAY specify a list of acceptable content codings using an annotation with term Capabilities.AcceptableEncodings, see OData-VocCap.

If the Content-Encoding header is specified on an individual request or response within a batch, then it specifies the encoding for that individual request or response. Individual requests or responses that don’t include the Content-Encoding header inherit the encoding of the overall batch request or response.

As defined in RFC9110, a request or response can include a Content-Language header to indicate the natural language of the intended audience for the enclosed message body. OData does not add any additional requirements over HTTP for including Content-Language. OData services can annotate model elements whose content depends on the content language with the term Core.IsLanguageDependent, see OData-VocCore.

If the Content-Language header is specified on an individual request or response within a batch, then it specifies the language for that individual request or response. Individual requests or responses that don’t include the Content-Language header inherit the language of the overall batch request or response.

As defined in RFC9110, a request or response SHOULD include a Content-Length header when the message’s length can be determined prior to being transferred. OData does not add any additional requirements over HTTP for writing Content-Length.

If the Content-Length header is specified on an individual request or response within a batch, then it specifies the length for that individual request or response.

OData clients SHOULD use the OData-Version header on a request to specify the version of the protocol used to generate the request payload.

If present on a request, the service MUST interpret the request payload according to the rules defined in the specified version of the protocol or fail the request with a 4xx response code.

If not specified in a request, the service MUST assume the request payload is generated using the minimum of the OData-MaxVersion, if specified, and the maximum version of the protocol that the service understands.

OData services MUST include the OData-Version header on a response to specify the version of the protocol used to generate the response payload. The client MUST interpret the response payload according to the rules defined in the specified version of the protocol. Request and response payloads are independent and may have different OData-Version headers according to the above rules.

For more details, see Versioning.

If the OData-Version header is specified on an individual request or response within a batch, then it specifies the OData version for that individual request or response. Individual requests or responses that don’t include the OData-Version header inherit the OData version of the overall batch request or response. This OData version does not typically vary within a batch.

As defined in RFC9110, the client MAY specify the set of accepted formats with the Accept Header.

Services MUST reject formats that specify unknown or unsupported format parameters.

If a media type specified in the Accept header includes a charset format parameter and the request also contains an Accept-Charset header, then the Accept-Charset header MUST be used.

If the media type specified in the Accept header does not include a charset format parameter, then the Content-Type header of the response MUST NOT contain a charset format parameter.

The service SHOULD NOT add any format parameters to the Content-Type header not specified in the Accept header.

If the Accept header is specified on an individual request within a batch, then it specifies the acceptable formats for that individual request. Requests within a batch that don’t include the Accept header inherit the acceptable formats of the overall batch request.

As defined in RFC9110, the client MAY specify the set of accepted character sets with the Accept-Charset header.

If the Accept-Charset header is specified on an individual request within a batch, then it specifies the acceptable character sets for that individual request. Requests within a batch that don’t include the Accept-Charset header inherit the acceptable character sets of the overall batch request.

As defined in RFC9110, the client MAY specify the set of accepted natural languages with the Accept-Language header.

If the Accept-Language header is specified on an individual request within a batch, then it specifies the acceptable languages for that individual request. Requests within a batch that don’t include the Accept-Language header inherit the acceptable languages of the overall batch request.

As defined in RFC9110, a client MAY include an If-Match header in a request to GET, POST, PUT, PATCH or DELETE. The value of the If-Match request header MUST be an ETag value previously retrieved for the resource, or *.

If an operation on an existing resource requires an ETag, (see term Core.OptimisticConcurrency in OData-VocCore and property OptimisticConcurrencyControl of type Capabilities.NavigationPropertyRestriction in OData-VocCap) and the client does not specify an If-Match request header in a Data Modification Request or in an Action Request invoking an action bound to the resource, the service responds with a 428 Precondition Required and MUST ensure that no observable change occurs as a result of the request.

If present, the request MUST only be processed if the specified ETag value matches the current ETag value of the target resource. Services sending ETag headers with weak ETags that only depend on the representation-independent entity state MUST use the weak comparison function because it is sufficient to prevent accidental overwrites. This is a deviation from RFC9110.

If the value does not match the current ETag value of the resource for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no observable change occurs as a result of the request. In the case of an upsert, if the addressed entity does not exist the provided ETag value is considered not to match.

The precondition If-Match: * is fulfilled if a current representation of the resource exists, a PUT or PATCH request with that header results in an upsert request being processed as an update and not an insert, independent of whether the resource requires an ETag.

The If-Match header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.

As defined in RFC9110, a client MAY include an If-None-Match header in a request to GET, POST, PUT, PATCH or DELETE. The value of the If-None-Match request header MUST be an ETag value previously retrieved for the resource, or *.

If present, the request MUST only be processed if the specified ETag value does not match the current ETag value of the resource, using the weak comparison function (see RFC9110). If the value matches the current ETag value of the resource, then for a GET request, the service SHOULD respond with 304 Not Modified, and for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no observable change occurs as a result of the request.

The precondition If-None-Match: * is fulfilled if there is no current representation of the resource, a PUT or PATCH request with that header request results in an upsert request being processed as an insert and not an update, independent of whether the resource requires an ETag.

The If-None-Match header MUST NOT be specified on a batch request, but MAY be specified on individual requests within the batch.

The Isolation header specifies the isolation of the current request from external changes. The only supported value for this header is snapshot.

If the service doesn’t support Isolation:snapshot and this header was specified on the request, the service MUST NOT process the request and MUST respond with 412 Precondition Failed.

Snapshot isolation guarantees that all data returned for a request, including multiple requests within a batch or results retrieved across multiple pages, will be consistent as of a single point in time. Only data modifications made within the request (for example, by a data modification request within the same batch) are visible. The effect is as if the request generates a “snapshot” of the committed data as it existed at the start of the request.

The Isolation header may be specified on a single or batch request. If it is specified on a batch then the value is applied to all statements within the batch.

Next links returned within a snapshot return results within the same snapshot as the initial request; the client is not required to repeat the header on each individual page request.

The Isolation header has no effect on links other than the next link. Navigation links, read links, and edit links return the current version of the data.

A service returns 410 Gone or 404 Not Found if a consumer tries to follow a next link referring to a snapshot that is no longer available.

The syntax of the Isolation header is defined in OData-ABNF.

A service MAY specify the support for Isolation:snapshot using an annotation with term Capabilities.IsolationSupported, see OData-VocCap.

Note: The Isolation header was named OData-Isolation in OData version 4.0. Services that support the Isolation header SHOULD also support OData-Isolation for OData 4.0 clients and clients SHOULD use OData-Isolation for compatibility with OData 4.0 services. If both Isolation and OData-Isolation headers are specified in the same request, the value of the Isolation header SHOULD be used.

Clients SHOULD specify an OData-MaxVersion request header.

If specified, the service MUST generate a response with the greatest supported OData-Version less than or equal to the specified OData-MaxVersion.

If OData-MaxVersion is not specified, then the service SHOULD return responses with the same OData version over time and interpret the request as having an OData-MaxVersion equal to the maximum OData version supported by the service at its initial publication.

If the OData-MaxVersion header is specified on an individual request within a batch, then it specifies the maximum OData version for that individual request. Individual requests that don’t include the OData-MaxVersion header inherit the maximum OData version of the overall batch request or response. The maximum OData version does not typically vary within a batch.

For more details, see Versioning.

The Prefer header, as defined in RFC7240, allows clients to request certain behavior from the service. The service MUST ignore preference values that are either not supported or not known by the service.

The value of the Prefer header is a comma-separated list of preferences. The following subsections describe preferences whose meaning in OData is defined by this specification.

In response to a request containing a Prefer header, the service MAY return the Preference-Applied and Vary headers.

Prefer: callback; url="http://myserver/notfication/token/12345"

Prefer: include-annotations="*"

Prefer: include-annotations="-*"

Prefer: include-annotations="display.*"

Prefer: include-annotations="display.subject"

Prefer: include-annotations="display.*#tablet"

Prefer: respond-async, wait=10

A 4.01 service MUST include the AsyncResult header in 200 OK responses from a status monitor resource in order to indicate the final HTTP Response Status Code of an asynchronously executed request. The header value is the three-digit HTTP response code, see OData-ABNF.

The AsyncResult header SHOULD NOT be applied to individual responses within a batch.

A response MAY include an ETag header, see RFC9110. Services MUST include this header if they require an ETag to be specified when modifying the resource.

Services MUST support specifying the value returned in the ETag header in an If-None-Match header of a subsequent Data Request for the resource. Clients MUST specify the value returned in the ETag header, or star (*), in an If-Match header of a subsequent Data Modification Request or Action Request in order to apply optimistic concurrency control in updating, deleting, or invoking an action bound to the resource.

As OData allows multiple formats for representing the same structured information, services SHOULD use weak ETags that only depend on the representation-independent entity state. A strong ETag MUST change whenever the representation of an entity changes, so it has to depend on the Content-Type, the Content-Encoding, and potentially other characteristics of the response.

An ETag header MAY also be returned on a metadata document request or service document request to allow the client subsequently to make a conditional request for the metadata or service document. Clients can also compare the value of the ETag header returned from a metadata document request to the metadata ETag returned in a response in order to verify the version of the metadata used to generate that response.

The ETag header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.

The Location header MUST be returned in the response from a Create Entity or Create Media Entity request to specify the edit URL, or for read-only entities the read URL, of the created entity, and in responses returning 202 Accepted to specify the URL that the client can use to request the status of an asynchronous request.

The Location header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.

A response to a create or upsert operation that returns 204 No Content MUST include an OData-EntityId response header. The value of the header is the entity-id of the entity that was acted on by the request. The syntax of the OData-EntityId header is defined in OData-ABNF.

The OData-EntityID header SHOULD NOT be included for the overall batch response, but MAY be included in individual responses within a batch.

A response with an in-stream error MAY include an OData-Error trailing header if the transport protocol supports trailing headers (e.g. HTTP/1.1 with chunked transfer encoding, or HTTP/2).

The value of this trailing header is a standard OData error response according to the OData response format, encoded suitably for transport in a header, see e.g. OData-JSON, section 21.2.

In a response to a request that specifies a Prefer header, a service MAY include a Preference-Applied header, as defined in RFC7240, specifying how individual preferences within the request were handled.

The value of the Preference-Applied header is a comma-separated list of preferences applied in the response. For more information on the individual preferences, see the Prefer header.

If the Preference-Applied header is specified on an individual response within a batch, then it specifies the preferences applied to that individual response. If the Preference-Applied header is specified on a batch response, then it specifies the preferences applied to the overall batch.

A service MAY include a Retry-After header, as defined in RFC9110), in 202 Accepted and in 3xx Redirect responses

The Retry-After header specifies the duration of time, in seconds, that the client is asked to wait before retrying the request or issuing a request to the resource returned as the value of the Location header.

If a response varies depending on the OData-Version of the response, the service MUST include a Vary header listing the OData-MaxVersion request header field to allow correct caching of the response.

If a response varies depending on the applied preferences (allow-entityreferences, include-annotations, omit-values, return), the service MUST include a Vary header listing the Prefer request header field to allow correct caching of the response.

Alternatively, the server MAY include a Vary header with the special value * as defined by RFC9110, Section 8.2.1. Note that this will make it impossible for a proxy to cache the response, see RFC7240.

A request that does not create a resource returns 200 OK if it is completed successfully and the value of the resource is not null. In this case, the response body MUST contain the value of the resource specified in the request URL.

A Create Entity, Create Media Entity, or Invoke Action request that successfully creates a resource returns 201 Created. In this case, the response body MUST contain the resource created.

202 Accepted indicates that the Data Service Request has been accepted and has not yet completed executing asynchronously. The asynchronous handling of requests is defined in the sections on Asynchronous Requests and Asynchronous Batch Requests.

A request returns 204 No Content if the requested resource has the null value, or if the service applies a return=minimal preference. In this case, the response body MUST be empty.

As defined in RFC9110, a Data Modification Request that responds with 204 No Content MAY include an ETag header with a value reflecting the result of the data modification if and only if the client can reasonably “know” the new representation of the resource without actually receiving it. For a PUT request this means that the response body of a corresponding 200 OK or 201 Created response would have been identical to the request body, i.e. no server-side modification of values sent in the request body, no server-calculated values etc. For a PATCH request this means that the response body of a corresponding 200 OK or 201 Created response would have consisted of all values sent in the request body, plus (for values not sent in the request body) server-side values corresponding to the ETag value sent in the If-Match header of the PATCH request, i.e. the previous values “known” to the client.

As per RFC9110, a 3xx Redirection indicates that further action needs to be taken by the client in order to fulfill the request. In this case, the response SHOULD include a Location header, as appropriate, with the URL from which the result can be obtained; it MAY include a Retry-After header.

As per RFC9110, a 304 Not Modified is returned when the client performs a GET request containing an If-None-Match header and the content has not changed. In this case the response SHOULD NOT include other headers in order to prevent inconsistencies between cached entity-bodies and updated headers.

The service MUST ensure that no observable change has occurred to the state of the service as a result of any request that returns a 304 Not Modified.

404 Not Found indicates that the resource specified by the request URL does not exist. The response body MAY provide additional information.

405 Method Not Allowed indicates that the resource specified by the request URL does not support the request method. In this case the response MUST include an Allow header containing a list of valid request methods for the requested resource as defined in RFC9110.

406 Not Acceptable indicates that the resource specified by the request URL does not have a current representation that would be acceptable for the client according to the request headers Accept, Accept-Charset, and Accept-Language, and that the service is unwilling to supply a default representation.

410 Gone indicates that the requested resource is no longer available. This can happen if a client has waited too long to follow a delta link or a status-monitor-resource link, or a next link on a collection that was requested with snapshot isolation.

As defined in RFC9110, 412 Precondition Failed indicates that the client has performed a conditional request and the resource fails the condition. The service MUST ensure that no observable change occurs as a result of the request.

424 Failed Dependency indicates that a request was not performed due to a failed dependency; for example, a request within a batch that depended upon a request that failed.

If the client requests functionality not implemented by the OData Service, the service MAY respond with 501 Not Implemented and include a response body describing the functionality not implemented.

Service documents enable simple hypermedia-driven clients to enumerate and explore the resources offered by the data service.

OData services MUST support returning a service document from the root URL of the service (the service root).

The format of the service document is dependent upon the format selected.

An OData metadata document is a representation of the data model that describes the data and operations exposed by an OData service.

OData-CSDLJSON describes a JSON representation for OData metadata documents and provides a JSON schema to validate their contents. The media type of the JSON representation of an OData metadata document is application/json.

OData-CSDLXML describes an XML representation for OData metadata documents and provides an XML schema to validate their contents. The media type of the XML representation of an OData metadata document is application/xml.

OData services can expose a metadata document that describes the data model exposed by the service. The metadata document URL MUST be the root URL of the service with $metadata appended. To retrieve this document the client issues a GET request to the metadata document URL.

If a request for metadata does not specify a format preference (via Accept header or $format) then the XML representation MUST be returned.

OData defines a number of system query options that allow refining the request. System query options are prefixed with the dollar ($) character, which is optional in OData 4.01. 4.01 services MUST support case-insensitive system query option names specified with or without the $ prefix. Clients that want to work with 4.0 services MUST use lower case names and specify the $ prefix.

The result of the request MUST be as if the system query options were evaluated in the following order.

• $schemaversion MUST be evaluated first, because it may influence any further processing.

Prior to applying any server-driven paging:

• $apply — defined in OData-Aggregation
• $compute
• $search
• $filter
• $count
• $orderby
• $skip
• $top

After applying any server-driven paging:

• $expand
• $select
• $format

To retrieve an individual entity, the client makes a GET request to a URL that identifies the entity, e.g. its read URL.

The read URL can be obtained from a response payload containing that instance, for example as a readLink or editLink in an OData-JSON, section 4.6.9 payload. In addition, services MAY support conventions for constructing a read URL using the entity’s key value(s), as described in OData-URL, section 4.3.1.

The set of structural or navigation properties to return may be specified through $select or $expand system query options.

Clients MUST be prepared to receive additional properties in an entity or complex type instance that are not advertised in metadata, even for types not marked as open.

Properties that are not available are not returned. If their unavailability is due to permissions, the Core.Permissions annotation, defined in OData-VocCore MUST be returned for the property with a value of None. If the omit-values preference is applied, Core.Permissions or another specific annotation that explains the reason MUST be returned for every unavailable property.

If no entity exists with the specified request URL, the service responds with 404 Not Found.

A media entity is an entity that represents an out-of-band stream, such as a photograph.

Use a media entity if the out-of-band stream is the main topic of interest and the media entity is just structured additional information attached to the stream. Use a normal entity with one or more stream properties if the structured data of the entity is the main topic of interest and the stream data is just additional information attached to the structured data.

To address the media stream represented by a media entity, clients append /$value to the resource path of the media entity URL. The media type of the response is the media type of the stream, subject to content type negotiation based on the Accept header of the request. The response body is the octet-stream that represents the raw value of the media stream with that media type. Alternatively, services MAY redirect from this canonical URL to the source URL of the media stream.

Appending /$value to an entity that is not a media entity returns 400 Bad Request.

Attempting to retrieve the media stream from a single-valued navigation property referencing a media entity whose value is null returns 404 Not Found.

To retrieve an individual property, the client issues a GET request to the property URL. The property URL is the entity read URL with / and the property name appended.

For complex typed properties, the path can be further extended with the name of an individual property of the complex type.

See OData-URL, section 4.6 for details.

If the property is single-valued and has the null value, the service responds with 204 No Content.

If the property is not available, for example due to permissions, the service responds with 404 Not Found.

GET http://host/service/Products(1)/Name

GET http://host/service/Products(1)/Name/$value

The $select and $expand system query options enable the client to specify the set of structural properties and navigation properties to include in a response. The service MAY include additional properties not specified in $select and $expand, including properties not defined in the metadata document.

GET http://host/service/Products?$select=Rating,ReleaseDate

GET http://host/service/Products?$select=*

GET http://host/service/Products?$expand=Category($select=Name)

GET http://host/service/Categories?$select=CategoryName,Products

GET http://host/service/Products?$select=DemoService.*

GET http://host/service.svc/Customers?$expand=Orders

GET http://host/service.svc/Customers?$expand=Orders/$ref

GET http://host/service.svc/Customers?$expand=Photo

GET http://host/service.svc/Customers?$expand=Orders($filter=Amount gt 100)

GET http://host/service.svc/Orders?$expand=Items($expand=Product),Customer

GET http://host/service.svc/Customers?$expand=SampleModel.VipCustomer/InHouseStaff

GET http://host/service/Employees?$expand=Model.Manager/DirectReports($levels=4)

GET http://host/service/Customers
   ?$filter=Orders/any(o:o/TotalPrice gt 100)
   &$expand=Orders($compute=Price mult Qty as TotalPrice
                  ;$select=Name,Price,Qty,TotalPrice)

OData services support querying collections of entities, complex type instances, and primitive values.

The target collection is specified through a URL, and query operations such as filter, sort, paging, and projection are specified as system query options optionally prefixed with a dollar ($) character. 4.01 Services MUST support case-insensitive system query option names specified with or without the $ prefix. Clients that want to work with 4.0 services MUST use lower case names and specify the $ prefix.

The same system query option MUST NOT be specified more than once for any resource.

An OData service MAY support some or all of the system query options defined. If a data service does not support a system query option, it MUST fail any request that contains the unsupported option and SHOULD return 501 Not Implemented.

GET http://host/service/Products?$filter=Price lt 10.00

GET http://host/service/Categories?$filter=Products/$count lt 10

Address/City eq 'Redmond'

Address/City ne 'London'

Price gt 20

Price ge 10

Price lt 20

Price le 100

Style has Sales.Color'Yellow'

Address/City in ('Redmond', 'London')

Price le 200 and Price gt 3.5

Price le 3.5 or Price gt 200

not endswith(Description,'milk')

Price add 5 gt 10

Price sub 5 gt 10

Price mul 2 gt 2000

Price div 2 gt 4

Price divby 2 gt 3.5

Price mod 2 eq 0

(Price sub 5) gt 10

concat(concat(City,', '), Country) eq 'Berlin, Germany'

contains(CompanyName,'freds')

endswith(CompanyName,'Futterkiste')

indexof(CompanyName,'lfreds') eq 1

length(CompanyName) eq 19

startswith(CompanyName,’Alfr’)

substring(CompanyName,1) eq 'lfreds Futterkiste'

hassubset([4,1,3],[3,1])

hassubsequence([4,1,3,1],[1,1])

matchespattern(CompanyName,'%5EA.*e$')

tolower(CompanyName) eq 'alfreds futterkiste'

toupper(CompanyName) eq 'ALFREDS FUTTERKISTE'

trim(CompanyName) eq 'Alfreds Futterkiste'

day(StartTime) eq 8

date(StartTime) ne date(EndTime)

second(StartTime) eq 0

hour(StartTime) eq 1

EndTime eq maxdatetime()

StartTime eq mindatetime()

minute(StartTime) eq 0

month(BirthDate) eq 12

StartTime ge now()

second(StartTime) eq 0

time(StartTime) le StartOfDay

totaloffsetminutes(StartTime) eq 60

totalseconds(duration'PT1M') eq 60

year(BirthDate) eq 0

ceiling(Freight) eq 33

floor(Freight) eq 32

round(Freight) eq 32

cast(ShipCountry,Edm.String)

isof(NorthwindModel.Order)

isof(ShipCountry,Edm.String)

geo.distance(CurrentPosition,TargetPosition)

geo.intersects(Position,TargetArea)

geo.length(DirectRoute)

case(X gt 0:1,X lt 0:-1,true:0)

GET http://host/service.svc/Employees?$filter=Region eq @p1&@p1='WA'

GET http://host/service.svc/Employees?$expand=Manager(@m=$this;$expand=DirectReports($filter=@m/FirstName eq FirstName))

GET http://host/service/Products?$orderby=ReleaseDate asc, Rating desc

GET http://host/service/Categories?$expand=Products($orderby=ReleaseDate asc, Rating desc)

GET http://host/service/Categories?$orderby=Products/$count

GET http://host/service/Products?$top=5

GET http://host/service/Products?$skip=5

GET http://host/service/Products?$top=5&$skip=2

GET http://host/service/Products?$count=true

GET http://host/service/Categories?$expand=Products($count=true)

GET http://host/service/Products?$search=bike

GET http://host/service/Products?$search="mountain bike"

GET http://host/service/Products?$search=NOT clothing

GET http://host/service/Products?$search=mountain AND bike

GET http://host/service/Products?$search=mountain OR bike

GET http://host/service/Products?$search=(mountain OR bike) AND NOT clothing

GET http://host/service/MainSupplier/Addresses/0

To request related entities according to a particular relationship, the client issues a GET request to the source entity’s request URL, followed by a forward slash and the name of the navigation property representing the relationship.

If the navigation property does not exist on the entity indicated by the request URL, the service returns 404 Not Found.

If the relationship terminates on a collection, the response MUST be the format-specific representation of the collection of related entities. If no entities are related, the response is the format-specific representation of an empty collection.

If the relationship terminates on a single entity, the response MUST be the format-specific representation of the related single entity. If no entity is related, the service returns 204 No Content.

GET http://host/service/Products(1)/Supplier

To request entity references in place of the actual entities, the client issues a GET request with /$ref appended to the resource path.

If the resource path does not identify an entity or a collection of entities, the service returns 404 Not Found.

If the resource path identifies a collection, the response MUST be the format-specific representation of a collection of entity references pointing to the related entities. If no entities are related, the response is the format-specific representation of an empty collection. The response MAY contain an ETag header for the collection whose value changes if the collection of references changes, i.e. a reference is added or removed.

If the resource path identifies a single existing entity, the response MUST be the format-specific representation of an entity reference. The response MAY contain an ETag header which represents the identity of the referenced entity. If the resource path terminates in a single-valued navigation path, the ETag value changes if the relationship is changed and points to a different OData entity. If the resource path is the canonical path for a single entity, the returned ETag can never change.

If the resource path terminates on a single entity and no such entity exists, the service returns either 204 No Content or 404 Not Found.

GET http://host/service/Products(0)/Orders/$ref

To resolve an entity-id, e.g. obtained in an entity reference, into a representation of the identified entity, the client issues a GET request to the $entity resource located at the URL $entity relative to the service root. The entity-id MUST be specified using the system query option $id.

GET http://host/service/$entity?$id=http://host/service/Products(0)

A type segment following the $entity resource casts the resource to the specified type. If the identified entity is not of the specified type, or a type derived from the specified type, the service returns 404 Not Found.

After applying a type-cast segment to cast to a specific type, the system query options $select and $expand can be specified in GET requests to the $entity resource.

GET http://host/service/$entity/Model.Customer
      ?$id=http://host/service/Customers('ALFKI')
      &$select=CompanyName,ContactName
      &$expand=Orders

To request only the number of items of a collection of entities or items of a collection-valued property, the client issues a GET request with /$count appended to the resource path of the collection.

On success, the response body MUST contain the exact count of items matching the request after applying any $filter or $search system query options, formatted as a simple primitive integer value with media type text/plain. Clients SHOULD NOT combine the system query options $top, $skip, $orderby, $expand, and $format with the path suffix /$count. The result of such a request is undefined.

GET http://host/service/Products/$count

With 4.01 services the /$count segment MAY be used in combination with the /$filter path segment to count the items in the filtered collection.

GET http://host/service/Products/$filter(@foo)/$count?@foo=Price lt 10.00

For backwards compatibility, the /$count suffix MAY be used in combination with the $filter system query option.

GET http://host/service/Products/$count?$filter=Price lt 10.00

The $filter system query option MUST NOT be used in conjunction with a both a /$count path segment and a /$filter path segment.

The /$count suffix can also be used in path expressions within system query options, e.g. $filter.

GET http://host/service/Customers?$filter=Interests/$count gt 5

GET http://host/service/Categories?$filter=Products/$filter(Price gt 5.0)/$count gt 1

The $format system query option specifies the media type of the response.

The $format query option, if present in a request, MUST take precedence over the value(s) specified in the Accept request header.

The value of the $format system query option is a valid internet media type, optionally including parameters.

In addition, format-specific abbreviations may be used, e.g. json for application/json, see OData-JSON, but format parameters MUST NOT be appended to the format abbreviations.

GET http://host/service/Orders?$format=application/json;metadata=full

is equivalent to a request with an Accept header using the same media type; it requests the set of Order entities represented using the JSON media type including full metadata, as defined in OData-JSON, section 3.1.2.

GET http://host/service/Orders?$format=json

is equivalent to a request with the Accept header set to application/json; it requests the set of Order entities represented using the JSON media type with minimal metadata, as defined in OData-JSON, section 3.1.1.

In metadata document requests, the values application/xml and application/json, along with their subtypes and parameterized variants, as well as the format-specific abbreviations xml and json, are reserved for this specification.

The $schemaversion system query option MAY be included in any request. For a metadata document request the value of the $schemaversion system query option addresses a specific schema version. For all other request types the value specifies the version of the schema against which the request is made. The syntax of the $schemaversion system query option is defined in OData-ABNF.

The value of the $schemaversion system query option MUST be a version of the schema as returned in the Core.SchemaVersion annotation, defined in OData-VocCore, of a previous request to the metadata document, or * in order to specify the current version of the metadata.

If specified, the service MUST process the request according to the specified version of the metadata.

Clients can retrieve the current version of the metadata by making a metadata document request with a $schemaversion system query option value of *, and SHOULD include the value from the returned Core.SchemaVersion annotation in the $schemaversion system query option of subsequent requests.

If the $schemaversion system query option is not specified in a request for the metadata document, the service MUST return a version of the metadata with no breaking changes over time, and the processing of all other requests that omit the $schemaversion system query option MUST be compatible with that “unversioned” schema. For more information on breaking changes, see Model Versioning.

If the $schemaversion system query option is specified on an individual request within a batch, then it specifies the version of the schema to apply to that individual request. Individual requests within a batch that don’t include the $schemaversion system query option inherit the schema version of the overall batch request.

If the $schemaversion system query option is specified, but the version of the schema doesn’t exist, the request is answered with a response code 404 Not Found. The response body SHOULD provide additional information.

Delta links are opaque, service-generated links that the client uses to retrieve subsequent changes to a result.

Delta links are based on a defining query that describes the set of results for which changes are being tracked; for example, the request that generated the results containing the delta link. The delta link encodes the collection of entities for which changes are being tracked, along with a starting point from which to track changes. OData services may use the reserved system query option $deltatoken when building delta links. Its content is opaque, service-specific, and must only follow the rules for URL query parts.

If the defining query contains a $schemaversion system query option, the response MUST be represented according to that schema version.

If the defining query contains a $filter or $search, the response MUST include only changes to entities matching the specified criteria. Added entities MUST be returned for entities that were added or changed and now match the specified criteria, and deleted entities MUST be returned for entities that are changed to no longer match the criteria of $filter or $search.

The delta link MUST NOT encode any client top or skip value, and SHOULD NOT encode a request for an inline count.

If the defining query includes expanded relationships, the delta link MUST return changes, additions, or deletions to the expanded entities, as well as added or deleted links to expanded entities or nested collections representing current membership. If the defining query includes expanded references, then the delta link MUST return changes to the membership in the set of expanded references.

Navigation properties specified in the $select list of a defining query are not used to define the scope or contents of the items being tracked. Clients can specify /$ref in $expand in order to specify interest in the set of related entities without interest in changes to the content of those related entities.

If an expanded entity becomes orphaned because all paths to the entity as specified in the defining query have been broken (i.e. due to relationship changes and/or changes or deletions to parent entities) then the service MUST return the appropriate notifications for the client to determine that the entity has been orphaned (i.e. the changed relationships and removed parent entities). The client should not assume that it will receive additional notifications for such an orphaned entity.

Entities are considered changed if any of the structural properties have changed. Changes to related entities and to streams are not considered a change to the entity containing the stream or navigation property.

If the defining query contains a projection, the generated delta link SHOULD logically include the same projection, such that the delta query only includes fields specified in the projection. Services MAY use the projection to limit the entities returned to those that have changed within the selected fields, but the client MUST be prepared to receive entities returned whether or not the field that changed was specified in the projection.

The client requests changes by invoking the GET method on the delta link. The client MUST NOT attempt to append system query options to the delta link. The Accept header MAY be used to specify the desired response format.

Clients SHOULD specify the same Accept-Language header when querying the delta link as was specified in the defining query. Services MAY return 406 Not Acceptable if a different Accept-Language is specified. If a service does support an Accept-Language header it MAY return changes only visible in that language, or MAY include records that have changes not visible in the requested language.

The /$count segment can be appended to the path of a delta link in order to get just the number of changes available. The count includes all added, changed, or deleted entities, as well as added or deleted links.

The results of a request against the delta link may span one or more pages and MUST be ordered by the service across all pages in such a way as to guarantee consistency when applied in order to the response which contained the delta link.

Services SHOULD return only changed entities, but MAY return additional entities matching the defining query for which the client may not see a change.

In order to continue tracking changes beyond the current set, the client specifies track-changes on the initial request to the delta link but is not required to repeat it for subsequent pages. The new delta link appears at the end of the last page of changes in place of the next link and MUST return all changes subsequent to the last change of the previous delta link.

If no changes have occurred, the response is an empty collection that contains a delta link for subsequent changes if requested. This delta link MAY be identical to the delta link resulting in the empty collection of changes.

If the delta link is no longer valid, the service responds with 410 Gone, and SHOULD include the URL for refetching the entire set in the Location header of the response.

A delta payload represents changes to a known state. A delta payload includes added entities, changed entities, and deleted entities, as well as a representation of added and removed relationships.

Services that support the use of ETags for optimistic concurrency control SHOULD return ETag values for added or changed entities within the delta payload.

Delta payloads can be requested from the service using a delta link or provided as updates to the service.

Data Modification Requests share the following semantics.

To create an entity in a collection, the client sends a POST request to that collection’s URL. The POST body MUST contain a single valid representation of an entity of the declared target entity type, or one of its derived types.

The entity representation MAY include references to existing entities as well as content for new related entities, but MUST NOT contain content for existing related entities. The result of the operation is the entity with relationships to all included references to existing entities as well as all related entities created inline. If the key properties for an entity include key properties of a directly related entity, those related entities MUST be included either as references to existing entities or as content for new related entities.

An entity may also be created as the result of an Upsert operation.

If the target URL for the collection is a navigation link, the new entity is automatically linked to the entity containing the navigation link.

If the target URL terminates in a type cast segment, then the segment MUST specify the type of, or a type derived from, the type of the collection, and the entity MUST be created as that specified type.

To create an open entity (an instance of an open type), additional property values beyond those specified in the metadata MAY be sent in the request body. The service MUST treat these as dynamic properties and add them to the created instance.

If the entity being created is not an open entity, additional property values beyond those specified in the metadata SHOULD NOT be sent in the request body. The service MUST fail if unable to persist all property values specified in the request.

Non-insertable properties SHOULD be omitted from the request body. If they are provided, services MUST either ignore the values in the request body or fail the request if the provided values do not match the service-determined values.

Non-insertable properties include (and are not limited to)

• dependent properties that are tied to non-key properties of the principal entity through a referential constraint OData-CSDL, section 8.5 (informally: “denormalized” properties),
• properties annotated with the term Core.Computed, see OData-VocCore,
• properties listed as NonInsertableProperties of term Capabilities.InsertRestrictions, see OData-VocCap,
• properties annotated with term Core.Permissions, see OData-VocCore, where the annotation value does not have the Write flag.

Services MUST return an error if the request body contains a value for a property that in principle can be specified on insert but the request cannot currently be executed respecting the specified value, for example, due to permissions or state of the object. Properties with a default value, nullable properties, and collection-valued properties omitted from the request are set to the default value, null, or an empty collection, respectively.

Services MAY add dynamic properties to the created entity as long as their names do not conflict with the names of declared properties and client-specified dynamic properties.

Upon successful creation of the entity, the service MUST respond with either 201 Created and a representation of the created entity, or 204 No Content if the request included a return=minimal preference and did not include the system query options $select and $expand, or if a representation of the created entity could not be constructed. In either case, if the service is able to construct the edit URL or read URL of the created entity, the response MUST contain that URL in a Location header.

{
  "@type": "#Northwind.Manager",
  "ID": 1,
  "FirstName": "Pat",
  "LastName": "Griswold",
  "Manager@odata.bind": "http://host/service/Employees(0)",
  "DirectReports@odata.bind": [
    "http://host/service/Employees(5)",
    "http://host/service/Employees(6)"
  ]
}

{
  "@type": "#Northwind.Manager",
  "ID": 1,
  "FirstName": "Pat",
  "LastName": "Griswold",
  "Manager": { "@id": "Employees(0)" },
  "DirectReports": [{ "@id": "Employees(5)" }, { "@id": "Employees(6)" }]
}

To update an individual entity, the client makes a PATCH or PUT request to a URL that identifies the entity. Services MAY restrict updates only to requests addressing the edit URL of the entity.

The body of the request MUST be a valid representation of the declared target entity type, or one of its derived types.

Services SHOULD support PATCH as the preferred means of updating an entity. PATCH provides more resiliency between clients and services by directly modifying only those values specified by the client.

The semantics of PATCH, as defined in RFC5789, is to merge the content in the request payload with the entity’s current state, applying the update only to those components specified in the request body. Collection properties and primitive properties provided in the payload corresponding to updatable properties MUST replace the value of the corresponding property in the entity or complex type. Complex properties are updated by applying PATCH semantics recursively, see also section 11.4.9.3. Omitted properties of the containing entity or complex property, including dynamic properties, MUST NOT be directly altered unless as a side effect of changes resulting from the provided properties.

If the type of the entity in a PATCH request differs from the type of the entity being updated (i.e., a different derived type of the declared target type), then properties shared through inheritance, as well as dynamic properties, are retained (unless overwritten by new values in the payload). Other properties of the original type are discarded.

Services MAY additionally support PUT but should be aware of the potential for data-loss in round-tripping properties that the client may not know about in advance, such as open or added properties, or properties not specified in metadata. Services that support PUT MUST replace all values of structural properties with those specified in the request body. Omitted non-key, updatable structural properties not defined as dependent properties within a referential constraint MUST be set to their default values. Omitting a non-nullable property with no service-generated or default value from a PUT request results in a 400 Bad Request error. Omitted dynamic properties MUST be removed, set to null, or set to a service-generated value.

For requests with an OData-Version header with a value of 4.01 or greater, the media stream of a media entity can be updated by specifying the format-specific representation of the media stream as a virtual property $value.

Updating a dependent property that is tied to a key property of the principal entity through a referential constraint updates the relationship to point to the entity with the specified key value. If there is no such entity, the update fails.

Updating a principal property that is tied to a dependent entity through a referential constraint on the dependent entity updates the dependent property.

Non-updatable properties SHOULD be omitted from the request body. If they are provided, services MUST either ignore the values in the request body or fail the request if the provided values do not match the service-determined values.

Non-updatable properties include (and are not limited to)

• key properties,
• dependent properties that are tied to non-key properties of the principal entity through a referential constraint OData-CSDL, section 8.5 (informally: “denormalized” properties),
• properties annotated with the terms Core.Computed or Core.Immutable, see OData-VocCore,
• properties listed as NonUpdatableProperties of term Capabilities.UpdateRestrictions, see OData-VocCap,
• properties annotated with term Core.Permissions, see OData-VocCore, where the annotation value does not have the Write flag.

Services MUST return an error if the request body contains a value for a property that in principle can be specified on update but the request cannot currently be executed respecting the specified value, for example, due to permissions or state of the object.

Clients SHOULD use PATCH and specify only those properties intended to be changed.

The entity-id cannot be changed when updating an entity. However, format-specific rules might in some cases require providing the entity-id in the payload when requesting the update.

For requests with an OData-Version header with a value of 4.01 or greater, if the entity representation in the request body includes an ETag value, the update MUST NOT be performed and SHOULD return 412 Precondition Failed if the supplied ETag value is not * and does not match the current ETag value for the entity. ETag values in request bodies MUST be ignored for requests containing an OData-Version header with a value of 4.0.

If an update specifies both a binding to a single-valued navigation property and a dependent property that is tied to a key property of the principal entity according to the same navigation property, then the dependent property is ignored, and the relationship is updated according to the value specified in the binding.

If the entity being updated is open, then additional values for properties beyond those specified in the metadata or returned in a previous request MAY be sent in the request body. The service MUST treat these as dynamic properties.

If the entity being updated is not open, then additional values for properties beyond those specified in the metadata or returned in a previous request SHOULD NOT be sent in the request body. The service MUST fail if it is unable to persist all updatable property values specified in the request.

Upon successful completion of the update, the service responds with either 200 OK and a representation of the updated entity, or 204 No Content. The client may request that the response SHOULD include a body by specifying a return=representation preference, or by specifying the system query options $select or $expand. If the service uses ETags for optimistic concurrency control, the entities in the response MUST include ETags. If a representation of the updated entity could not be constructed, the service MAY ignore the system query options and respond with 204 No Content.

{
  "@type": "#Northwind.Manager",
  "FirstName": "Patricia",
  "DirectReports": [
    {
      "@id": "Employees(5)"
    },
    {
      "@id": "Employees(6)",
      "LastName": "Smith"
    },
    {
      "FirstName": "Suzanne",
      "LastName": "Brown"
    }
  ]
}

{
  "@type": "#Northwind.Manager",
  "FirstName": "Patricia",
  "DirectReports@delta": [
    {
      "@removed": {
        "reason": "deleted"
      },
      "@id": "Employees(3)"
    },
    {
      "@removed": {
        "reason": "changed"
      },
      "@id": "Employees(4)"
    },
    {
      "@id": "Employees(5)"
    },
    {
      "@id": "Employees(6)",
      "LastName": "Smith"
    },
    {
      "FirstName": "Suzanne",
      "LastName": "Brown"
    }
  ]
}

PUT http://host/service/Categories(6)?$expand=Products
Content-Type: application/json

{
  "Name": "UpdatedCategory",
  "Products": [
    {
      "@context": "$metadata#$ref",
      "@id": "Products(57)"
    }
  ]
}

{
  "@context": "$metadata#Categories/$entity",
  "CategoryID": 6,
  "Name": "UpdatedCategory",
  "Products": [
    {
      "ProductID": 57,
      "Name": "Widgets"
    }
  ]
}

PUT http://host/service/Categories(6)?$expand=Products
Content-Type: application/json

{
  "Name": "UpdatedCategory",
  "Products": [
    {
      "@id": "Products(57)",
      "ProductID": 57
    }
  ]
}

{
  "@context": "$metadata#Categories/$entity",
  "CategoryID": 6,
  "Name": "UpdatedCategory",
  "Products": [
    {
      "ProductID": 57,
      "Name": null
    }
  ]
}

An upsert occurs when the client sends an update request to a valid URL that identifies a single entity that does not yet exist. In this case the service MUST handle the request as a create entity request or fail the request altogether.

Upserts to single-valued navigation properties are possible for

• containment navigation properties,
• non-containment navigation properties with a navigation property binding, or
• payloads including a context URL specifying the entity set or contained collection of entities in which the new entity is to be created.

Upserts are not supported against entities whose keys’ values are generated by the service. Services MUST fail an update request to a URL that would identify such an entity and the entity does not yet exist.

Similarly, services MUST fail an update request to the URL of a media entity that does not yet exist. However, a PUT request to the media edit URL of a media entity does have Upsert semantics, in that the media entity is created with the specified media stream if it does not already exist, otherwise the media stream of the existing media entity is updated.

Singleton entities can be upserted if they are nullable. Services supporting this SHOULD advertise it by annotating the singleton with the term Capabilities.UpdateRestrictions (nested property Upsertable with value true) defined in OData-VocCap.

A key property whose value is provided in the request URL SHOULD be omitted from the request body. If key properties are provided in the request URL and the request body with different values, services MUST either fail the request or ignore the value in the request body.

To ensure that an update request is not treated as an insert, the client MAY specify an If-Match header in the update request. The service MUST NOT treat an update request containing an If-Match header as an insert.

A PUT or PATCH request MUST NOT be treated as an update if an If-None-Match header is specified with a value of *.

To delete an individual entity, the client makes a DELETE request to a URL that identifies the entity. Services MAY restrict deletes only to requests addressing the edit URL of the entity.

The request body SHOULD be empty. Top-level singleton entities can be deleted if they are nullable. Services supporting this MAY advertise it by annotating the singleton with the term Capabilities.DeleteRestrictions (nested property Deletable with value true) defined in OData-VocCap.

On successful completion of the delete, the response MUST either be 204 No Content and contain an empty body, or 200 OK and contain a representation of a deleted entity according to the specified format.

Services MUST implicitly remove relations to and from an entity when deleting it; clients need not delete the relations explicitly.

Services MAY implicitly delete or modify related entities if required by integrity constraints. If integrity constraints are declared in $metadata using a ReferentialConstraint element, services MUST modify affected related entities according to the declared integrity constraints, e.g. by deleting dependent entities, or setting dependent properties to null or their default value.

One such integrity constraint results from using a navigation property in a key definition of an entity type. If the related “key” entity is deleted, the dependent entity is also deleted.

Relationships between entities are represented by navigation properties as described in Data Model. URL conventions for navigation properties are described in OData-URL, section 4.3.3.

A media entity MUST have a source URL that can be used to read the media stream, and MAY have a media edit URL that can be used to write to the media stream.

Because a media entity has both a media stream and standard entity properties special handling is required.

An entity may have one or more stream properties. Stream properties are properties of type Edm.Stream.

The values for stream properties do not usually appear in the entity payload unless explicitly requested with $expand. Instead, the values are generally read or written through URLs.

GET http://host/service/Products(1)?$select=Thumbnail

{
  "@context": "http://host/service/$metadata#Products/$entity",
  …
  "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
  "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
  …
}

GET http://server/Thumbnail546.jpg

Services SHOULD support direct property access to a stream property’s canonical URL. The response MAY be a redirect to the media read link of the stream property if the media read link is different from the canonical URL.

GET http://host/service/Products(1)/Thumbnail

Note: for scenarios in which the media value can only be inlined, the property should instead be modeled with type Edm.Binary.

DELETE http://server/uploads/Thumbnail546.jpg

Values and properties can be explicitly addressed with URLs. The edit URL of a property is the edit URL of the entity appended with the path segment(s) specifying the individual property. The edit URL allows properties to be individually modified. See OData-URL, section 4.6 for details on addressing individual properties.

Collections annotated with the Core.Ordered term (see OData-VocCore) have a stable order. Members of an ordered collection of primitive and complex types can be individually updated or deleted by invoking an update operation against the URL of the collection appended by a segment containing the zero-based ordinal of the item within the collection. A negative ordinal number indexes from the end of the collection, with -1 representing the last item in the collection.

Entities can be updated using their edit URL and SHOULD NOT be addressed using an index.

Collections of entity, complex, or primitive types annotated with the Core.PositionalInsert term (see OData-VocCore) support inserting items at a specific location via POST requests to the collection URL using the $index system query option. The value of the $index system query option is the zero-based ordinal position where the item is to be inserted. The ordinal positions of items within the collection greater than or equal to the inserted position are increased by one. A negative ordinal number indexes from the end of the collection, with -1 representing an insert as the last item in the collection.

POST /service/Customers('ALFKI')/EmailAddresses?$index=1
Content-Type: application/json

{
  "value": "alfred@futterkiste.de"
}

Collections of entities can be updated by submitting a PATCH request to the resource path of the collection. The body of the request MUST be a delta payload, and the resource path of the collection MUST NOT contain type cast or filter segments, and MUST NOT contain any system query options that affect the shape of the result.

Added/changed entities are applied as upserts, and deleted entities as deletions. Non-key properties of deleted entities are ignored. The top-level collection may include added and deleted links, and related entities represented inline are updated according to the rules for treating related entities when updating an entity.

Clients MAY associate an id with individual nested entities in the request by using the Core.ContentID term defined in OData-VocCore. Services that respond with 200 OK SHOULD annotate the entities in the response using the same Core.ContentID value as specified in the request.

Services SHOULD advertise support for updating a collection using a delta payload through the DeltaUpdateSupported property of the Capabilities.UpdateRestrictions term, and SHOULD advertise support for returning the Core.ContentID through the ContentIDSupported property of the Capabilities.DeepUpdateSupport term, both defined in OData-VocCap.

For each entity being updated or removed, clients MAY specify an ETag value obtained from a previous request. If an ETag is provided that does not match the ETag value of the entity being updated or removed, or if an ETag is provided when adding or updating an entity that does not currently exist, then services that support ETags MUST NOT apply the change and instead report a 412 Precondition Failed error. The special value * can be used to match any existing entity but fail if the entity does not already exist.

The response, if requested, is a delta payload, in the same structure and order as the request payload, representing the applied changes.

Collections of entities can be replaced by submitting a PUT request to the resource path of the collection. The body of the request MUST be the representation of the complete collection of replacement entities. In this case all entities provided in the request are applied as upserts, and any entities not provided in the request are deleted.

For each entity being updated, clients MAY specify an ETag value obtained from a previous request. If an ETag is provided that does not match the ETag value of the entity being updated, or if an ETag is provided for an entity that does not currently exist, then services that support ETags MUST NOT apply the change and instead report a 412 Precondition Failed. The special ETag value * can be used to match any existing entity but fail if the entity does not already exist.

Members of a collection can be updated by submitting a PATCH request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the request body describes an update to each member of the collection, not an update to the collection itself.

The resource path of the collection MAY contain type-cast or filter segments to subset the collection, see OData-URL, section 4.11 and OData-URL, section 4.12.

For primitive-typed collections the body of the request MUST be a primitive value. Each member of the potentially filtered collection is updated to the specified primitive value.

For collections of structured type, the body of the request MUST be a full or partial representation of an instance of the collection’s structured type. Each member of the potentially filtered collection is updated using PATCH semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in Update a Collection of Entities applies.

PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
Content-Type: application/json

{
  "Color": "taupe"
}

The response, if requested, is a collection payload containing the updated representation of each member identified by the request. If the update payload includes nested collections or nested delta collections, then they MUST be included in the response, as described in Update a Collection of Entities.

Clients should note that requesting a response may be expensive for services that could otherwise efficiently apply updates to a (possibly filtered) collection.

If the continue-on-error preference has been specified, the service MAY continue processing updates after a failure. In this case, the service MUST return a response containing at least the members of the collection that failed to update, which MUST be annotated with the term Core.DataModificationException with a failedOperation value of update.

If the continue-on-error preference has not been specified, and the service is unable to update all of the members identified by the request, then it MUST return an error response and MUST NOT apply any updates.

Members of a collection can be deleted by submitting a DELETE request to the URL constructed by appending /$each to the resource path of the collection. The additional path segment expresses that the collection itself is not deleted.

The request resource path of the collection MAY contain type-cast or filter segments to subset the collection.

DELETE /service/Products/$filter(Age gt 3)/$each

If the path identifies a collection of entities and if the service returns a representation, then the response is a delta response containing a representation of a deleted entity for each deleted member.

If the collection is a collection of entities, then the client MAY specify the continue-on-error preference, in which case the service MAY continue processing deletes after a failure. In this case, the service MUST return a response containing at least an entity or entity reference for each entity identified by the request that failed to delete, which MUST be annotated with the term Core.DataModificationException with a failedOperation value of delete.

Clients should note that requesting a response may be expensive for services that could otherwise efficiently apply deletes to a (possibly filtered) collection.

If the continue-on-error preference has not been specified, and the service is unable to delete all of the entities identified by the request, then it MUST return an error response and MUST NOT apply any changes.

Actions and Functions MAY be bound to any type or collection, similar to defining a method in a class in object-oriented programming. The first parameter of a bound operation is the binding parameter.

The namespace- or alias-qualified name of a bound operation may be appended to any URL that identifies a resource whose type matches, or is derived from, the type of the binding parameter. The resource identified by that URL is used as the binding parameter value. Only aliases defined in the metadata document of the service can be used in URLs.

<Function Name="MostRecentOrder" IsBound="true">
  <Parameter Name="customer" Type="SampleModel.Customer" />
  <ReturnType Type="SampleModel.Order" />
</Function>

GET http://host/service/Customers(6)/SampleModel.MostRecentOrder()

<Function Name="Comparison" IsBound="true">
  <Parameter Name="in" Type="Collection(Edm.EntityType)" />
  <ReturnType Type="Diff.Overview" />
</Function>

GET http://host/service/Products/$filter(Color eq 'Red')/Diff.Comparison()

A bound operation with a single-valued binding parameter can be applied to each member of a collection by appending the path segment /$each to the resource path of the collection, followed by a forward slash and the namespace- or alias-qualified name of the bound operation. In this case the type of the collection members MUST match or be derived from the type of the binding parameter.

The resource path of the collection MAY contain type-cast or filter segments to subset the collection.

The response is a collection with members that are instances of the result type of the bound operation. If the bound operation returns a collection, the response is a collection of collections.

GET http://host/service/Customers/$each/SampleModel.MostRecentOrder()

The client MAY specify the continue-on-error preference, in which case the service MAY continue processing actions after a failure. In this case, the service MUST, regardless of the return preference, return a response containing at least the members identified by the request for which the action failed. Such members MUST be annotated with the term Core.DataModificationException with a failedOperation value of invoke.

If the continue-on-error preference has not been specified, and the service is unable to invoke the action against all of the entities identified by the request, then it MUST return an error response and MUST NOT apply the action to any of the members of the collection.

Services MAY return actions and/or functions bound to a particular entity or entity collection as part of the representation of the entity or entity collection within the payload. The representation of an action or function depends on the format.

{
  "@context": …,
  "CustomerID": "ALFKI",
  "CompanyName": "Alfreds Futterkiste",
  "#SampleEntities.MostRecentOrder": {
    "title": "Most Recent Order",
    "target": "Customers('ALFKI')/SampleEntities.MostRecentOrder()"
  },
  …
}

An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in OData-URL, section 4.5.

Services can advertise that a function or action is not available for a particular instance by setting its value to null.

{
  "@context": …,
  "CustomerID": "ALFKI",
  "CompanyName": "Alfreds Futterkiste",
  "#SampleEntities.MostRecentOrder": null,
  …
}

Functions are operations exposed by an OData service that MUST return data and MUST have no observable side effects.

POST http://host/service/MyShoppingCart()/Items

…

GET http://host/service/EmployeesByManager(ManagerID=3)

GET http://host/service/Customers?
      $filter=Sales.SalesRegion(City=$it/City) eq 'Western'

GET http://host/service/EmployeesByManager(ManagerID=@p1)?@p1=3

GET http://host/service/EmployeesByManager?ManagerID=3

Actions are operations exposed by an OData service that MAY have side effects when invoked. Actions MAY return data but MUST NOT be further composed with additional path segments.

POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
If-Match: W/"MjAxOS0wMy0yMVQxMzowNVo="
Content-Type: application/json

{
  "items": [
    { "product": 4001, "quantity": 2 },
    { "product": 7062, "quantity": 1 },
  ],
  "discountCode": "BLACKFRIDAY"
}

A batch request using the multipart batch format MUST contain a Content-Type header specifying a content type of multipart/mixed and a boundary parameter as defined in RFC2046.

POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.0
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b

<Multipart Batch request body>

A batch request using the JSON batch format MUST contain a Content-Type header specifying a content type of application/json.

POST /service/$batch HTTP/1.1
Host: odata.org
OData-Version: 4.01
Content-Type: application/json

<JSON Batch request body>

Batch requests SHOULD contain the applicable OData-Version header.

Batch requests SHOULD contain an Accept header specifying the desired batch response format, either multipart/mixed or application/json. If no Accept header is provided, services SHOULD respond with the content type of the request.

Requests within a batch may have dependencies on other requests according to the particular batch format.

In the JSON format, requests may explicitly declare a dependency on other requests that must be successfully processed before the current request. In addition, requests may be specified as part of an atomicity group whose members MUST either all succeed, or all fail. If a request fails, then any dependent requests within the JSON format return 424 Failed Dependency.

In the Multipart format, data modification requests or action invocation requests may be grouped as part of an atomic change set. Operations outside the change set are executed sequentially, while operations within the change set may be executed in any order.

Each individual request within a batch request MAY have a request identifier assigned. The request identifier is case-sensitive, MUST be unique within the batch request, and MUST satisfy the rule request-id in OData-ABNF.

The representation of the request identifier is format-specific, as are the rules for which individual requests require an identifier.

Entities created by an insert request or an action can be referenced in the request URL of subsequent requests by using the request identifier prefixed with a $ character as the first segment of the request URL. Services MUST treat this segment like the URL in the Location header of the response to the request identified by the segment. If the Location header in the response to the subsequent request contains a relative URL, clients MUST be able to resolve it relative to the request’s URL even if that contains such a reference. See example 106.

If the $-prefixed request identifier is 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 the reference to the top-level system resource is used. This collision can be avoided by e.g. using only numeric request identifiers.

Services MAY also support referencing within request bodies, in which case they SHOULD advertise this support by specifying the ReferencesInRequestBodiesSupported property in the Capabilities.BatchSupport term applied to the entity container, see OData-VocCap.

Services MAY support the use of an ETag returned from a previous operation in an If-Match or If-None-Match header of a subsequent statement. Services SHOULD advertise this support by specifying the EtagReferencesSupported property in the Capabilities.BatchSupport annotation term applied to the entity container, see OData-VocCap.

The ETag for a previous operation can be referenced by using the request identifier prefixed with a $ character as the unquoted value of the If-Match or If-None-Match header.

Services MAY support using values from a response body in the query part of the URL or in the request body of subsequent requests. A value reference can consist of a $ character followed by the identifier of the preceding request, then the referenced value is the value represented by the response body of that preceding request. Alternatively, a value reference can consist of a $ character followed by the value of an instance annotation with term Core.ContentID (see OData-VocCore) that occurs in the payload of the preceding request as described in section 11.4.2.2 and section 11.4.3.1, then the referenced value is the corresponding value in the response, which the service SHOULD annotate with the same Core.ContentID value.

In both cases, if the referenced value is a collection, the value reference MAY be followed by a collectionNavigationExpr, as defined in OData-ABNF, that is evaluated relative to the referenced value. Otherwise the value reference MAY be followed by a forward slash and a memberExpr that is evaluated relative to the referenced value.

If the $-prefixed identifier is identical to the name of a predefined literal for query expressions ($it, $root, or other literals defined according to the OData-Version of the protocol specified in the request), then the predefined literal is used. This collision can be avoided by e.g. using only numeric identifiers.

The multipart batch format is represented as a Multipart Media Type message RFC2046, a standard format allowing the representation of multiple parts, each of which may have a different content type.

GET https://host:1234/path/service/People(1) HTTP/1.1

PATCH /path/service/People(1) HTTP/1.1
Host: myserver.mydomain.org:1234
Content-Type: application/json

{ "Name": "Peter" }

DELETE People(1) HTTP/1.1

POST /service/$batch HTTP/1.1
Host: host
OData-Version: 4.0
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Length: ###

--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: application/http

GET /service/Customers('ALFKI')
Host: host


--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
Content-Type: application/http
Content-ID: 1

POST /service/Customers HTTP/1.1
Host: host
Content-Type: application/json
Content-Length: ###

<JSON representation of a new Customer>
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
Content-Type: application/http
Content-ID: 2

PATCH /service/Customers('ALFKI') HTTP/1.1
Host: host
Content-Type: application/json
If-Match: xxxxx
Prefer: return=minimal
Content-Length: ###

<JSON representation of changes to Customer ALFKI>
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd--
--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: application/http

GET /service/Products HTTP/1.1
Host: host


--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

POST /service/$batch HTTP/1.1
Host: host
OData-Version: 4.0
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Length: ###

--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
Content-Type: application/http
Content-ID: 1

POST /service/Customers HTTP/1.1
Host: host
Content-Type: application/json
Content-Length: ###

<JSON representation of a new Customer entity>
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
Content-Type: application/http
Content-ID: 2

POST $1/Orders HTTP/1.1
Host: host
Content-Type: application/json
Content-Length: ###

<JSON representation of a new Order>
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd--
--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77a

--batch_36522ad7-fc75-4b56-8c71-56071383e77a
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbe

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbe
Content-Type: application/http

HTTP/1.1 201 OK
Location: Customers('ALFKI')
…
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbe
Content-Type: application/http

HTTP/1.1 201 OK
Location: Orders(1)
…
--changeset_77162fcd-b8da-41ac-a9f8-9357efbbe--
--batch_36522ad7-fc75-4b56-8c71-56071383e77a--

POST /service/$batch HTTP/1.1
Host: host
OData-Version: 4.0
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Length: ###

--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: application/http
Content-ID: 1

GET /service/Employees(0) HTTP/1.1
Host: host
Accept: application/json


--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: application/http
Content-ID: 2

PATCH /service/Employees(0) HTTP/1.1
Host: host
Content-Type: application/json
Content-Length: ###
If-Match: $1

{
   "Salary": 75000
}
--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

POST /service/$batch HTTP/1.1
Host: host
OData-Version: 4.01
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Length: ###

--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: application/http
Content-ID: 1

GET /service/Employees/0?$select=Building HTTP/1.1
Host: host
Accept: application/json


--batch_36522ad7-fc75-4b56-8c71-56071383e77b
Content-Type: application/http
Content-ID: 2

GET /service/Employees?$filter=Building eq $1/Building HTTP/1.1
Host: host
Accept: application/json


--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
Content-Type: multipart/mixed; boundary=b_243234_25424_ef_892u748

--b_243234_25424_ef_892u748
Content-Type: application/http

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

<JSON representation of the Customer entity with key ALFKI>
--b_243234_25424_ef_892u748
Content-Type: multipart/mixed; boundary=cs_12u7hdkin252452345eknd_383673037

--cs_12u7hdkin252452345eknd_383673037
Content-Type: application/http
Content-ID: 1

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://host/service.svc/Customer('POIUY')
Content-Length: ###

<JSON representation of the new Customer entity>
--cs_12u7hdkin252452345eknd_383673037
Content-Type: application/http
Content-ID: 2

HTTP/1.1 204 No Content


--cs_12u7hdkin252452345eknd_383673037--
--b_243234_25424_ef_892u748
Content-Type: application/http

HTTP/1.1 404 Not Found
Content-Type: application/xml
Content-Length: ###

<Error message>
--b_243234_25424_ef_892u748---

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

HTTP/1.1 200 OK
Content-Type: application/http

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: ####
Content-Type: multipart/mixed; boundary=b_243234_25424_ef_892u748

--b_243234_25424_ef_892u748
Content-Type: application/http

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

<JSON representation of the Customer entity with key ALFKI>
--b_243234_25424_ef_892u748
Content-Type: application/http

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


--b_243234_25424_ef_892u748--

HTTP/1.1 200 OK
AsyncResult: 200
OData-Version: 4.0
Content-Length: ####
Content-Type: multipart/mixed; boundary=b_243234_25424_ef_892u748

--b_243234_25424_ef_892u748
Content-Type: multipart/mixed; boundary=cs_12u7hdkin252452345eknd_383673037

--cs_12u7hdkin252452345eknd_383673037
Content-Type: application/http
Content-ID: 1

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://host/service.svc/Customer('POIUY')
Content-Length: ###

<JSON representation of a new Customer entity>
--cs_12u7hdkin252452345eknd_383673037
Content-Type: application/http
Content-ID: 2

HTTP/1.1 204 No Content


--cs_12u7hdkin252452345eknd_383673037--
--b_243234_25424_ef_892u748
Content-Type: application/http

HTTP/1.1 404 Not Found
Content-Type: application/xml
Content-Length: ###

<Error message>
--b_243234_25424_ef_892u748--

In order to conform to the OData 4.0 Minimal conformance level, a service:

1. MUST publish a service document at the service root (section 11.1.1)
2. MUST return data according to the OData-JSON format
3. MUST use server-driven paging when returning partial results (section 11.2.6.7) and not use any other mechanism
4. MUST return the appropriate OData-Version header (section 8.1.5)
5. MUST conform to the semantics the following headers, or fail the request
   1. Accept (section 8.2.1)
   2. OData-MaxVersion (section 8.2.7)
6. MUST follow OData guidelines for extensibility (section 6 and all subsections)
7. MUST successfully parse the request according to OData-ABNF for any supported system query options and follow the specification or fail the request
8. MUST expose only data types defined in OData-CSDLXML
9. MUST NOT require clients to understand any metadata or instance annotations (section 6.4), custom headers (section 6.5), or custom content (section 6.2) in the payload in order to correctly consume the service
10. MUST NOT violate any OData update semantics (section 11.4 and all subsections)
11. MUST NOT violate any other OData-defined semantics
12. SHOULD support $expand (section 11.2.5.2)
13. SHOULD publish metadata at $metadata according to OData-CSDLXML and MAY publish metadata according to OData-CSDLJSON (section 11.1.2)
14. MUST support prefixed variants of supported headers and preference values
15. MUST support enumeration and duration literals in URLs with the type prefix

Additionally, if async operations are supported:

16. MUST return an HTTP message as the final response to an asynchronous request with an OData-MaxVersion value of 4.0 and an Accept header including application/http.
17. MAY return the AsyncResult header in the final response to an asynchronous request

To be considered an Updatable OData Service, the service additionally:

18. MUST include edit links (explicitly or implicitly) for all updatable or deletable resources according to OData-JSON, section 4.6.9
19. MUST support POST of new entities to insertable entity sets (section 11.4.1.5)
20. MUST support POST of new related entities to updatable navigation properties (section 11.4.2)
21. MUST support POST to $ref to add an existing entity to an updatable related collection (section 11.4.6.1)
22. MUST support PUT to $ref to set an existing single updatable related entity (section 11.4.6.3)
23. MUST support PATCH to all edit URLs for updatable resources (section 11.4.3)
24. MUST support DELETE to all edit URLs for deletable resources (section 11.4.5)
25. MUST support DELETE to $ref to remove a reference to an entity from an updatable navigation property (section 11.4.6.2)
26. MUST support If-Match header in update/delete of any resources returned with an ETag (section 11.4.1.1)
27. MUST return a Location header with the edit URL or read URL of a created resource (section 11.4.2)
28. MUST include the OData-EntityId header in response to any create or upsert operation that returns 204 No Content (section 8.3.4)
29. MUST support Upserts (section 11.4.4)
30. SHOULD support PUT and PATCH to an individual primitive (section 11.4.9.1) or complex (section 11.4.9.3) property (respectively)
31. SHOULD support DELETE to set an individual property to null (section 11.4.9.2)
32. SHOULD support deep inserts (section 11.4.2.2)
33. MAY support set-based updates (section 11.4.14) or deletes (section 11.4.15) to members of a collection

In order to conform to the OData Intermediate Conformance Level, a service:

1. MUST conform to the OData 4.0 Minimal Conformance Level
2. MUST successfully parse the request according to OData-ABNF and follow the specification or fail the request
3. MUST support $select (section 11.2.5.1)
4. MUST support casting to a derived type according to OData-URL, section 4.11 if derived types are present in the model
5. MUST support $top (section 11.2.6.3)
6. MUST support /$value on media entities (section 11.1.2) and individual properties (section 11.2.4.2)
7. MUST support $filter (section 11.2.6.1)
   1. MUST support eq, ne filter operations on properties of entities in the requested entity set (section 11.2.6.1.1)
   2. MUST support aliases in $filter expressions (section 11.2.6.1.3)
   3. SHOULD support additional filter operations (section 11.2.6.1.1) and MUST fail the request for any unsupported filter operations
   4. SHOULD support the canonical functions (section 11.2.6.1.2) and MUST fail the request for any unsupported canonical functions
   5. SHOULD support $filter on expanded entities (section 11.2.5.2.1)
8. SHOULD publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
9. SHOULD support the OData-JSON format
10. SHOULD consider supporting basic authentication as defined in RFC7617 over HTTPS for the highest level of interoperability with generic clients
11. SHOULD support the $search system query option (section 11.2.6.6)
12. SHOULD support the $skip system query option (section 11.2.6.4)
13. SHOULD support the $count system query option (section 11.2.6.5)
14. SHOULD support $expand (section 11.2.5.2)
15. SHOULD support the lambda operators any and all on navigation- and collection-valued properties (OData-URL, section 5.1.1.13)
16. SHOULD support the /$count segment on navigation and collection properties (section 11.2.10)
17. SHOULD support $orderby asc and desc on individual properties (section 11.2.6.2)

In order to conform to the OData Advanced Conformance Level, a service:

1. MUST conform to at least the OData 4.0 Intermediate Conformance Level
2. MUST publish metadata at $metadata according to OData-CSDLXML (section 11.1.2)
3. MUST support the OData-JSON format
4. MUST support the /$count segment on navigation and collection properties (section 11.2.10)
5. MUST support the lambda operators any and all on navigation- and and collection-valued properties (OData-URL, section 5.1.1.13)
6. MUST support the $skip system query option (section 11.2.6.4)
7. MUST support the $count system query option (section 11.2.6.5)
8. MUST support $orderby with asc and desc on individual properties (section 11.2.6.2)
9. MUST support $expand (section 11.2.5.2)
   1. MUST support returning references for expanded properties
   2. MUST support $filter on expanded collection-valued properties
   3. MUST support cast segment in expand with derived types
   4. SHOULD support $orderby with asc and desc on expanded collection-valued properties
   5. SHOULD support $count on expanded collection-valued properties
   6. SHOULD support $top and $skip on expanded collection-valued properties
   7. SHOULD support $search on expanded collection-valued properties
   8. SHOULD support $levels for recursive expand (section 11.2.5.2.1.1)
   9. MAY support $compute on expanded properties
10. MUST support the $search system query option (section 11.2.6.6)
11. MUST support batch requests according to the multipart format (section 11.7 and all subsections) and MAY support batch requests according to the JSON Batch format defined in OData-JSON, section 19
12. MUST support the resource path conventions defined in OData-URL, section 4
13. SHOULD support asynchronous requests (section 11.6)
14. SHOULD support Delta change tracking (section 11.3)
15. SHOULD support cross-join queries defined in OData-URL, section 4.15
16. MAY support the $compute system query option (section 11.2.5.3)

In order to conform to the OData 4.01 Minimal Conformance Level, a service:

1. MUST conform to the OData 4.0 Minimal Conformance Level
2. MUST be compliant with version 4.01 of the OData-JSON format
3. MUST return the AsyncResult result header in the final response to an asynchronous request if asynchronous operations are supported.
4. MUST support both prefixed and non-prefixed variants of supported headers and preference values
5. MUST reject a request with an incompatible $schemaversion system query option if a Core.SchemaVersion annotation is returned in $metadata
6. MUST support specifying supported system query options with or without the $ prefix
7. MUST support case-insensitive query option, operator, and canonical function names
8. MUST return identifiers in the case they are specified in $metadata
9. MUST support both 4.0 and 4.01 syntax in URLs for supported functionality regardless of requested OData-MaxVersion
   1. MUST support casting strings to primitive types in URLs
   2. MUST support enumeration and duration literals in URLs with or without the type prefix
   3. MUST support invoking parameter-less function imports with or without parentheses
   4. MUST support an empty object or no-content for the request body when invoking an action with no non-binding parameters
   5. MUST support invoking functions and actions in a default namespace with or without namespace qualification
   6. MUST support parameter aliases for key values and function parameter values if they allow the octets 00 (NUL), 2F (forward slash), or 5C (backslash) in string literals
   7. SHOULD support implicit aliasing of parameters
   8. SHOULD support eq/ne null comparison for navigation properties with a maximum cardinality of one
   9. SHOULD support the in operator
   10. SHOULD support divby
   11. SHOULD support negative indexes for the substring function
   12. MAY support Key-As-Segment URL convention
       1. MUST also support canonical URL conventions (described in OData-URL, section 4.3.1) or include URLs in payload
   13. MAY support the count of a filtered collection in a common expression
   14. MAY support equal and non-equal structural comparison
10. SHOULD publish metadata at $metadata according to both OData-CSDLXML and OData-CSDLJSON (section 11.1.2)
11. SHOULD NOT have identifiers within a uniqueness scope (e.g. a schema, a structural type, or an entity container) that differ only by case
12. SHOULD return the Core.ODataVersions annotation
13. SHOULD report capabilities through the Capabilities vocabulary
14. MAY support filtering on annotation values
15. MAY support $compute system query option
16. MAY support $search for all collections
17. MAY support 4.01 behavior, including returning 4.01 content and payloads, if the client does not specify the OData-MaxVersion:4.0 request header

In addition, to be considered an Updatable OData 4.01 Service, the service:

18. MUST conform to the OData 4.0 Minimal Conformance Level for an Updateable service.
19. MUST support DELETE to the reference of a collection member to be removed, identified by key (section 11.4.6.2)
20. SHOULD support PUT against single entity with nested content
21. SHOULD support deep updates (section 11.4.3.1) and deep inserts (section 11.4.2.2)
22. SHOULD support PUT or DELETE to $ref of a collection-valued nav prop
23. MAY support POST to collections of complex/primitive types
24. MAY support PATCH and DELETE to a collection
25. MAY support POST, PATCH and DELETE to a collection URL terminating in a type cast segment
26. MAY support PATCH to entity sets using the 4.01 delta payload format
27. MAY support $select and $expand on data modification requests

In order to conform to the OData 4.01 Intermediate Conformance Level, a service:

1. MUST conform to the OData 4.01 Minimal Conformance Level
2. MUST conform to the OData 4.0 Intermediate Conformance Level
3. MUST support eq/ne null comparison for navigation properties with a maximum cardinality of one
4. MUST support the in operator
5. MUST support the $select option nested within $select
6. SHOULD support the count of a filtered collection in a common expression
7. SHOULD support equal and non-equal structural comparison
8. SHOULD support $compute system query option
9. SHOULD support nested query options in $select
10. MAY support nested parameter alias assignments in $select and $expand
11. MAY support filtering a collection using a /$filter path segment

In order to conform to the OData 4.01 Advanced Conformance Level, a service:

1. MUST conform to the OData 4.01 Intermediate Conformance Level
2. MUST conform to the OData 4.0 Advanced Conformance Level
3. MUST support the count of a filtered/searched collection in a common expression
4. MUST support $compute system query option
5. MUST support nested options in $select
   1. MUST support $filter on selected collection-valued properties
   2. SHOULD support $orderby with asc and desc on selected collection-valued properties
   3. SHOULD support the $count on selected collection-valued properties
   4. SHOULD support $top and $skip on selected collection-valued properties
   5. SHOULD support $search on selected collection-valued properties
6. MUST publish metadata at $metadata according to OData-CSDLJSON (section 11.1.2)
7. MUST support batch requests according both to the multipart format (section 11.7 and all subsections) and the JSON Batch format defined in OData-JSON, section 19
8. SHOULD support filtering a collection using a /$filter path segment
9. SHOULD support nested parameter alias assignments in $select and $expand
10. MAY support case-insensitive comparison of identifiers in URLs and request payloads if no exact match is found, using the same lookup sequence as for default namespaces with a case-insensitive comparison