Atom Format (OData Version 2.0)

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

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<service xml:base="https://services.odata.org/OData/OData.svc/"
         xmlns:atom="https://www.w3.org/2005/Atom"
         xmlns:app="https://www.w3.org/2007/app"
         xmlns="https://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 https://services.odata.org/OData/OData.svc/Categories, is represented as shown below. The format of elements within a feed is described in the Representing Entries section.

Note: The "m" and "d" prefixes represent the OData metadata and data namespaces. It is likely the next version of OData will generalize the namespace URI to use an odata.org based URI.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<feed xml:base=https://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="https://www.w3.org/2005/Atom">
    <title type="text">Categories</title>
    <id>https://services.odata.org/OData/OData.svc/Categories</id>
    <updated>2010-03-10T08:38:14Z</updated>
    <link rel="self" title="Categories" href="Categories" />
    <entry>
        <id>https://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 element with the value of the element being the total number of Entries in the Collection. See the $inlinecount section of the [OData-URI] document for a description of how the count value is calculated.

In response payloads only, if the server does not include an element for every Entry in the Collection identified by the request URI (typically for resource conservation reasons), then the returned feed represents a partial listing as defined in AtomPub [RFC5023] section 10.1. In this case, the response includes a element to indicate the feed is a partial listing and to provide the URI of the next partial list feed so a client can easily continue obtaining additional entries. Version Note: Partial lists of Entries are supported in OData V2.0 only. For more information on interacting with partial listings, see Retrieving feeds, entries and service documents in the [OData-Operations] document.

<feed xml:base="https://services.odata.org/Northwind/Northwind.svc/"
      xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
      xmlns:m=http://schemas.microsoft.com/ado/2007/08/dataservices/metadata
      xmlns="https://www.w3.org/2005/Atom">
    <title type="text">Customers</title>
    <id>https://services.odata.org/Northwind/Northwind.svc/Customers</id>
    <updated>2010-03-10T09:34:11Z</updated>
    <link rel="self" title="Customers" href="Customers" />
    <strong><m:count>91</m:count></strong>
    <entry>
        <id>https://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 -->
    <strong>
        <link rel="next"
              href="https://services.odata.org/Northwind/Northwind.svc/Customers?
    $inlinecount=allpages&amp;$skiptoken='ERNSH'" />
    </strong>
</feed>

2.4. Representing Entries

In OData, Entries are represented as Atom elements with all the Properties of the Entry represented as elements within the element which is a direct child of the element. When using an OData v2 server, clients may indicate that they want a subset of the properties by using the Select System Query Option in the request.

If the Entry being represented links to other Entries via Navigation Properties (e.g. a Product is related to a Category), then the Links are represented as http://schemas.microsoft.com/ado/2007/08/dataservices/related/[NavigationPropertyName] href=â€â€¦"/> elements â€" one for each Navigation Property of the Entry.

Metadata describing the Entry being represented can be specified using additional Atom-defined and OData-defined elements/attributes as defined by the following list.

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

• This element may be present with a term attribute whose value indicates the Entity Type in the data model of the OData service that describes the Entry represented by the parent element. An must contain at most one such category element with the specified scheme.
• To ensure type fidelity across of Entries sent from server to client (and vice versa), this element must be included if the Entry is part of a type hierarchy and is not the base type in the hierarchy.
• 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] .

m:etag attribute

• An attribute in the OData Metadata Namespace whose value is the concurrency token associated with the Entry. The value is formatted as required by the ETag header in [RFC2616].
• This attribute should be present in a response from an OData service when returning a feed (i.e. multiple Entries in a single HTTP response), otherwise the HTTP ETag response header should be used to communicate the concurrency token of the resource returned to a client.

For example, as shown in the following listing, the Category Entry identified by the URI https://services.odata.org/OData/OData.svc/Categories(0), has two primitive properties (ID & Name) and one Navigation Property named “Productsâ€, which identifies a feed of Product Entries related to the Category.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<entry xml:base="https://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="https://www.w3.org/2005/Atom">
    <id>https://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)" />
    <strong>
        <link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products"
              type="application/atom+xml;type=feed" title="Products"
              href="Categories(0)/Products" />
    </strong>
    <category term="ODataDemo.Category"
              scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <strong>
        <content type="application/xml">
            <m:properties>
                <d:ID m:type="Edm.Int32">0</d:ID>
                <d:Name>Food</d:Name>
            </m:properties>
        </content>
    </strong>
