1. Overview

The OData protocol is comprised of a set of specifications for representing and interacting with structured content. This document describes the OData Atom Format returned from an OData Service when requesting the application/atom+xml mime type.

An OData payload may represent:

• a single primitive value
• a sequence of primitive values
• a single structured (“complex”) value
• a sequence of structured (“complex”) values
• an entity (a structured type with an identity)
• a sequence of entities
• a media resource
• a single instance of a mime type
• a single link to a related entity
• a collection of links to related entities
• a service document describing the collections (entity sets) exposed by the service
• an xml document describing the entity model exposed by the service
• an error
• a batch of requests to be executed in a single request
• a set of responses returned from a batch request

For a description of the xml format for describing an entity model, see OData:CSDL. For a description of batch requests and responses, see OData:Batch.

2. Notational Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119, “Key words for use in RFCs to Indicate Requirement Levels”)].

2.1. Normative References

This document references the following related documents:

• OData:Core. Core OData semantics and concepts.
• OData:CSDL. Detailed description of the OData Entity Data Model.
• OData:URL. Conventions for constructing OData requests.
• OData:ABNF Full ABNF rules for OData requests.
• OData:JSON A JSON encoding for OData payloads. OData services SHOULD support a JSON encoding.
• OData:Batch Support for grouping multiple OData requests in a single batch.
• RFC2616 HTTP 1.1 Specification
• RFC5023 The Atom Publishing Protocol
• RFC2119 Keywords for use in RFCs to Indicate Requirement Levels
• RFC4287 The Atom Syndication Format.
• RFC3987 Internationalized Resource Identifiers (IRIs)

3. xml:base Attribute

OData payloads may use the xml:base attribute to define a base URI for relative references defined within the scope of the element containing the xml:base attribute.

4. Primitive Types in Atom

OData Atom and XML payloads serialize primitive types as shown in the table below.

For full syntax rules, see OData:ABNF:

