11.Data Protocol V4.0 Conformance Levels

OData is designed as a set of conventions that can be layered on top of existing standards (REST, JSON, XML, ATOM) to provide common representations for common functionality. Not all services will support all of the conventions defined in the protocol; services SHOULD chose those conventions defined in OData as the representation to expose that functionality appropriate for their scenarios.

To aid in client/server interoperability, this specification defines multiple levels of conformance for an OData Service, as well as the minimal requirements for an OData Client to be interoperable across OData services.

11.1OData Service Conformance Levels

OData defines three levels of conformance for an OData Service.

The conformance levels are design to correspond to different service scenarios. For example, a service that publishes data compliant with one or more of the OData defined formats may comply with theOData Data Publishing Conformance Level without supporting any additional functionality. A service that supports finer grained query functionality may comply with the OData Data Service Conformance Level. Services that conform to the OData Full Conformance Level can expect to interoperate with the most functionality against the broadest range of generic clients.

Services are encouraged to support as much additional functionality beyond their level of conformance as is appropriate for their intended scenario.

11.1.1OData Data Publishing Level

In order to conform to the OData Data Publishing conformance level, a service:

SHOULD use dereferenceable ids
MUST publish a service document at the service root
MUST return data according to at least one of the OData defined formats
MUST include a next link, formatted according to the appropriate OData format, if the results span more than one page
MUST return the appropriate DataServiceVersion header
MUST honor the semantics the following headers, or fail the request
odata.version
accept
MaxDataServiceVersion
MinDataServiceVersion
MUST follow OData guidelines for extensibility, specifically
Custom query options MUST NOT start with $
Additional elements in payload MUST be able to be safely be ignored
MUST fail any request containing unknown query options, actions or functions
Custom headers MUST NOT start with "odata."
SHOULD support casting to a derived type if present in the model
SHOULD support $expand to specify the extent of the graph to retrieve
MUST return 501,"Not Implemented" for any unsupported (including unknown) query string options starting with "$"
The service SHOULD include the appropriate not supported code
MUST successfully parse the request according to[OData-ABNF]for any supported system query string options and either follow the specification or return 501,"Not Implemented" for any unsupported functionality.
the service SHOULD include the appropriate not supported code
MUST ignore any unsupported preference header value
MUST expose only datatypes defined in this specification
MUST NOT require clients to understand any metadata or instance annotations, custom headers, or custom content in the payload in order to correctly consume the service
MUST NOT violate any odata update semantics
MUST NOT violate any other OData defined semantics

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

MUST include editlinks (explicitly or implicitly) for all updatabale or deletable resources
MUST support POST of new entities to insertable entity sets
MUST support POST of new related entities to updatable navigation properties
MUST support POST to $ref to add an existing entity to an updatable related collection
MUST support PUT to $ref to set an existing single updatable related entity
MUST support PATCH to all editlinks for updatable resources
MUST support DELETE to all editlinks for deleteable resources
MUST support DELETE to $ref to remove an entity from an updatable navigation property
MUST support if-match header in update/delete of any resources returned with an etag
MUST return a Location header from POST with the edit-link or self-link of the created resource
MUST include the DataServiceId header in response to any POST/PATCH that returns 204, no content

11.1.2OData Data Service Level

In order to conform to the OData Data Service conformance level, a service:

MUST conform to the OData Data Publishing level
SHOULD publish metadata at /$metadata according to [ODATA-CSDL]
SHOULD support the OData JSON format
MUST support $select
MUST support casting to a derived type if present in the model
SHOULD support $orderbyasc or descon individualproperties
MUST support $top
MUST support $filter
MUST support eq, nefilter operations on filterable properties
MUST support parameterized expressions (@paramname in place of a literal) in $filter
SHOULD support additional filter operations and MUST fail on any unsupported filter operations
SHOULD support the query functions and MUST fail on any unsupported query operations
SHOULD support $search
SHOULD support $skip
SHOULD support /$count
SHOULD support $expand for expandable navigation properties
SHOULD support $filter on expanded properties
SHOULD support any/all on collections
SHOULD support /$count on navigation, collection properties within a $filter expression
SHOULD support $search
MUST support cast segments for derived types
MUST successfully parse the [OData ABNF] and either follow the specification or return 501, "Not Implemented" for any unsupported functionality
MUST support selecting individual property values; i.e., /property/$value

11.1.3OData Full Data Service Level

In order to conform to the OData FullData Serviceconformance level, a service:

MUST conform to at least the OData Data Service Level
MUST support the OData JSON format
MUST use dereferenceable IDs
MUST support all filter operators on filterable properties
MUST support /$count on navigation, collection properties within a $filter expression
MUST support any/all on collections
MUST support $skip
MUST support /$count
SHOULD support $inlinecount
MUST support $expand for expandable navigation properties
MUST support returning references for expanded properties
MUST support $filter on filterable properties of expanded entities
MUST support cast segment in expand with derived types
SHOULD support $orderby for individual orderable properties of expanded entities
SHOULD support $inlinecount of expanded properties
SHOULD support $top and $skip on expanded properties
MUST support $search
MUST follow optional URL conventions (possibly through redirects)
Canonical Key Syntax
Navigation of relationships
Entity References

11.1.4Optional Data Service Features

In addition to minimally supporting the OData Data Publishing Conformance Level, an OData Service MAY support the following optional features.