</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 element to indicate the service deferred representing the related Entries. If needed, a client can then use the URI in the href attribute in a subsequent retrieve request to obtain the related Entries.

2.4.2. Inline Representation of Associated Entries

As described in the $expand System Query Option section of the [OData-URI] document, a request URI may include the $expand query option to explicitly request that a linked to Entry or collection of Entries be serialized inline, rather than deferred.

In this case the related Entry or collection of Entries is represented as the child element of an element as an or respectively. For example, a single Category Entry with its related Product Entries serialized inline is represented as shown in the example below.

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<entry xml:base=https://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="https://www.w3.org/2005/Atom">
    <id>https://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" />
    <strong><m:inline></m:inline></strong>
    <feed>
        <title type="text">Products</title>
        <id>https://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>https://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>
    <strong></m:inline></strong>
    </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 element becomes a child of the element. The element is moved out from under the element because in the case of an MLE, the content describes the MR.

This additional MR-specific metadata is represented by the following constructs in the :

• • As per [RFC5023] section 9.6, this element indicates the URI a client should use to update or delete the Media Resource, as described in [OData-Operations] .
  • If the ETag of the Media Resource (MR) is independent from that of the Media Link Entry (MLE), then this element should include an m:etag attribute with value equal to the concurrency token of the MR.
• • For MLE's, this element describes the associated MR. The value of the src attribute is the URI a client should use to retrieve the Media Resource, as described in [OData-Operations]. Note: this allows a Media Resource to have independent links for editing and retrieval.
  • The value of the type attribute is the mime type of the MR.

2.4.4. Customizing the Representation of an Entry

Services may wish to have more flexibility over how Entries are represented within an element. For example, a service may want to enable the value of a property of an Entry be represented as the value of one of the standard Atom elements (Title, Summary, etc) or as the value of a custom element within an Entry. OData supports services that need this kind of control over the Atom representations of an Entry.

In general a service may choose to deviate from the conventions defined in Representing Entries section above and represent the value of a Property of an Entry as the value of a standard Atom element (Title, Summary, etc) or as the value of an element in a custom namespace. When a service does this form of customization it breaks the shared assumption between client and server regarding how Entries are encoded within an element. OData services that deviate from the prescribed encoding should expose a Service Metadata Document that include Feed Customization annotations which allow a client to discover how the server chose to encode a given Entry within the element. The remainder of this section describes the set of Feed Customization annotations that may be used.

The following table lists all the Feed Customization annotations defined in OData.

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 element. Since FC_KeepInContent is equals true for this mapping the value is duplicated within the element.

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

<strong>Category representation in Atom</strong>
(see https://services.odata.org/OData/OData.svc/Categories(0) )

<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
<entry xml:base="https://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="https://www.w3.org/2005/Atom">
    <id>https://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/Categories(0)</id>
    <strong><title type="text">Food</title></strong>
    <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>
            <strong><d:Name>Food</d:Name></strong>
        </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 is still possible, however the placement of the annotation changes to be on the element in the Service Metadata Document as shown in the following listing.

<EntityType Name="Category" <strong>m:FC_TargetPath="SyndicationTitle" m:FC_SourcePath="Name"
  m:FC_ContentKind="text" m:FC_KeepInContent="true"</strong>
                            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 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"
              <strong>m:FC_TargetPath="Road" m:FC_SourcePath="Street" m:FC_KeepInContent="true"
                m:FC_NsUri="http://customUri" m:FC_NsPrefix="c"/></strong>

    <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="https://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""=0"" xmlns="https://www.w3.org/2005/Atom" Xmlns:c="http://customUri">
    <id>https://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" />
    <strong><c:Road>NE 228th</c:Road></strong>
    <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 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 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.

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 element with the value of the element set to the URI that identifies the Link. A collection of links is represented as a element with zero or more child elements, where each 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">
    https://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>https://services.odata.org/OData/OData.svc/Products(1)</uri>
    <uri>https://services.odata.org/OData/OData.svc/Products(2)</uri>
    <uri>https://services.odata.org/OData/OData.svc/Products(3)</uri>
    <uri>https://services.odata.org/OData/OData.svc/Products(4)</uri>
    <uri>https://services.odata.org/OData/OData.svc/Products(5)</uri>
    <uri>https://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 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 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 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>
        </city>
    </element>
    <!-- additional Addresses returned go here -->
    </GetAddresses>