Atom Format (OData Version 2.0)
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.
Go to OData Version 4.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.
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
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] .|
|Edm.Boolean||true | false|
|Edm.Byte||Same as the literal form in [OData:Core], except without the surrounding|
|Edm.DateTime||Same as the literal form in [OData:Core], except without the surrounding datetime'' syntax|
|Edm.Decimal||Same as the literal form in [OData:Core], except without the trailing "m"|
|Edm.Double||Same as the literal form in [OData:Core]|
|Edm.Guid||Same as the literal form in [OData:Core], except without the surrounding guid'' syntax|
|Edm.Int16||Same as the literal form in [OData:Core]|
|Edm.Int32||Same as the literal form in [OData:Core]|
|Edm.Int64||Same as the literal form in [OData:Core]|
|Edm.SByte||Same as the literal form in [OData:Core]|
|Edm.Single||Same as the literal form in [OData:Core], except without the trailing "f"|
|Edm.String||Same as the literal form in [OData:Core], except without surrounding double quotes|
|Edm.Time||Same as the literal form in [OData:Core], except without the surrounding time'' syntax|
|Edm.DateTimeOffset||Same as the literal form in [OData:Core], except without the surrounding datetimeoffset'' syntax|
2.2. Service Documents
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.
2.3. Representing Collections of Entries
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
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:
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
In response payloads only, if the server does not include an
2.4. Representing Entries
In OData, Entries are represented as Atom
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
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.
- The value of the element is the namespace qualified name of the Entity Type in the Service Metadata Document that describes the Entry.
- 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] .
- 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.
2.4.1. Deferred Content
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
2.4.3. Representing Media Link Entries
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
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
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
The following table lists all the Feed Customization annotations defined in OData.
For example, the sample Service Metadata Document at https://services.odata.org/OData/OData.svc/$metadata states the Name Property of the Category Entry is represented as the value of the
If the Category Entry in the example above was part of a type hierarchy and the Name property was defined on the type Category derives from, then the mapping from Name to
Instead of mapping the Name property to an Atom-defined element, a Property may be mapped to a custom element in any namespace. For example, the following listing maps the Street Property of the Address Complex Type on a Supplier entry to a custom
2.5. Representing Primitive Properties
When represented in a request/response payload as part of an Entry, Complex Type or a standalone construct in a request payload, primitive properties are represented in Atom as child elements of an
See section 3.1 for the format of Properties when they are represented independently from their defining Entry (i.e. outside the context of the defining Entry).
2.6. Representing Complex Type Properties
When represented as a property of an Entry or Complex Type (also within an Entry) in a request/response payload, a property whose type is a complex type is represented as an XML element with each property of the complex type represented as a direct child element (as described in the prior section for primitive properties). For example, the Address Complex Type of a Supplier Entry is shown in the example below.
See section 3.1.2 for the format of Complex Type Properties when they are represented independently from their defining Entry (i.e. outside the context of the defining Entry).
3. XML Representations
The smallest unit of information that can be represented in Atom is an Entry. In several application scenarios it is practical to be able to identify a specific piece of information within the Entry, particularly when the entry is mapped to an application-level construct on the server. For example, a Presentation Entry may have a Property that is the abstract describing the presentation.
To enable this scenario, as described in the Resource Path section in the [OData-URI] document, OData supports directly addressing a Property of an Entry. Since there is not a natural mapping of a single Property (outside of the context of the defining Entry) to an Atom representation, OData represents the constituent parts of an Entry using a simple XML representation, which is described by the following subsections.
3.1. Representing Property Values
As described in the Resource Path section in the [OData-URI] document, OData supports directly addressing a Property of an Entry. The following subsections describe how each type of Property is represented in XML.
3.1.1. Representing Primitive Properties
When a primitive Property is represented as a standalone construct in a response from an OData service (such as when a retrieve request is made to a URI that identifies a single Property) it is represented as a single XML element where the element name equals the name of the Property and the value of the element is the value Property value. For example, the response payload to a retrieve request that identifies the Name property of a Category Entry is represented as shown below.
3.1.2. Representing Complex Types Properties
When a Property whose type is a complex type is represented as a standalone construct, such as when a retrieve request is made to a URI that identifies a single Property, it uses a single XML element with the name of the Property and child elements for each Property defined on the complex type (formatted as per this section of the prior â€œRepresenting Primitive Propertiesâ€ section). For example, the response payload to a retrieve request that identifies the Name property of a Category Entry is represented as shown below.
3.1.3. Representing the Raw value of a Property
OData services may support addressing the entry value of a primitive Property (see the description of the $value URI segment). In this case, the value is returned using the format (aka mime type) the OData service deems to be the entry format for the Property. For example, the HTTP response from the sample OData service when retrieving the Name string Property of a Category Entry is shown in the example below.
3.2. Representing Links
A Link (or collection of Links) represents an associated Entry (or collection of associated Entries). As described in [OData-Operations] Links can be retrieved and modified to change the associations between Entries. A single link is represented as a
Note: in the paragraph above, "d" represents the OData Data Namespace.
For example, a link with multiplicity 1 (ex. Product is related to a single Supplier) would be represented in XML in a response as:
For example, a link with multiplicity greater than 1 (e.g. Supplier is related to many products) would be represented in a response as:
3.3. Representing Results from Service Operations
As described in [OData-Operations] OData services may expose custom behaviors via Service Operations, which may accept input parameters identified by the request URI (as described in [OData-URI]). This section specifies how the results of a Service Operation are formatted using Atom or XML. Service operations support returning:
- A single primitive value or collection of primitive values
- A single complex type or collection of complex types
- A single Entry or collection of Entries
If a Service Operation returns a collection of Entries or a single Entry, then the Entries (or Entry) are formatted in Atom as described in the Representing Collections of Entries or Representing an Entry section.
If a Service Operation returns a single primitive value, then it is formatted in XML as per the Representing Primitive Properties section. Likewise, if a Service Operation returns a single Complex Type value, then it is represented in XML as per the Representing Complex Type Properties section.
If a Service Operation returns a collection of primitive values, then the primitives are returned as the value of
If a Service Operation returns a collection of complex types, then the collection is represented in XML by a root element whose name is equal to the name of the Service Operation and includes one child