The following Preferences within the Prefer header:
return=minimal, return=representation
async
odata.allow-references
odata.include-annotations
odata.maxpagesize
odata.track-changes
The following System Query Options
$search
$expand
$select in expands
filtered expands
ordered expands
$inlinecount in expands
/$count, /$ref
recursive expand
$inlinecount
$skip
selecting just entity references; i.e., path/$ref
Specific canonical functions
Queries rooted at the entity container
Batch Operations
Delta Change Tracking
Metadata as a Service
Specific data model features
open types, particular data types, navigation properties, containment
named entities, functions, actions, function imports
Extended Update Functionality
Deep insert, posting to navigation properties, etc.
Direct update to property
todo…>

11.1.5Not Supported Codes

Compliant services that don't support optional operations MUST recognize the request and SHOULD respond with 501, Not Implemented, and SHOULD include an error body, formatted in the requested format, containing the error code and description of the error.

Batch operations not supported

$filter not supported on this collection

$filter not supported on <property-name property

$orderby not supported on this collection

$orderby not supported on <property-name property

$expand not supported on navigation-property-name

Path navigation not supported for <navigation-property-name

Recursive expand not supported on navigation-property-name

Filtered expand not supported on <navigation-property-name

Count not supported on <navigation-property-name

functionfunction not supported

queryoptionquery option not supported

Canonical Key Syntax not supported

11.2Interoperable OData Clients

To be generally interoperable, OData Clients:

MUST specify a MaxDataServiceVersion header in request
MUST specify DataServiceVersion and content-type in any request with a payload
MUST use JSON?
MUST understand JSON minimal OR explicitly specify no odata.metadata=none or odata.metadata=full in request
MUST ignore odata.kind objects not defined in the version of the response
MUST support entities and entity references returned as top level objects or within an array
MUST process or ignore all odata.* annotations defined in the version of the response
MUST ignore odata.* annotations not defined in the version of the response
if supporting ATOM
MUST support atom entries and entity references defined in the odata metadata namespace as top level elements or within an atom feed
MUST ignore attributes and elements defined in the odata metadata namespace not defined in the version of the response
MUST ignore elements within a feed not defined in the version of the response
MUST ignore unknown annotations
MUST follow redirects
MUST be prepared to process nextlinks
if supporting updates
MUST generate PATCH requests for updates
MUST support arbitrary entity models
MUST support all primitive types defined in this specification
MUST support complex types, enumerations, collections of primitive/complex types/enumerations
MUST support derived entity types, complex types
MUST support entities with navigation properties
MUST support entities with composite keys
MUST support one-way navigation properties and unspecified related entitysets
MUST support TypeDefinitions
MUST support instances returning properties, navigation properties not specified in metadata
MUST support heterogeneous results where types/sets are explicitly specified per instance?

11.2.1Optional Client Features

Clients MAY support the following features by explicitly requesting them in the request.

Entity References in place ofentities previously returned in the response
Delta Links
Deleted Entries, Link Entries, Deleted Link Entries in a Delta Response
Asynchronous responses
Minimal metadata in a JSON response

12.JSON Conformance

In order to conform to the OData JSON format, a service:

MUST return well-formed JSON payloads
MUST follow the syntax defined in this specification:
Responses MUST include an odata.metadata property, unless odata.metadata=none has been specified in the request
Responses typed to return a single structured object MUST be formatted as a single top-level JSON object
Responses typed to return a single primitive value MUST be formattedas a single top-levelJSON object with a property named "value" containing the primitive value
Responses typed to return a collectionMUST be formattedas a single top-level JSON object containing aJSON arraywhose name MUST be "value"
Primitive typed properties within an entity or complex type MUST be represented as name-value pairs, where the name is the name of the property and the value is the value of the primitive type.
Int64 values MUST be represented as strings
Complex typed properties and expanded to-one navigation properties within an entity or complex type MUST be represented as a name-value pair within the JSON object representing the entity or complex type where the name is the name of the property and the value is a single JSON object representing the complex property or related entity.
Collection-valued properties and expanded to-many navigation properties within an entity or complex type MUST be represented as a name-value pair within the JSON object representing the entity or complex type where the name is the name of the property and the value is a JSON array containing the individual values from the collection or related entities.
Additional mark-up MUST be exposed using annotation syntax (ns.termname or name)
MUST support returning full metadata (note; it's valid to return full even if the client requests minimal or none) including at least:
odata.type
odata.id
odata.editlink or odata.selflink if the odata.id is not derferenceable
odata.set for any set not prescribed by the metadata url
gationLink for navigation properties
MUST include a next link annotation in the feed for partial results
MUST NOT violate any other aspects of the OData JSON specification

13.ATOM Conformance

In order to conform to the OData ATOM format, a service:

MUST return well-formed ATOM payloads with the following exceptions:
The next link MAY be returned at the end of the payload
The delta link MAY be returned at the end of the payload
MUST follow the syntax defined in this specification:
Entities MUST BE returned as atom entry elements
Properties MUST BE returned as elements whose name MUST correspond to the name of the property defined within the odata data namespace. Such of elements MUST BE returned as direct children of an element named "properties" defined within the odata metadata namespace.
For non-media entities the properties element MUST BE returned as a child of the atom content element.
For media entities, the properties element MUST BE returned as a peer to the atom content element.
Entries MUST contain an atom category element with a scheme attribute value of " and a term attribute value specifying the namespace qualified name of the type of the entity.
Relationships MUST BE returned as link elements with a rel value equal to the name of the navigation property prepended with " and an href attribute whose value is the URL for retrieving the related entity(ies).
MUST include a next link in the feed for partial results
MUST NOT violate any other aspects of the OData ATOM specification