Primitive Type	Literal Form	Example
Null Represents the absence of a value	"null"	null
Edm.Binary Represent fixed- or variable- length binary data	((A-F | a-f | 0-9)(A-F | a-f | 0-9))*	23ABFF
Edm.Boolean Represents the mathematical concept of binary-valued logic	"true" | "1" "false" | "0"	true false
Edm.Byte Unsigned 8-bit integer value	(A-F | a-f | 0-9)(A-F | a-f | 0-9)	FF
Edm.DateTime Represents date and time with values ranging from 12:00:00 midnight, January 1, 1753 A.D. through 11:59:59 P.M, December 9999 A.D.	yyyy "-" mm "-" dd "T" hh ":" mm [":" ss["." fffffff]]	2000-12-12T12:00
Edm.Decimal Represents numeric values with fixed precision and scale. This type can describe a numeric value ranging from negative 10^255 + 1 to positive 10^255 -1	["-"][0-9]+[.][0-9]*	2.345
Edm.Double Represents a floating point number with 15 digits precision that can represent values with approximate range of ± 2.23e -308 through ± 1.79e +308	["-"][0-9]+ ((.[0-9]+) | [E[+ | -][0-9]+])	2.345
Edm.Single Represents a floating point number with 7 digits precision that can represent values with approximate range of ± 1.18e -38 through ± 3.40e +38	["-"][0-9]+.[0-9]	2.5
Edm.Float Represents a floating point number with 7 digits precision that can represent values with approximate range of ± 1.18e -38 through ± 3.40e +38	["-"][0-9]+.[0-9]	2.5
Edm.Guid Represents a 16-byte (128-bit) unique identifier value	dddddddd "-" dddd "-" dddd "-" dddd "-" dddddddddddd d= A-F |a-f | 0-9	12345678-aaaa-bbbb-cccc-ddddeeeeffff
Edm.Int16 Represents a signed 16-bit integer value	[-][0-9]+	16
Edm.Int32 Represents a signed 32-bit integer value	[-] [0-9]+	32
Edm.Int64 Represents a signed 64-bit integer value	[-] [0-9]+	64
Edm.SByte Represents a signed 8-bit integer value	[-] [0-9]+	8
Edm.String Represents fixed- or variable-length character data	any UTF-8 character Note: See definition of UTF8-char in [RFC3629]	OData
Edm.Time Represents the time of day with values ranging from 0:00:00.x to 23:59:59.y, where x and y depend upon the precision	Defined by the lexical representation for time at http://www.w3.org/TR/xmlschema-2	13:20:00
Edm.DateTimeOffset Represents date and time as an Offset in minutes from GMT, with values ranging from 12:00:00 midnight, January 1, 1753 A.D. through 11:59:59 P.M, December 9999 A.D	Defined by the lexical representation for datetime (including timezone offset) at http://www.w3.org/TR/xmlschema-2	2002-10-10T17:00:00Z
Edm.Geography Abstract base type for all Geography types.	N/A	N/A
Edm.GeographyPoint Represents a point in a round-earth coordinate system.	srid "Point(" point ")" srid= "SRID=" 1*5DIGIT ";" point= LONG LAT Where LONG and LAT are EDM.Doubles representing Longitude and Latitude.	SRID=123435;Point(33.84 -117.91)
Edm.GeographyLineString Represents a linestring in a round-earth coordinate system.	srid "LineString(" linestring ")" linestring= point ["," point]+	SRID=123435;Linestring(33.84 -117.91,48.87 2.78)
Edm.GeographyPolygonRepresents a polygon in a round-earth coordinate system.	srid "Polygon(" polygon ")" polygon= ring "," [ring ","]* ring= "(" firstpoint "," [point ","]* firstpoint ")" ]* ")" firstpoint = point	SRID=123435;Polygon((33.84 -117.91,48.87 2.78,33.84 -117.91))
Edm.GeographyCollection Represents a collection of Geography Values.	srid "GeographyCollection(" geographycollection ")" geographycollection= geographyvalue ["," geographyvalue]* geographyvalue="Point("point")" | "LineString(" linestring ")" | "Polygon(" polygon ")" | "GeographyCollection(" geographycollection ")" | "MultiPoint("multipoint ")" | "MultiLineString("multilinestring ")" | "MultiPolygon("multipolygon ")"	SRID=123435;GeographyCollection(Point(33.84 -117.91),Point(48.87 2.78))
Edm.GeographyMultiPointRepresents a collection of points in a round-earth coordinate system	srid "MultiPoint(" multipoint ")" multipoint= point ["," point]*	SRID=123435;MultiPoint((33.84 -117.91),(48.87 2.78))
Edm.GeographyMultiLineStringRepresents a collection of linestrings in a round-earth coordinate system.	srid "MultiLineString(" multilinestring ")" multilinestring= "(" linestring ")" [",(" linestring ")" ]*	SRID=123435;MultiLineString((33.84 -117.91,48.87 2.78),(33.84 -117.91, 28.36 -81.56))
Edm.GeographyMultiPolygonRepresents a collection of polygons in a round-earth coordinate system.	srid "MultiPolygon(" multipolygon ")" multipolygon= "(" polygon ")" [",(" polygon ")"]*	SRID=123435;MultiPolygon(((33.84 -117.91,(33.84 -117.91,28.36 -81.56,33.84 -117.91)))
Edm.Geometry Abstract base type for all Geometry types	N/A	N/A
Edm.GeometryPoint Represents a point in a flat-earth coordinate system.	srid "Point(" point ")"	SRID=123435;Point(33.84 -117.91)
Edm.GeometryLineString Represents a linestring in a flat-earth coordinate system.	srid "LineString(" linestring ")"	SRID=123435;Linestring(33.84 -117.91,48.87 2.78)
Edm.GeometryPolygonRepresents a polygon in a flat-earth coordinate system.	srid "Polygon(" polygon ")"	SRID=123435;Polygon((33.84 -117.91,48.87 2.78,33.84 -117.91))
Edm.GeometryCollection Represents a collection of Geometry Values.	srid "GeometryCollection(" geometrycollection ")" geometrycollection= geometryvalue ["," geometryvalue]* geometryvalue= "Point("point")" | "LineString(" linestring ")" | "Polygon(" polygon ")" | "GeometryCollection(" geometrycollection ")" | "MultiPoint("multipoint ")" | "MultiLineString("multilinestring ")" | "MultiPolygon("multipolygon ")"	SRID=123435;GeometryCollection(Point(33.84 -117.91),Point(48.87 2.78))
Edm.GeometryMultiPointRepresents a collection of points in a flat-earth coordinate system.	srid "MultiPoint(" multipoint ")"	SRID=123435;MultiPoint((33.84 -117.91),(48.87 2.78))
Edm.GeographyMultiLineStringRepresents a collection of linestrings in a flat-earth coordinate system.	srid "MultiLineString(" multilinestring ")"	SRID=123435;MultiLineString((33.84 -117.91,48.87 2.78),(33.84 -117.91, 28.36 -81.56))
Edm.GeographyMultiPolygonRepresents a collection of polygons in a flat-earth coordinate system.	srid "MultiPolygon(" multipolygon ")"	SRID=123435;MultiPolygon(((33.84 -117.91,(33.84 -117.91,28.36 -81.56,33.84 -117.91)))

5. Use of Atom

The Atom Syndication Format RFC4287 defines an XML-based format for describing collections (“feeds”) made up of individual “entries”. The Atom Publishing Protocol RFC5023 defines an application-level protocol based on HTTP transfer of Atom-formatted representations.

OData builds on RFC4287 and RFC5023 by defining additional conventions and extensions for representing and querying entity data.

5.1. Namespaces

OData defines meaning for elements and attributes defined in the following namespaces.

5.1.1. Atom Namespace

Atom elements and attributes are defined within the Atom namespace: “http://www.w3.org/2005/Atom”.

In this specification the namespace prefix “atom” is used to represent the Atom Namespace, however the prefix name is not prescriptive.

5.1.2. Atom Publishing Protocol Namespace

Atom Publishing Protocol (AtomPub) elements and attributes are defined within the AtomPub namespace: “http://www.w3.org/2007/app”.

In this specification the namespace prefix “app” is used to represent the AtomPub Namespace, however the prefix name is not prescriptive.

5.1.3. OData Data Namespace

Elements that describe the actual data values for an entity are qualified with the OData Data Namespace: “http://schemas.microsoft.com/ado/2007/08/dataservices”

In this specification the namespace prefix “data” is used to represent the OData Data Namespace, however the prefix name is not prescriptive.

5.1.4. OData Metadata Namespace

Attributes and elements that represent metadata (such as type, null usage, and entry-level etags) are defined within the OData Metadata Namespace: “http://schemas.microsoft.com/ado/2007/08/dataservices/metadata”. Custom elements or attributes MUST NOT use this namespace.

In this specification the namespace prefix “metadata” is used to represent the OData Metadata Namespace, however the prefix name is not prescriptive.

6. Atom Element Definition

OData’s Atom format defines extensions and conventions on top of RFC4287 and RFC5023 for representing structured data as follows:

6.1. Entity Instances

Entity Instances, whether individual or within an ATOM feed, are represented as atom:entry elements.

For example, the following atom:entry element describes a Product:

<entry>
  <id>http://services.odata.org/OData/OData.svc/Products(0)</id> 
  <title /> 
  <summary /> 
  <updated>2012-03-30T07:11:05Z</updated> 
  <author>
    <name /> 
  </author>
  <link rel="edit" title="Product" href="Products(0)" /> 
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Category" type="application/atom+xml;type=entry" title="Category" href="Products(0)/Category" /> 
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Supplier" type="application/atom+xml;type=entry" title="Supplier" href="Products(0)/Supplier" /> 
  <category term="ODataDemo.Product" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> 
  <content type="application/xml">
    <metadata:properties>
      <data:ID m:type="Edm.Int32">0</data:ID> 
      <data:Name>Bread</data:Name>
      <data:Description>Whole grain bread</data:Description>
      <data:ReleaseDate metadata:type="Edm.DateTime">1992-01-01T00:00:00</data:ReleaseDate> 
      <data:DiscontinuedDate metadata:type="Edm.DateTime" metadata:null="true" /> 
      <data:Rating metadata:type="Edm.Int32">4</data:Rating> 
      <data:Price metadata:type="Edm.Decimal">2.5</data:Price> 
    </metadata:properties>
  </content>
</entry>

This section defines the elements and attributes within an atom:entry element that are assigned meaning in OData.

6.1.1. Entities as atom:entry Elements

An atom:entry element is used to represent a single entity, which is an instance of a structured type with an identity.

6.1.1.1. The metadata:etag Attribute

The atom:entry element MAY contain a metadata:etag attribute, representing an opaque string value that can be used in a subsequent request to determine if the value of the entity has changed. For details on how ETags are used, see to OData:Core.

6.1.2. The atom:id Element

The atom:id element defines a durable, opaque, globally unique identifier for the entry. Its content must be an IRI as defined in RFC3987. The consumer of the feed must not assume this IRI can be de-referenced, nor assume any semantics from its structure.

6.1.3. Self and Edit Links as atom:link Elements

Atom defines two types of links within an entry that represent retrieve or update/delete operations on the entry.

atom:link elements with a rel attribute of "self" can be used to retrieve the entity (via the URL specified in the href attribute).

atom:link elements with a rel attribute of "edit" can be used to retrieve, update, or delete the entity (via the URL specified in the href attribute).

An atom:entry element representing an OData entity SHOULD contain a self link, an edit link, or both for a particular entry, but MUST NOT contain more than one edit link for a given entry. Absence of an edit link implies that the entry is read-only.

6.1.4. Stream Properties as atom:link Elements

An entity may have one or more stream properties (for example, a photo property of an employee entity). Properties that represent streams have a type of “Edm.Stream”.

OData uses atom:link elements to represent named stream properties of an entity.

For example, a stream property named “Photo” could be represented through an atom:link element as a child of the atom:entry element as follows:

<atom:link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/mediaresource/Photo" 
type="img/jpg" title="Photo" href="Categories(0)/Photo"/>

A stream property named “Photo” could be edited through an atom:link element as a child of the atom:entry element as follows:

<atom:link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/edit-media/Photo" 
type="img/jpg" title="Photo" href="Categories(0)/Photo"/>

6.1.4.1. The rel attribute of a Link Representing a Stream Property

The rel attribute for an atom:link element that can be used to retrieve a stream property is made up of the name of the OData Data Namespace, followed by the string “/mediaresource/”, followed by the name of the stream property on the entity.

The rel attribute for an atom:link element that can be used to write a stream property is made up of the name of the OData Data Namespace, followed by the string “/edit-media/”, followed by the name of the stream property on the entity.

In both cases the full name must be used; the use of relative URLs in the rel attribute is not allowed.

6.1.4.2. The href attribute of a Link Representing a Stream Property

The href attribute of an atom:link element describing an OData stream property contains the URL that can be used to read, or write, the stream, according to the rel attribute. This URL may be relative or absolute.

6.1.4.3. The title attribute of a Link Representing a Stream Property

The title attribute on an atom:link element describing an OData relationship provides human-readable, possibly language-dependent, and not necessarily unique information about the link. It has no implied semantics in OData.

6.1.5. Relationships as atom:link Elements

OData uses atom:link elements to represent relationships between entities.

For example, the set of related products for a particular catagory may be represented through an atom:link element as a child of a category entry element as follows:

<atom:link 
    rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products" 
    href="Categories(0)/Products"
    type="application/atom+xml;type=feed" 
    title="Products" />

The related data for the relationship MAY be included in the Entity using a single child metadata:inline element.

6.1.5.1. The rel attribute of an atom:link element Representing a Relationship

The rel attribute for an atom:link element that represents a relationship MUST be present and is made up of the name of the OData Data Namespace, followed by the string “/related/” followed by the name of the navigation property on the entity.

Note that the full name must be used; the use of relative URLs in the rel attribute is not allowed.

6.1.5.2. The href attribute of an atom:link element Representing a Relationship

The href attribute of an atom:link element describing an OData relationship MUST be present and specifies the URL that can be used to retrieve the related entities. This URL may be relative or absolute.

6.1.5.3. The type attribute of an atom:link element Representing a Relationship

The type attribute on an atom:link element describing an OData relationship MUST be present and determines whether the cardinality of the related end is:

• a single entity, in which case the type=“application/atom+xml;type=entry”, or
• a collection of entities, in which case the type=“application/atom+xml;type=feed”

6.1.5.4. The title attribute of an atom:link element Representing a Relationship

The title attribute on an atom:link element describing an OData relationship SHOULD be present and equal to the name of the navigation property, and provides human-readable, possibly language-dependent, and not necessarily unique information about the link.

6.1.6. Inline Content within a metadata:inline Element

An atom:link element describing an OData relationship MAY contain a single metadata:inline element, in which case the element contains the feed (in the case of a collection) or entry (in the case of a single entity), where the feed or entry is a child of the metadata:inline element formatted as per this document.

An empty metadata:inline element means that there is no content associated with the relationship (i.e., the navigation property is null). Note that this case is distinct from the absence of a metadata:inline element which simply means that the contents of the relationship is deferred (not included in the payload).

It is valid to include the metadata:inline element in only a subset of the entries within a feed.

6.1.7. Relationship Links as atom:link Elements

OData uses atom:link elements to represent the collection of relationship link(s) between entities.

For example, the set of links between a category and related products may be represented through an atom:link element as a child of a category entry element as follows:

<atom:link 
  rel="http://schemas.microsoft.com/ado/2007/08/dataservices/relatedlinks/Products" 
  href="Categories(0)/$links/Products"
  type="application/xml"
  title="Products" />

6.1.7.1. The rel attribute of an atom:link element Representing Relationship Links

The rel attribute for an atom:link element that represents a collection of relationship links MUST be present and is made up of the name of the OData Data Namespace, followed by the string "/relatedlinks/" followed by the name of the navigation property on the entity.

Note that the full name must be used; the use of relative URLs in the rel attribute is not allowed.

6.1.7.2 The href attribute of an atom:link element Representing Relationship Links

The href attribute of an atom:link element describing a relationship link MUST be present and specifies the URL that represents the collection of relationship links. This URL may be relative or absolute.

6.1.7.3. The type attribute of an atom:link element Representing Relationship Links

The type attribute on an atom:link element describing a relationship link MUST be present and equal to the content type “application/xml”

6.1.7.4. The title attribute of an atom:link element Representing Relationship Links

The title attribute on an atom:link element describing a relationship link SHOULD be present and SHOULD be set to the name of the navigation property. The title attribute provides human-readable, possibly language-dependent, and not necessarily unique information about the link.

6.1.8. Entity Type as an atom:category Element

An OData entry MAY contain a single atom:category element with a scheme attribute equal to "http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" to identify the entity type of the entry. This element MUST be present if the entry represents an entity whose type is part of a type hierarchy.

An atom:category element describing an OData entity type MUST have a term attribute whose value is the namespace qualified name of the entity type of the entry.

The entry MAY contain additional atom:category elements with different scheme values; such atom:category elements have no semantic meaning in OData.

6.1.9. Entity Content within an atom:content Element

The atom:content element defines the content of the entry.

6.1.9.1. Media Entities As Media Link Entries using the src Attribute

The atom:content element MAY contain a src attribute, in which case the entry is a Media Link Entry, used to represent a Media Resource (for example, a photo). The value of the src attribute MUST be a URI that can be used to retrieve the content of the Media Resource.

For Media Entities, the atom:content element MUST be empty. In this case, properties of the Media Resource (other than the stream) are represented by the metadata:properties element as a sibling to, rather than a child of, the atom:content element.

6.1.10. atom:link element for Updating Media Link Entries

A Media Link Entry MAY contain an atom:link element with a rel attribute of "edit-media" to specify a URL that can be used to write to the BLOB associated with the entity.

6.1.10.1. The rel attribute for writing to Media Link Entries

Within an atom:entry representing a Media Link Entry, an atom:link element with a rel attribute of “edit-media” is used to identify a link that can be used to write to the BLOB associated with the entry.

6.1.10.2. The href attribute for writing to Media Link Entries

An atom:link element representing the link used to write to the BLOB associated with the entity MUST include an href attribute to specify the URI that can be used to write the stream. This URI may be relative or absolute.

6.1.11. Entity Properties within a metadata:properties Element

The metadata:properties element represents a subset of the property values for an entity that are not exclusively mapped to defined or custom elements, as described in Custom Mapping to Atom Elements.

The metadata:properties element MUST be a direct child of the atom:content element EXCEPT for the case where the entry represents a media entity, in which case the metadata:properties element MUST be a sibling of the atom:content element. In the case that all properties of the entity are exclusively mapped to defined or custom elements, an empty metadata:properties element MAY be present.

6.1.11.1. Entity Property as a data:[propertyName] Element

Within the metadata:properties element, individual data values of the entity are represented as elements where the name of the element is the name of the entity property within the OData Data Namespace.

The data:[PropertyName] element MAY include a metadata:type attribute to specify the type of the simple- or complex-typed instance.

For example, the following element within an metadata:properties element represents the “Rating” field with an integer value of 4:

<data:Rating m:type="Edm.Int32">4</data:Rating> 

6.1.11.1.1. Simple Typed Properties

For simple typed properties, the content of the data:[propertyName] element represents the value of the property. For example, the following would represent the value “CEO” for the Title property of an entity:

<data:Title>CEO</data:Title>

6.1.11.1.2. Complex Typed Properties

For complex typed properties, the content of the data:[propertyName] element consists of nested data:[propertyName] elements describing the properties of the complex type. It MAY include a metadata:type attribute to specify the type.

For example, the complex typed property “Name”, with properties “FirstName” and “LastName” would be respresented as:

<data:Name metadata:type="MyModel.FullName">  
    <data:FirstName>Julie</data:FirstName>  
    <data:LastName>Swansworth</data:LastName>  
</data:Name>

6.1.11.1.3. Collection of Simple Typed Properties

For properties that represent a collection of simple types, the data:[propertyName] element may include a metadata:type attribute with a value of "Collection([SimpleTypeName])". The content of the element consists of nested child elements named “element”, in the OData Data Namespace, for each value in the collection.

The value of each simple-typed data:element in the collection follows the syntax for the simple typed property as defined for [simple-typed properties](#simpletypedproperties.

<data:element> elements MUST NOT contain the metadata:null="true" attribute value.

For example, the collection typed property “Emails” would be respresented as:

<data:Emails metadata:type="Collection(Edm.String)">  
    <data:element>Julie@Swansworth.com</data:element>  
    <data:element>Julie.Swansworth@work.com</data:element>  
</data:Emails>

6.1.11.1.4. Collection of Complex Typed Properties

For properties that represent a collection of complex types, the data:[propertyName] element may include a metdata:type attribute with a value of "Collection([ComplexTypeName])“ attribute. The content of the element consists of nested child elements named ”element", in the OData Data Namespace namespace, for each complex typed value in the collection.

The <data:element> element representing the instance may include a metadata:type attribute to specify the type of the individual element. The value of each complex-typed <data:element> follows the syntax for complex-typed properties.

<data:element> elements MUST NOT be empty and MUST NOT contain the metadata:null="true" attribute.

For example, the collection typed property “PhoneNumbers” would be respresented as:

<data:PhoneNumbers metadata:type="Collection(Person.PhoneNumber)"">  
    <data:element metadata:type="Person.PhoneNumber">  
        <data:Number>425-555-1212</data:Number>  
        <data:PhoneType>Home</data:PhoneType>  
    </data:element>  
    <data:element metadata:type="Person.CellPhoneNumber">  
        <data:Number>425-555-0178</data:Number>  
        <data:PhoneType>Cell</data:PhoneType>  
        <data:CellCarrier>Sprint</data:CellCarrier>  
    </data:element>  
</data:PhoneNumbers> 

6.1.12. Nulls represented using the metadata:null Attribute

Null valued properties are represented as empty elements with the metadata:null="true" attribute.

The metadata:null attribute distinguishes null values from other empty content (such as an empty string).

For example, the following represents an empty apartment number:

<data:Apartment metadata:null="true"/>

The absence of the metadata:null attribute is equivalent to specifying metadata:null="false".

6.1.13. Data Type represented using the metadata:type Attribute

Primitive-valued properties and Complex-valued properties that are not part of a hierarchy MAY contain a metadata:type to specify the primitive type of the property.

Complex-valued properties that are part of a hierarchy MUST contain a metadata:type attribute.

For Complex-valued properties, the value of the attribute is the namespace-qualified name of the complex type.

For example, the following specifies that the Age property is a 32bit integer with the value 25:

<data:Age metadata:type="Edm.Int32">25</data:Age>

6.2. Collections of Entities

Collections of entities are represented in Atom as an Atom Feed.

6.2.1 Collection of Entities as an atom:feed Element

Collections of entities are represented using an atom:feed Element, where each entity is represented as an atom:entry.

6.2.2. The atom:id Element within an atom:feed

The atom:id element defines a durable, opaque, globally unique identifier for the feed. Its content must be an IRI as defined in RFC3987. The consumer of the feed must not assume this IRI can be de-referenced, nor assume any semantics from its structure.

6.2.3. Count as a metadata:count Element

The atom:feed element may contain an m:count element to specify the total count of rows in the result. This may be greater than the number of rows in the feed if server side paging has been applied, in which case the feed will include a next results link.

6.2.4. Self Links as atom:link Elements

Atom requires that feeds contain a “self link”. A self link is represented as an atom:link with a rel attribute of “self” and an href that can be used to retrieve the feed from which the current entries are taken.

Note that the actual set of entries contained within the atom:feed may be a subset of those retrieved using the self link, for example, if filtering has been applied.

6.2.5. Additional Results as an atom:link element

The atom:feed element may contain a “next link” to indicate the presence of additional entries that belong to the feed. Such a link is represented as an atom:link with a rel attribute of "next" and an href attribute containing a URL that can be used to retrieve the next set of results.

For example, the following atom:link element within an atom:feed element indicates that additional results can be returned by following the specified href:

<atom:link rel="next" href="http://myservice/customers/?$skiptoken=1237"/>

The contents of the href should be treated as an opaque URL that can be used to fetch the next set of results.

7. Actions

Zero or more actions may be associated with a feed or entry.

The actions associated with a particular feed or entry MAY be described using metadata:action element(s) that are direct children of the feed or entry on which the action(s) exist.

For example, the following element describes an “Order” action:

<metadata:action
  metadata="#DemoService.OrderProduct"
  target="http://services.odata.org/OData/OData.svc/Products(1)/OrderProduct"
  title="Order"
/>

7.1. Actions as a metadata:action Element

Actions are represented as metadata:action elements that appear as direct children of the atom:feed or atom:entry element representing the feed or entity on which the action(s) exist.

7.1.1. The metadata:metadata Attribute for an Action

A metadata:action element MUST have a metadata:metadata attribute which specifies the container qualified name of the function import describing the action, preceded by a “#”. For example, “#MyEntityContainer.MyFunctionName”.

This function import name must be unique within the entity container.

If the metadata cannot be retrieved by appending "$metadata" to the service root, then this name MUST additionally be prefixed by a URL that can be used to retrieve the metadata document containing the function import that describes the action.

7.1.2. The metadata:target Attribute for an Action

A metadata:action element MUST have a metadata:target attribute that specifies the URL to POST to in order to invoke the action.

The first parameter of the action MUST be a binding parameter that is bound to the feed or entity on which the action is specified, and MUST NOT be provided as a separate parameter by the client when invoking the action.

7.1.3. The metadata:title Attribute for an Action

The metadata:action element MUST have a metadata:title attribute that contains a human-readable, possibly language-dependent, and not necessarily unique name for the action, commonly used by clients to describe the action to a user.

8. Functions

Zero or more functions may be associated with a feed or entry.

The functions associated with a particular feed or entry MAY be described using metadata:function element(s) that are direct children of the feed or entry on which the action(s) exist.

For example, the following element describes a “GetTopProducts” function:

<metadata:function
  metadata="#DemoService.GetTopProducts"
  target="http://services.odata.org/OData/OData.svc/Categories(0)/GetTopProducts()"
  title="GetTopProducts"
/>

8.1. Functions as a metadata:function Element

Functions are represented as metadata:function elements that appear as direct children of the atom:feed or atom:entry element representing the collection or entity on which the function(s) exist.

8.1.1. The metadata:metadata Attribute for a Function

A metadata:function element MUST have a metadata:metadata attribute which specifies the container qualified name of the function import describing the function, preceded by a “#”. For example, “#MyEntityContainer.MyFunctionName”.

The named function may have multiple overloads (multiple function imports) within the container. If the metadata:function cannot be used to invoke all overloads for the function, then it must further be distinguished by appending a comma separated ordered list of parameter type names, enclosed in parenthesis (). For example, “#MyEntityContainer.MyFunctionName(Edm.Integer, Edm.String)”.

If the metadata cannot be retrieved by appending "$metadata" to the service root, then this name MUST additionally be prefixed by a URL that can be used to retrieve the metadata document containing the function import that describes the function.

8.1.2. The metadata:target Attribute for a Function

A metadata:function element MUST have a metadata:target element that specifies the URL to GET from in order to invoke the function.

The first parameter of the function MUST be a binding parameter that is bound to the feed or entity on which the function is specified, and MUST NOT be provided as a separate parameter by the client when invoking the function.

8.1.3. The metadata:title Attribute for a Function

The metadata:function element MUST have a metadata:title attribute that contains a human-readable, possibly language-dependent, and not necessarily unique name for the function, commonly used by clients to describe the function to a user.

9. Annotations

In OData version 3.0, annotations may be appear as a child to any of the following elements: <atom:feed>, <atom:entry>, <metadata:properties>, <metadata:function>, <metadata:action>, <metadata:error>, or <atom:link> where rel indicates a navigation link or named stream.

There are two types of annotation terms in OData; ValueTerms and TypeTerms.

A ValueTerm defines a named annotation for a single primitive value. A ValueAnnotation specifies the value for a ValueTerm.

A TypeTerm defines a named annotation for a complex or entity typed value. A TypeAnnotation specifies the values for each property defined by the TypeTerm.

Custom ValueTerms and Custom TypeTerms MUST be defined in a namespace other than the Atom Namespace, AtomPub Namespace, OData Data Namespace, or OData Metadata Namespace. Annotations corresponding to custom terms add additional information about the item being annotated and SHOULD be designed in such a way that they can be safely ignored by the client.

TypeAnnotations and ValueAnnotations specify a target, which represents the collection, entry, property, function, action, navigation link, error, or named stream being annotated. The target is specified relative to the parent of the ValueAnnotation or TypeAnnotation, and is either the parent itself (“.”) or the name of the sibling element being annotated.

If more than one sibling exists with the same unqualifed name, then the namespace qualified element named MUST be used.

9.1. ValueAnnotations as custom Elements

A ValueAnnotation is specified by a single element containing the metadata:target attribute, whose element name is the namespace-qualified ValueTerm.

The content of the ValueAnnotation element is the value of the ValueTerm, formatted as per Primitive Types In Atom.

For example; the following specifies a value of “Home” for the “PhoneNumberType” ValueTerm applied to the “PhoneNumber” property of a customer:

  <metadata:properties  xmlns:contact="http://odata.org/vocabularies/contact/v1">
    <data:CustomerID>ALFKI</data:CustomerID>
    <data:ContactName> Alfreds Futterkiste </data:ContactName>
    <data:Phone>030-0074321</data:Phone>
    <contact:PhoneNumberType metadata:target="Phone">Home</contact:PhoneNumberType>
  </metadata:properties>

9.1.1. The metadata:target attribute

The metadata:target attribute MUST be present on a ValueAnnotation and identifies the target of the annotation as described in Annotations.

9.1.2. The metadata:type attribute

If the type of the annotation value being specified is Edm.String, then the ValueAnnotation element MAY contain the metadata:type attribute specifying “Edm.String”, otherwise the ValueAnnotation element MUST contain the metadata:type attribute specifying the appropriate primitive type.

9.2. Type Annotations as Custom Elements

A TypeAnnotation is specified by an element containing the metadata:target attribute, whose element name is the namespace-qualified TypeTerm.

The TypeAnnotation element contains a single child element for each property of the TypeTerm being specified. The name of each such child element is the namespace-qualified name of the property, and its content specifies the value of the corresponding property of the TypeTerm, formatted as per Primitive Types In Atom. If the type of the annotation property is Edm.String, then the child element MAY contain the metadata:type attribute specifying “Edm.String”, otherwise the child element MUST contain the metadata:type attribute specifying the appropriate primitive type.

For example; the following specifies the “StreetAddress”, “City”, “Region”, “Country” and “Postal Code” properties of an “Address” TypeTerm applied to a customer entity:

  <metadata:properties xmlns:contact="http://odata.org/vocabularies/contact/v1">
    <data:CustomerID>ALFKI</data:CustomerID>
    <data:ContactName> Alfreds Futterkiste </data:ContactName>
    <data:Phone>030-0074321</data:Phone>
    <contact:Address metadata:target=".">  
      <contact:StreetAddress>Obere Str. 578</contact:StreetAddress>
      <contact:City>Toronto</contact:City>
      <contact:Region metadata:null="true" />
      <contact:PostalCode>12209</contact:PostalCode>
      <contact:Country>Germany</contact:Country>
    </contact:Address>
  </metadata:properties>

9.2.1. The metadata:target attribute

The metadata:target attribute MUST be present on a TypeAnnotation and identifies the target of the annotation as described in Annotations.

10. Custom Mapping to Atom Elements

Individual property values MAY be mapped to predefined atom elements or custom content within the entry. The mapping is described through attributes in the metadata.

The mapping may specify whether the property value appears within the metadata:properties element as well as being mapped, however in the case of a null value the property MUST always appear within the metadata:properties element as an empty element with the metadata:null="true" attribute.

For more information on the format of the mapping specification, see OData:CSDL.

11. Individual Primitive or Complex Scalar Values

A valid OData payload may consist of a single primitive or complex property.

For example, a request for the first name of a given customer may return the following payload:

   <Title xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">CEO<Title> 

Similarly, the following payload represents a full name:

<FullName metadata:type="HumanResources.Address"
      xmlns:metadata="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
      xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">
   <FirstName>Julie</FirstName>
   <LastName>Swansworth</LastName>
</FullName>

12. Collections of Primitive or Complex Scalar Values

A valid OData payload MAY consist of a collection of primitive or complex properties. A collection is a single root element containing zero or more <metadata:element> elements whose content is an individual primitive or complex property as defined above.

For example, the following payload represents a collection of phone numbers.

<PhoneNumbers xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">     
    <element>(203)555-1718<element>
    <element>(203)555-1719<element>
</PhoneNumbers>

Similarly, the following payload represents a collection of full names.

<Names xmlns:metadata="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
       xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">
   <element metadata:type="HumanResources.FullName">
       <FirstName>Julie</FirstName>
       <LastName>Swansworth</LastName>
   </element>
   <element metadata:type="HumanResources.FullName">
        <FirstName>Mark</FirstName>
        <LastName>Swansworth</LastName>
   </element>
</Names>

13. Entity Container as a Workspace within a Service Document

Atom defines the concept of a Service Document to represent the set of available collections. OData uses Service Documents to describe the set of entity sets available through the service.

13.1. The app:service element

The atom ServiceDocument is represented by the app:service element. The app:service element contains one or more app:workspaces, which represents a set of collections.

13.1.1. Entity Container as an app:workspace element

OData represents entity containers as app:workspace elements. An app:workspace element contains zero or more app:collections.

13.1.2. Entity Sets as an app:collection element

OData describes available collections of entities as app:collection elements.

The app:collection element MUST contain an href attribute which represents a URL that can be used to retrieve the members of the entity set.

13.1.3. Entity Set Name as an atom:title element

The atom:title element within the app:collection SHOULD contain the name of the entity set.

14. Links

Links represent the relationships between an entity and related entity(s).

The link(s) available from a particular entity for a particular relationship can be retrieved from the service as a colleciton of URIs within a data:links element.

14.1. Collection of Links as a data:links Element

A data:link element represents the set of references from one entity to all related entities according to a particular relationship.

The reference for each related entity is represented as a data:uri element that appears as a direct child of the data:links element.

For example, a query for links to Products within the Category with ID=1:

http://services.odata.org/OData/OData.svc/Categories(1)$links/Products

might return the following XML response:

<links xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices"> 
    <uri>http://services.odata.org/OData/OData.svc/Products(1)</uri> 
    <uri>http://services.odata.org/OData/OData.svc/Products(2)</uri> 
    <uri>http://services.odata.org/OData/OData.svc/Products(3)</uri> 
    <uri>http://services.odata.org/OData/OData.svc/Products(4)</uri> 
    <uri>http://services.odata.org/OData/OData.svc/Products(5)</uri> 
    <uri>http://services.odata.org/OData/OData.svc/Products(6)</uri> 
</links>

14.2. Link as a data:uri Element

Each related entity is represented as a data:uri element, which appears as a direct child of a data:link element.

The content of the data:uri element is the Canonical URL for the related entity.

15. Errors as XML

In the case of an error being generated in response to a request specifying an Accept header of application/xml or application/atom+xml, or that does not specify an Accept header, the service MUST respond with with an error formatted as XML.

When formatting error responses as XML, servers SHOULD include a Content-Type response header with the value "application/xml".

15.1 The metadata:error Element

Errors formatted as XML have a root metadata:error element. The metadata:error element MUST have two child elements: metadata:code and metadata:message.

In addition, errors may be annotated using custom annotations

For example:

<error xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <code>BDRQST</code>
  <message xml:lang="en-US">Bad Request - Error in query syntax.</message>
</error>

15.2 The metadata:code Element

The metadata:error element MUST contain a metadata:code element specifying a service-defined string. This value MAY be used to provide a more specific substatus to the returned HTTP response code.

15.3 The metadata:message Element

The metadata:error element MUST contain a metadata:message element specifying a human readable message describing the error.

15.3.1. The xml:lang Attribute

The metadata:message element MAY contain an xml:lang attribute to specify the language of the error message.

15.4 The metadata:innererror Element

The metadata:error element MAY contain a metadata:innererror element containing service specific debugging information that might assist a service implementer in determining the cause of an error.

The metadata:innererror element SHOULD only be used in development environments in order to guard against potential security concerns around information disclosure.

16. Extensibility

Implementations MAY add custom content anywhere allowed by RFC4287, Section 6, “Extending Atom”. However, custom elements and attributes MUST NOT be defined in the OData Data Namespace nor the OData Metadata Namespace, and SHOULD not be required to be understood by the receiving party in order to correctly interpret the rest of the payload.

Introduction

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 <atom:elementName> 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).

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 http://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.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?> 
<service xml:base="http://services.odata.org/OData/OData.svc/" 
         xmlns:atom="http://www.w3.org/2005/Atom" 
         xmlns:app="http://www.w3.org/2007/app" 
         xmlns="http://www.w3.org/2007/app">
  <workspace>
    <atom:title>Default</atom:title> 
    <collection href="Products">
      <atom:title>Products</atom:title> 
    </collection>
    <collection href="Categories">
      <atom:title>Categories</atom:title> 
    </collection>
    <collection href="Suppliers">
      <atom:title>Suppliers</atom:title> 
    </collection>
  </workspace>
</service>

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 http://services.odata.org/OData/OData.svc/Categories, is represented as shown below. The format of <atom:entry> 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"?>
<feed xml:base=http://services.odata.org/OData/OData.svc/
     xmlns:d=http://schemas.microsoft.com/ado/2007/08/dataservices
     xmlns:m=http://schemas.microsoft.com/ado/2007/08/dataservices/metadata
     xmlns="http://www.w3.org/2005/Atom">
  <title type="text">Categories</title>
  <id>http://services.odata.org/OData/OData.svc/Categories</id>
  <updated>2010-03-10T08:38:14Z</updated>
  <link rel="self" title="Categories" href="Categories" />
  <entry>
    <id>http://services.odata.org/OData/OData.svc/Categories(0)</id>
    <title type="text">Food</title>
    <updated>2010-03-10T08:38:14Z</updated>
    <author>
      <name />
    </author>
    <link rel="edit" title="Category" href="Categories(0)" />
    <link 
        rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products"
        type="application/atom+xml;type=feed"
        title="Products" href="Categories(0)/Products" />
    <category term="ODataDemo.Category"
        scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <content type="application/xml">
      <m:properties>
        <d:ID m: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 <m:count> 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 <entry> 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 <link rel="next" href="…"> 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: 

<feed xml:base="http://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/metadata
        xmlns="http://www.w3.org/2005/Atom">
  <title type="text">Customers</title> 
  <id>http://services.odata.org/Northwind/Northwind.svc/Customers</id> 
  <updated>2010-03-10T09:34:11Z</updated> 
  <link rel="self" title="Customers" href="Customers" /> 
  <m:count>91</m:count> 
  <entry>
    <id>http://services.odata.org/Northwind/Northwind.svc/Customers('ALFKI')</id> 
    <title type="text" /> 
    <updated>2010-03-10T09:34:11Z</updated> 
    <author>
      <name /> 
    </author>
    <link rel="edit" title="Customer" href="Customers('ALFKI')" /> 
    <link 
        rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Orders"
        type="application/atom+xml;type=feed"
        title="Orders" href="Customers('ALFKI')/Orders" />
    <link 
  rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/CustomerDemographics"
  type="application/atom+xml;type=feed"
  title="CustomerDemographics" href="Customers('ALFKI')/CustomerDemographics" /> 
    <category term="NorthwindModel.Customer"
        scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> 
    <content type="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:Region m: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 -->
  <link rel="next" 
      href="http://services.odata.org/Northwind/Northwind.svc/Customers?
    $inlinecount=allpages&$skiptoken='ERNSH'" /> 
</feed>

2.4. Representing Entries

In OData, Entries are represented as Atom <atom:entry> elements with all the Properties of the Entry represented as elements within the <m:properties> element which is a direct child of the <atom:content> 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 <atom:link rel= 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.

<atom:id>

• As per [RFC4287], contains a URI which uniquely identifies the Entry

<atom:category scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme">

• 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 <atom:entry> element. An <atom:Entry> 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.

<atom:link rel="self" href=".." >

• 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] .

<atom:link rel="edit" href=" .. " >

• 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 http://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.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?> 
<entry xml:base="http://services.odata.org/OData/OData.svc/" 
       xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" 
       xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
       xmlns="http://www.w3.org/2005/Atom">
  <id>http://services.odata.org/OData/OData.svc/Categories(0)</id> 
  <title type="text">Food</title> 
  <updated>2010-03-10T10:43:51Z</updated> 
  <author>
    <name /> 
  </author>
  <link rel="edit" title="Category" href="Categories(0)" /> 
  <link 
      rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products"
      type="application/atom+xml;type=feed" title="Products" 
      href="Categories(0)/Products" /> 
  <category term="ODataDemo.Category" 
      scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> 
  <content type="application/xml"> 
    <m:properties> 
      <d:ID m:type="Edm.Int32">0</d:ID>
      <d:Name>Food</d:Name> 
    </m:properties> 
  </content>
</entry>

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 <link rel="   http://schemas.microsoft.com/ado/2007/08/dataservices/related/[NavigationPropertyName]" href="..." /> 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 <m:inline> element as an <atom:feed> or <atom:entry> respectively. For example, a single Category Entry with its related Product Entries serialized inline is represented as shown in the example below.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base=http://services.odata.org/OData/OData.svc/"
   xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
   xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
   xmlns="http://www.w3.org/2005/Atom">
  <id>http://services.odata.org/OData/OData.svc/Categories(0)</id>
  <title type="text">Food</title>
  <updated>2010-03-11T06:40:04Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Category" href="Categories(0)" />
  <link 
      rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products" 
      type="application/atom+xml;type=feed" 
       title="Products" href="Categories(0)/Products">
    <m:inline>
      <feed>
        <title type="text">Products</title>
        <id>http://services.odata.org/OData/OData.svc/Categories(0)/Products</id>
        <updated>2010-03-11T06:40:04Z</updated>
        <link rel="self" title="Products" href="Categories(0)/Products" />
        <entry>
          <id>http://services.odata.org/OData/OData.svc/Products(0)</id>
          <title type="text">Bread</title>
          <summary type="text">Whole grain bread</summary>
          <updated>2010-03-11T06:40:04Z</updated>
          <author>
            <name />
          </author>
          <link rel="edit" title="Product" href="Products(0)" />
          <link 
              rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Category" 
              type="application/atom+xml;type=entry" 
              title="Category" href="Products(0)/Category" />
          <link 
              rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Supplier" 
              type="application/atom+xml;type=entry" 
              title="Supplier" href="Products(0)/Supplier" />
          <category term="ODataDemo.Product" 
              scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
          <content type="application/xml">
            <m:properties>
              <d:ID m:type="Edm.Int32">0</d:ID>
              <d:ReleaseDate m:type="Edm.DateTime">1992-01-01T00:00:00</d:ReleaseDate>
              <d:DiscontinuedDate m:type="Edm.DateTime" m:null="true" />
              <d:Rating m:type="Edm.Int32">4</d:Rating>
              <d:Price m:type="Edm.Decimal">2.5</d:Price>
            </m:properties>
          </content>
        </entry>
      </feed>
    </m:inline>
  </link>
  <category term="ODataDemo.Category"
     scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:ID m:type="Edm.Int32">0</d:ID>
      <d:Name>Food</d:Name>
    </m:properties>
  </content>
</entry>

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 <m:properties> element becomes a child of the <atom:entry> element. The <m:properties> element is moved out from under the <atom:content> 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 <atom:entry>:

• <link rel="edit-media" href="{MediaResourceUri}">
  • 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.
• <atom:content src="{MediaResourceUri}" type="{MimeType}">
  • 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 <atom:entry> 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 <atom:entry> 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 <atom:entry> 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.

For example, the sample Service Metadata Document at http://services.odata.org/OData/OData.svc/$metadata states the Name Property of the Category Entry is represented as the value of the <atom:title> element. Since FC_KeepInContent is equals true for this mapping the value is duplicated within the <m:properties> element.

Snippet from Service Metadata Document 
<EntityType Name="Category">
  <Key>
    <PropertyRef Name="ID" />
  </Key>
  <Property Name="ID" Type="Edm.Int32" Nullable="false" />
  <Property Name="Name" Type="Edm.String" 
            Nullable="true" 
            m:FC_TargetPath="SyndicationTitle" m:FC_ContentKind="text" 
            m:FC_KeepInContent="true" />
  <NavigationProperty Name="Products" 
                      Relationship="ODataDemo.Product_Category_Category_Products" 
                      FromRole="Category_Products" ToRole="Product_Category" />
</EntityType>

Category representation in Atom 
(see http://services.odata.org/OData/OData.svc/Categories(0) )

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/"
    xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
    xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
    xmlns="http://www.w3.org/2005/Atom">
  <id>http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/Categories(0)</id>
  <title type="text">Food</title>
  <updated>2010-03-11T22:28:51Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Category" href="Categories(0)" />
  <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products" 
      type="application/atom+xml;type=feed" 
      title="Products" 
      href="Categories(0)/Products" />
  <category term="ODataDemo.Category" 
      scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <content type="application/xml">
    <m:properties>
      <d:ID m:type="Edm.Int32">0</d:ID>
      <d:Name>Food</d:Name>
    </m:properties>
  </content>
</entry>

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 <atom:title> is still possible, however the placement of the annotation changes to be on the <EntityType> element in the Service Metadata Document as shown in the following listing.

<EntityType Name="Category" m:FC_TargetPath="SyndicationTitle" m:FC_SourcePath="Name"
  m:FC_ContentKind="text" m:FC_KeepInContent="true"
                            BaseType:"Sample.BaseCategory">
  <Key>
    <PropertyRef Name="ID" />
  </Key>
  <Property Name="ID" Type="Edm.Int32" Nullable="false" />
  <NavigationProperty Name="Products" 
                      Relationship="ODataDemo.Product_Category_Category_Products" 
                      FromRole="Category_Products" ToRole="Product_Category" />
</EntityType>

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 <c:Road> element.

Snippet from Service Metadata Document 
<EntityType Name="Supplier">
  <Key>
    <PropertyRef Name="ID" />
    </Key>
    <Property Name="ID" Type="Edm.Int32" Nullable="false" />
    <Property Name="Name" Type="Edm.String" Nullable="true"/> 

    <Property Name="Address" Type="ODataDemo.Address" Nullable="false" 
              m:FC_TargetPath="Road" m:FC_SourcePath="Street" m:FC_KeepInContent="true"
                m:FC_NsUri="http://customUri" m:FC_NsPrefix="c"/> 

    <Property Name="Concurrency" Type="Edm.Int32" Nullable="false" ConcurrencyMode="Fixed" />
    <NavigationProperty Name="Products" 
                        Relationship="ODataDemo.Product_Supplier_Supplier_Products" 
                        FromRole="Supplier_Products" 
                        ToRole="Product_Supplier" />
</EntityType>

<ComplexType Name="Address">
  <Property Name="Street" Type="Edm.String" Nullable="true" />
  <Property Name="City" Type="Edm.String" Nullable="true" />
  <Property Name="State" Type="Edm.String" Nullable="true" />
  <Property Name="ZipCode" Type="Edm.String" Nullable="true" />
  <Property Name="Country" Type="Edm.String" Nullable="true" />
</ComplexType>

Supplier representation in Atom
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/"
    xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
    xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
    m:etag="W/"0"" xmlns="http://www.w3.org/2005/Atom" Xmlns:c="http://customUri">
  <id>http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/Suppliers(0)</id>
  <title type="text">Exotic Liquids</title>
  <updated>2010-03-11T22:47:21Z</updated>
  <author>
    <name />
  </author>
  <link rel="edit" title="Supplier" href="Suppliers(0)" />
  <link 
      rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products"
      type="application/atom+xml;type=feed" title="Products"
      href="Suppliers(0)/Products" />
  <category term="ODataDemo.Supplier"
      scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <c:Road>NE 228th</c:Road>
  <content type="application/xml">
    <m:properties>
      <d:ID m:type="Edm.Int32">0</d:ID>
      <d:Name>Exotic Liquids</d:Name>
      <d:Concurrency m:type="Edm.Int32">0</d:Concurrency>
      <d:Address m:type="ODataDemo.Address">
        <d:Street>NE 228th</d:Street>
        <d:City>Sammamish</d:City>
        <d:State>WA</d:State>
        <d:ZipCode>98074</d:ZipCode>
        <d:Country>USA</d:Country>
      </d:Address>
    </m:properties>
  </content>
</entry>

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 <m:properties> element (see Representing Entities) with the name equal to the element equal to the property and value of the element set to the primitive type value formatted as described by the table in the Primitive Types section above.

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.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Name xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">Bread</Name>

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.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Address p1:type="ODataDemo.Address" 
         xmlns:p1="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"  
         xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">
  <Street>NE 228th</Street>
  <City>Sammamish</City>
  <State>WA</State>
  <ZipCode>98074</ZipCode>
  <Country>USA</Country>
</Address>

3.1.3. Representing the Raw value of a Property

OData services may support addressing the “raw†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 “raw†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.

HTTP/1.1 200 OK
DataServiceVersion: 1.0;
Content-Type: text/plain;charset=utf-8

Food

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 <d:uri> element with the value of the element set to the URI that identifies the Link. A collection of links is represented as a <d:links> element with zero or more child <d:uri> elements, where each <d:uri> element represents a Link.

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:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<uri xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">

http://services.odata.org/OData/OData.svc/Suppliers(1)

</uri>

For example, a link with multiplicity greater than 1 (e.g. Supplier is related to many products) would be represented in a response as:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<links xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices">
  <uri>http://services.odata.org/OData/OData.svc/Products(1)</uri>
  <uri>http://services.odata.org/OData/OData.svc/Products(2)</uri>
  <uri>http://services.odata.org/OData/OData.svc/Products(3)</uri>
  <uri>http://services.odata.org/OData/OData.svc/Products(4)</uri>
  <uri>http://services.odata.org/OData/OData.svc/Products(5)</uri>
  <uri>http://services.odata.org/OData/OData.svc/Products(6)</uri>
</links>

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 <m:element> elements which are children of the root element. The name of the root element should be equal to the name of the Service Operation that was invoked. For example a response payload from a "GetInts" Service Operation that returns a collection of integer values would be formatted as shown in the following listing.

<GetInts xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <element>0</element>
  <element>1</element>
  <element>2</element>
</GetInts>

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 <m:element> element for each Complex Type value in the collection returned from the Service Operation. The Properties of each Complex Type are represented as per the Representing Complex Type Properties section. Finally, each <m:element> element should include an m:type attribute that lists the namespace qualified name of the Complex Type. For example, response payload from a "GetAddresses" Service Operation that returns a collection of Address Complex Type values would be represented as show in the following listing.

<GetAddressses xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata">
  <element type="SampleNamespace.Address">
    <street>123 Contoso Ave</street>
    <city>London</street>
  </element>
  <!-- additional Addresses returned go here -->
</GetAddresses>