OData Version 4.0 is the current recommended version of OData. OData V4 has been standardized by OASIS and has many features not included in OData Version 2.0.
OData supports two formats for representing the resources (Collections, Entries, Links, etc) it exposes: the XML-based Atom format and the JSON format. This document describes how OData resources are represented in Atom (plus additional elements defined in AtomPub) and [OData-JSON] describes the JSON representation. The content type negotiation section of the [OData-Operations] document describes how clients can use standard HTTP content type negotiation to tell an OData service which format it wants to use.
1. Background
As described in Atom [RFC4287], Atom is an XML-based document format that describes Collections of related information known as "feeds". Feeds are composed of a number of items, known as Entries. AtomPub [RFC5023] defines additional format constructs for Entries and Feeds to enable the resources they represent to be easily categorized, grouped, edited and discovered. For the remainder of this document, the term Atom is used to represent the combination of the format/representation rules defined in Atom[RFC4287] and AtomPub [RF5023].
As noted in the OData Basics section of [OData:Core], OData services expose Collections of structured Entries, making Atom a natural fit for representing OData resources. Since Atom does not define how structured data is encoded with feeds, to enable transfers of structured content by OData services, this document defines a set of conventions for representing structured data in an Atom feed.
It should be noted that feeds following the conventions defined in this document are valid AtomPub feeds and can be consumed by feed readers, tools, etc. which are only aware of the Atom standards ([RFC4287] & [RFC5023]), but not the additional conventions defined in this document.
2. Atom Representations
The following sections define how resources (Collection, Entries, etc) exposed by an OData service can be represented in requests and responses payloads using the Atom format. For details regarding how to create various request types (Retrieve, Create, etc) see [OData-Operations] .
Through out this section the notation is used to refer to the named element in the Atom [RFC4287] specification.
2.1. Primitive Types
Values of OData primitive types are represented as values of XML elements/attributes as per the table below. Note: The type system used by OData services is described in full in the primitive types section of the [OData-Core] document. In addition to the rules stated in the table, if the value of a primitive type is null, then it is represented as an empty XML element with an m:null="true" attribute ("m" identifies the OData metadata namespace).
Primitive Type
Serialization Format in XML Documents
Edm.Binary
Base64 encoded value of an EDM.Binary value. See [RFC3548] .
As described in [OData-Core], if a service exposes several Collections, then to aid discovery of those Collections by clients it is useful for the service to expose a Service Document which lists the available Collections. Service Documents are described in AtomPub [RFC5023], section 15.
For example, the URI https://services.odata.org/OData/OData.svc identifies the Service Document of a sample OData service which exposes a Categories, Products and Suppliers Collection. For convenience, a sample Service Document is shown in the listing below.
Collections represent a set of Entries. In OData, Collections are represented as Atom feeds ([RFC5023] ), with one Atom entry for each Entry within the Collection. For example, a Collection of product category Entries (that could be part of a product catalog) exposed by an OData service, as identified by the URI https://services.odata.org/OData/OData.svc/Categories, is represented as shown below. The format of elements within a feed is described in the Representing Entries section.
Note: The "m" and "d" prefixes represent the OData metadata and data namespaces. It is likely the next version of OData will generalize the namespace URI to use an odata.org based URI.
OData V1:
<?xml version="1.0" encoding="utf-8" standalone="yes"?><feedxml:base=https://services.odata.org/OData/OData.svc/xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservicesxmlns:m=http://schemas.microsoft.com/ado/2007/08/dataservices/metadataxmlns="https://www.w3.org/2005/Atom"><titletype="text">Categories</title><id>https://services.odata.org/OData/OData.svc/Categories</id><updated>2010-03-10T08:38:14Z</updated><linkrel="self"title="Categories"href="Categories"/><entry><id>https://services.odata.org/OData/OData.svc/Categories(0)</id><titletype="text">Food</title><updated>2010-03-10T08:38:14Z</updated><author><name/></author><linkrel="edit"title="Category"href="Categories(0)"/><linkrel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products"type="application/atom+xml;type=feed"title="Products"href="Categories(0)/Products"/><categoryterm="ODataDemo.Category"scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/><contenttype="application/xml"><m:properties><d:IDm:type="Edm.Int32">0</d:ID><d:Name>Food</d:Name></m:properties></content></entry><!-- <entry> elements representing additional Categories go here --></feed>
In response payloads only, OData v2 supports two pieces of collection-level metadata: an Entry count (the total count of the number of entities in the Collection) and "next links" in the case when a partial listing of the Collection of Entries is being represented.
The Entry count, is only included in the feed returned by an OData service when the request URI includes the $inlinecount System Query Option. In this case, the count information is represented as a element with the value of the element being the total number of Entries in the Collection. See the $inlinecount section of the [OData-URI] document for a description of how the count value is calculated.
In response payloads only, if the server does not include an element for every Entry in the Collection identified by the request URI (typically for resource conservation reasons), then the returned feed represents a partial listing as defined in AtomPub [RFC5023] section 10.1. In this case, the response includes a element to indicate the feed is a partial listing and to provide the URI of the next partial list feed so a client can easily continue obtaining additional entries. Version Note: Partial lists of Entries are supported in OData V2.0 only. For more information on interacting with partial listings, see Retrieving feeds, entries and service documents in the [OData-Operations] document.
OData V2:
<feedxml:base="https://services.odata.org/Northwind/Northwind.svc/"xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"xmlns:m=http://schemas.microsoft.com/ado/2007/08/dataservices/metadataxmlns="https://www.w3.org/2005/Atom"><titletype="text">Customers</title><id>https://services.odata.org/Northwind/Northwind.svc/Customers</id><updated>2010-03-10T09:34:11Z</updated><linkrel="self"title="Customers"href="Customers"/><strong><m:count>91</m:count></strong><entry><id>https://services.odata.org/Northwind/Northwind.svc/Customers('ALFKI')</id><titletype="text"/><updated>2010-03-10T09:34:11Z</updated><author><name/></author><linkrel="edit"title="Customer"href="Customers('ALFKI')"/><linkrel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Orders"type="application/atom+xml;type=feed"title="Orders"href="Customers('ALFKI')/Orders"/><linkrel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/CustomerDemographics"type="application/atom+xml;type=feed"title="CustomerDemographics"href="Customers('ALFKI')/CustomerDemographics"/><categoryterm="NorthwindModel.Customer"scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/><contenttype="application/xml"><m:properties><d:CustomerID>ALFKI</d:CustomerID><d:CompanyName>Alfreds Futterkiste</d:CompanyName><d:ContactName>Maria Anders</d:ContactName><d:ContactTitle>Sales Representative</d:ContactTitle><d:Address>Obere Str. 57</d:Address><d:City>Berlin</d:City><d:Regionm:null="true"/><d:PostalCode>12209</d:PostalCode><d:Country>Germany</d:Country><d:Phone>030-0074321</d:Phone><d:Fax>030-0076545</d:Fax></m:properties></content></entry><!-- <entry> elements representing additional customers goes here --><strong><linkrel="next"href="https://services.odata.org/Northwind/Northwind.svc/Customers?
$inlinecount=allpages&$skiptoken='ERNSH'"/></strong></feed>
2.4. Representing Entries
In OData, Entries are represented as Atom elements with all the Properties of the Entry represented as elements within the element which is a direct child of the element. When using an OData v2 server, clients may indicate that they want a subset of the properties by using the Select System Query Option in the request.
If the Entry being represented links to other Entries via Navigation Properties (e.g. a Product is related to a Category), then the Links are represented as http://schemas.microsoft.com/ado/2007/08/dataservices/related/[NavigationPropertyName] href=â€â€¦"/> elements â€" one for each Navigation Property of the Entry.
Metadata describing the Entry being represented can be specified using additional Atom-defined and OData-defined elements/attributes as defined by the following list.
As per [RFC4287], contains a URI which uniquely identifies the Entry
This element may be present with a term attribute whose value indicates the Entity Type in the data model of the OData service that describes the Entry represented by the parent element. An must contain at most one such category element with the specified scheme.
To ensure type fidelity across of Entries sent from server to client (and vice versa), this element must be included if the Entry is part of a type hierarchy and is not the base type in the hierarchy.
When this element is not present clients and servers should assume that the entry is of the base type of the containing collection, if that information is known. When a collection can contain a number of types within a inheritance hierarchy servers will typically reject requests that contain Entries without type information.
As per [RFC4287], this element is optional. If included it contains the URI a client should use to retrieve the Entry as described in [OData-Operations] .
As per [RFC5023], this element should be included. If included it contains the URI a client should use to update or delete the Entry as defined in [OData-Operations] .
m:etag attribute
An attribute in the OData Metadata Namespace whose value is the concurrency token associated with the Entry. The value is formatted as required by the ETag header in [RFC2616].
This attribute should be present in a response from an OData service when returning a feed (i.e. multiple Entries in a single HTTP response), otherwise the HTTP ETag response header should be used to communicate the concurrency token of the resource returned to a client.
For example, as shown in the following listing, the Category Entry identified by the URI https://services.odata.org/OData/OData.svc/Categories(0), has two primitive properties (ID & Name) and one Navigation Property named “Productsâ€, which identifies a feed of Product Entries related to the Category.
To conserve resources (bandwidth, CPU, and so on), it is generally not a good idea for an OData service to return the full graph of Entries related to the Entry (or Collection of entries) identified in a request URI. For example, an OData service should defer sending related Entries unless the client explicitly asked for them using the $expand System Query Option which provides a way for a client to state related entities should be represented inline.
As shown in the example in the prior section, by default properties which represent Links (the "Products" property in the example) are represented as a element to indicate the service deferred representing the related Entries. If needed, a client can then use the URI in the href attribute in a subsequent retrieve request to obtain the related Entries.
2.4.2. Inline Representation of Associated Entries
As described in the $expand System Query Option section of the [OData-URI] document, a request URI may include the $expand query option to explicitly request that a linked to Entry or collection of Entries be serialized inline, rather than deferred.
In this case the related Entry or collection of Entries is represented as the child element of an element as an or respectively. For example, a single Category Entry with its related Product Entries serialized inline is represented as shown in the example below.
Media Link Entries (MLE) are represented in the same way as regular Entries as described in Representing Entries; however, they also contain additional metadata per Entry that describes the Media Resource (MR) associated with the Entry and the element becomes a child of the element. The element is moved out from under the element because in the case of an MLE, the content describes the MR.
This additional MR-specific metadata is represented by the following constructs in the :
As per [RFC5023] section 9.6, this element indicates the URI a client should use to update or delete the Media Resource, as described in [OData-Operations] .
If the ETag of the Media Resource (MR) is independent from that of the Media Link Entry (MLE), then this element should include an m:etag attribute with value equal to the concurrency token of the MR.
For MLE's, this element describes the associated MR. The value of the src attribute is the URI a client should use to retrieve the Media Resource, as described in [OData-Operations]. Note: this allows a Media Resource to have independent links for editing and retrieval.
The value of the type attribute is the mime type of the MR.
2.4.4. Customizing the Representation of an Entry
Services may wish to have more flexibility over how Entries are represented within an element. For example, a service may want to enable the value of a property of an Entry be represented as the value of one of the standard Atom elements (Title, Summary, etc) or as the value of a custom element within an Entry. OData supports services that need this kind of control over the Atom representations of an Entry.
In general a service may choose to deviate from the conventions defined in Representing Entries section above and represent the value of a Property of an Entry as the value of a standard Atom element (Title, Summary, etc) or as the value of an element in a custom namespace. When a service does this form of customization it breaks the shared assumption between client and server regarding how Entries are encoded within an element. OData services that deviate from the prescribed encoding should expose a Service Metadata Document that include Feed Customization annotations which allow a client to discover how the server chose to encode a given Entry within the element. The remainder of this section describes the set of Feed Customization annotations that may be used.
The following table lists all the Feed Customization annotations defined in OData.
Feed Customization Annotation
Description
FC_SourcePath
The name of the Property on an Entry which this feed mapping rule applies to.The format of this parameter is a path expression where property names are separated by a / character. For example for a Person Entry with an integer Property Age and an Address Complex Type Property, the following are legal values for this property:
- Age
- Address/Street
The following are invalid values for this property:
- Foo (not a defined property)
- Address (doesn't identify a primitive property)
- Address/Street/ (cannot end with a /)
- Empty string or null
- /Address/Street (cannot start with a /)
FC_TargetPath
The name of the element to map the property identified by the FC_SourcePath annotation to. If no FC_SourcePath annotation is specified, then this annotation must be on a element in the Service Metadata Document which itself identifies the source Property.The format of this annotation is a path expression where nested elements are separated by a / and attributes are specified by a @ symbol.
For example, to map to a property value to a custom XML element or attribute:
To map the source Property to a custom element which is a direct child of the element use:
- FC_TargetPath="Category"
To map the source Property to an attribute named Term on a custom element which is a direct child of the element:
- FC_TargetPath="Category/@Term"
To map the source Property to a child element of the custom element named , where is a direct child of the element:
- FC_TargetPath="Category/Foo"
This annotation also supports mapping to Atom-defined elements. This following list describes the values used to map to Atom-defined elements: