OData Version 4.0 is the current recommended version of OData. OData V4 has been standardized by OASIS and has many features not included in OData Version 2.0.

Go to OData Version 4.0

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

Primitive Type Serialization Format in XML Documents
Edm.Binary Base64 encoded value of an EDM.Binary value. See [RFC3548] .
Edm.Boolean true | false
Edm.Byte Same as the literal form in [OData:Core], except without the surrounding
Edm.DateTime Same as the literal form in [OData:Core], except without the surrounding datetime'' syntax
Edm.Decimal Same as the literal form in [OData:Core], except without the trailing "m"
Edm.Double Same as the literal form in [OData:Core]
Edm.Guid Same as the literal form in [OData:Core], except without the surrounding guid'' syntax
Edm.Int16 Same as the literal form in [OData:Core]
Edm.Int32 Same as the literal form in [OData:Core]
Edm.Int64 Same as the literal form in [OData:Core]
Edm.SByte Same as the literal form in [OData:Core]
Edm.Single Same as the literal form in [OData:Core], except without the trailing "f"
Edm.String Same as the literal form in [OData:Core], except without surrounding double quotes
Edm.Time Same as the literal form in [OData:Core], except without the surrounding time'' syntax
Edm.DateTimeOffset Same as the literal form in [OData:Core], except without the surrounding datetimeoffset'' syntax

2.2. Service Documents

As described in [OData-Core], if a service exposes several Collections, then to aid discovery of those Collections by clients it is useful for the service to expose a Service Document which lists the available Collections. Service Documents are described in AtomPub [RFC5023], section 15.

For example, the URI 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 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 element with the value of the element being the total number of Entries in the Collection. See the $inlinecount section of the [OData-URI] document for a description of how the count value is calculated.

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

OData V2:
<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" /> 
  <strong><m:count>91</m:count></strong> 
  <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 -->
  <strong><link rel="next" 
      href="http://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.

m:etag attribute

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)" /> 
  <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=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">
    <strong><m:inline></strong>
      <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>
    <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 :

2.4.4. Customizing the Representation of an Entry

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

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

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

Feed Customization Annotation Description
FC_SourcePath The name of the Property on an Entry which this feed mapping rule applies to.The format of this parameter is a path expression where property names are separated by a / character. For example for a Person Entry with an integer Property Age and an Address Complex Type Property, the following are legal values for this property:

- Age

- Address/Street

The following are invalid values for this property:

- Foo (not a defined property)

- Address (doesn't identify a primitive property)

- Address/Street/ (cannot end with a /)

- Empty string or null

- /Address/Street (cannot start with a /)

FC_TargetPath The name of the element to map the property identified by the FC_SourcePath annotation to. If no FC_SourcePath annotation is specified, then this annotation must be on a element in the Service Metadata Document which itself identifies the source Property.The format of this annotation is a path expression where nested elements are separated by a / and attributes are specified by a @ symbol.

For example, to map to a property value to a custom XML element or attribute:

To map the source Property to a custom element which is a direct child of the element use:

- FC_TargetPath="Category"

To map the source Property to an attribute named Term on a custom element which is a direct child of the element:

- FC_TargetPath="Category/@Term"

To map the source Property to a child element of the custom element named , where is a direct child of the element:

- FC_TargetPath="Category/Foo"

This annotation also supports mapping to Atom-defined elements. This following list describes the values used to map to Atom-defined elements:

Format: value : mapped to atom element

  • "SyndicationAuthorEmail" :
  • "SyndicationAuthorName" :
  • "SyndicationAuthorUri" :
  • "SyndicationPublished" :
  • "SyndicationRights" :
  • "SyndicationSummary" :
  • "SyndicationTitle" : </li> </ul> <p><a id="_GoBack" name="_GoBack"></a></p> <p>Note: This annotation does not support mapping to multiple instances of an element, so two overlapping path definitions imply the same element instances. For example: the target path values <strong>a/b/c</strong> and <strong>a/d/f</strong> imply the following XML structure: <a><b> <c/></b><d><f/></d></td> </tr> <tr> <td valign="top">FC_ContentKind</td> <td>The mime type of the source Property</td> </tr> <tr> <td valign="top">FC_NsPrefix</td> <td>When the source Property is being mapped to an element that is not in the Atom namespace, the value of this annotation specifies the namespace prefix to use the Atom document for target element.</td> </tr> <tr> <td valign="top">FC_NsUri</td> <td>When a property is being mapped to an element that is not in the Atom namespace, this annotation is used to specify the namespace for the target element. The FC_NSPrefix annotation specifies the namespace prefix for the namespace specified by this annotation.</td> </tr> <tr> <td valign="top">FC_KeepInContent</td> <td>The value of this property is true if the property being mapped should appear both in its “mapped to†location as well as within the content section of the <entry>.If the value of this property is false, then the property being mapped should only appear in its new “mapped to†location in the <entry> and NOT also in the content section. This value (false) is only supported in OData v2.0 and requires that any response formatted in this way return a DataServiceVersion:2.0 response header.</td> </tr> </tbody> </table> </div> <p>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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><strong></span>Snippet from Service Metadata Document<span class="nt"></strong></span> <span class="nt"><EntityType</span> <span class="na">Name=</span><span class="s">"Category"</span><span class="nt">></span> <span class="nt"><Key></span> <span class="nt"><PropertyRef</span> <span class="na">Name=</span><span class="s">"ID"</span> <span class="nt">/></span> <span class="nt"></Key></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"ID"</span> <span class="na">Type=</span><span class="s">"Edm.Int32"</span> <span class="na">Nullable=</span><span class="s">"false"</span> <span class="nt">/></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"Name"</span> <span class="na">Type=</span><span class="s">"Edm.String"</span> <span class="na">Nullable=</span><span class="s">"true"</span> <span class="err"><strong</span><span class="nt">></span>m:FC_TargetPath="SyndicationTitle" m:FC_ContentKind="text" m:FC_KeepInContent="true"<span class="nt"></strong></span> /> <span class="nt"><NavigationProperty</span> <span class="na">Name=</span><span class="s">"Products"</span> <span class="na">Relationship=</span><span class="s">"ODataDemo.Product_Category_Category_Products"</span> <span class="na">FromRole=</span><span class="s">"Category_Products"</span> <span class="na">ToRole=</span><span class="s">"Product_Category"</span> <span class="nt">/></span> <span class="nt"></EntityType></span> <span class="nt"><strong></span>Category representation in Atom<span class="nt"></strong></span> (see http://services.odata.org/OData/OData.svc/Categories(0) ) <span class="cp"><?xml version="1.0" encoding="utf-8" standalone="yes"?></span> <span class="nt"><entry</span> <span class="na">xml:base=</span><span class="s">"http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/"</span> <span class="na">xmlns:d=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices"</span> <span class="na">xmlns:m=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"</span> <span class="na">xmlns=</span><span class="s">"http://www.w3.org/2005/Atom"</span><span class="nt">></span> <span class="nt"><id></span>http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/Categories(0)<span class="nt"></id></span> <span class="nt"><strong><title</span> <span class="na">type=</span><span class="s">"text"</span><span class="nt">></span>Food<span class="nt"></title></strong></span> <span class="nt"><updated></span>2010-03-11T22:28:51Z<span class="nt"></updated></span> <span class="nt"><author></span> <span class="nt"><name</span> <span class="nt">/></span> <span class="nt"></author></span> <span class="nt"><link</span> <span class="na">rel=</span><span class="s">"edit"</span> <span class="na">title=</span><span class="s">"Category"</span> <span class="na">href=</span><span class="s">"Categories(0)"</span> <span class="nt">/></span> <span class="nt"><link</span> <span class="na">rel=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products"</span> <span class="na">type=</span><span class="s">"application/atom+xml;type=feed"</span> <span class="na">title=</span><span class="s">"Products"</span> <span class="na">href=</span><span class="s">"Categories(0)/Products"</span> <span class="nt">/></span> <span class="nt"><category</span> <span class="na">term=</span><span class="s">"ODataDemo.Category"</span> <span class="na">scheme=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"</span> <span class="nt">/></span> <span class="nt"><content</span> <span class="na">type=</span><span class="s">"application/xml"</span><span class="nt">></span> <span class="nt"><m:properties></span> <span class="nt"><d:ID</span> <span class="na">m:type=</span><span class="s">"Edm.Int32"</span><span class="nt">></span>0<span class="nt"></d:ID></span> <span class="nt"><strong><d:Name></span>Food<span class="nt"></d:Name></strong></span> <span class="nt"></m:properties></span> <span class="nt"></content></span> <span class="nt"></entry></span></code></pre></figure> <p>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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><EntityType</span> <span class="na">Name=</span><span class="s">"Category"</span> <span class="err"><strong</span><span class="nt">></span>m:FC_TargetPath="SyndicationTitle" m:FC_SourcePath="Name" m:FC_ContentKind="text" m:FC_KeepInContent="true"<span class="nt"></strong></span> BaseType:"Sample.BaseCategory"> <span class="nt"><Key></span> <span class="nt"><PropertyRef</span> <span class="na">Name=</span><span class="s">"ID"</span> <span class="nt">/></span> <span class="nt"></Key></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"ID"</span> <span class="na">Type=</span><span class="s">"Edm.Int32"</span> <span class="na">Nullable=</span><span class="s">"false"</span> <span class="nt">/></span> <span class="nt"><NavigationProperty</span> <span class="na">Name=</span><span class="s">"Products"</span> <span class="na">Relationship=</span><span class="s">"ODataDemo.Product_Category_Category_Products"</span> <span class="na">FromRole=</span><span class="s">"Category_Products"</span> <span class="na">ToRole=</span><span class="s">"Product_Category"</span> <span class="nt">/></span> <span class="nt"></EntityType></span></code></pre></figure> <p>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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml">Snippet from Service Metadata Document <span class="nt"><EntityType</span> <span class="na">Name=</span><span class="s">"Supplier"</span><span class="nt">></span> <span class="nt"><Key></span> <span class="nt"><PropertyRef</span> <span class="na">Name=</span><span class="s">"ID"</span> <span class="nt">/></span> <span class="nt"></Key></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"ID"</span> <span class="na">Type=</span><span class="s">"Edm.Int32"</span> <span class="na">Nullable=</span><span class="s">"false"</span> <span class="nt">/></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"Name"</span> <span class="na">Type=</span><span class="s">"Edm.String"</span> <span class="na">Nullable=</span><span class="s">"true"</span><span class="nt">/></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"Address"</span> <span class="na">Type=</span><span class="s">"ODataDemo.Address"</span> <span class="na">Nullable=</span><span class="s">"false"</span> <span class="err"><strong</span><span class="nt">></span>m:FC_TargetPath="Road" m:FC_SourcePath="Street" m:FC_KeepInContent="true" m:FC_NsUri="http://customUri" m:FC_NsPrefix="c"/><span class="nt"></strong></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"Concurrency"</span> <span class="na">Type=</span><span class="s">"Edm.Int32"</span> <span class="na">Nullable=</span><span class="s">"false"</span> <span class="na">ConcurrencyMode=</span><span class="s">"Fixed"</span> <span class="nt">/></span> <span class="nt"><NavigationProperty</span> <span class="na">Name=</span><span class="s">"Products"</span> <span class="na">Relationship=</span><span class="s">"ODataDemo.Product_Supplier_Supplier_Products"</span> <span class="na">FromRole=</span><span class="s">"Supplier_Products"</span> <span class="na">ToRole=</span><span class="s">"Product_Supplier"</span> <span class="nt">/></span> <span class="nt"></EntityType></span> <span class="nt"><ComplexType</span> <span class="na">Name=</span><span class="s">"Address"</span><span class="nt">></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"Street"</span> <span class="na">Type=</span><span class="s">"Edm.String"</span> <span class="na">Nullable=</span><span class="s">"true"</span> <span class="nt">/></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"City"</span> <span class="na">Type=</span><span class="s">"Edm.String"</span> <span class="na">Nullable=</span><span class="s">"true"</span> <span class="nt">/></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"State"</span> <span class="na">Type=</span><span class="s">"Edm.String"</span> <span class="na">Nullable=</span><span class="s">"true"</span> <span class="nt">/></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"ZipCode"</span> <span class="na">Type=</span><span class="s">"Edm.String"</span> <span class="na">Nullable=</span><span class="s">"true"</span> <span class="nt">/></span> <span class="nt"><Property</span> <span class="na">Name=</span><span class="s">"Country"</span> <span class="na">Type=</span><span class="s">"Edm.String"</span> <span class="na">Nullable=</span><span class="s">"true"</span> <span class="nt">/></span> <span class="nt"></ComplexType></span> Supplier representation in Atom <span class="cp"><?xml version="1.0" encoding="utf-8" standalone="yes"?></span> <span class="nt"><entry</span> <span class="na">xml:base=</span><span class="s">"http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/"</span> <span class="na">xmlns:d=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices"</span> <span class="na">xmlns:m=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"</span> <span class="na">m:etag=</span><span class="s">"W/"</span><span class="err">0""</span> <span class="na">xmlns=</span><span class="s">"http://www.w3.org/2005/Atom"</span> <span class="na">Xmlns:c=</span><span class="s">"http://customUri"</span><span class="nt">></span> <span class="nt"><id></span>http://services.odata.org/(S(S_ODATA_RO))/OData/OData.svc/Suppliers(0)<span class="nt"></id></span> <span class="nt"><title</span> <span class="na">type=</span><span class="s">"text"</span><span class="nt">></span>Exotic Liquids<span class="nt"></title></span> <span class="nt"><updated></span>2010-03-11T22:47:21Z<span class="nt"></updated></span> <span class="nt"><author></span> <span class="nt"><name</span> <span class="nt">/></span> <span class="nt"></author></span> <span class="nt"><link</span> <span class="na">rel=</span><span class="s">"edit"</span> <span class="na">title=</span><span class="s">"Supplier"</span> <span class="na">href=</span><span class="s">"Suppliers(0)"</span> <span class="nt">/></span> <span class="nt"><link</span> <span class="na">rel=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/related/Products"</span> <span class="na">type=</span><span class="s">"application/atom+xml;type=feed"</span> <span class="na">title=</span><span class="s">"Products"</span> <span class="na">href=</span><span class="s">"Suppliers(0)/Products"</span> <span class="nt">/></span> <span class="nt"><category</span> <span class="na">term=</span><span class="s">"ODataDemo.Supplier"</span> <span class="na">scheme=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"</span> <span class="nt">/></span> <span class="nt"><strong><c:Road></span>NE 228th<span class="nt"></c:Road></strong></span> <span class="nt"><content</span> <span class="na">type=</span><span class="s">"application/xml"</span><span class="nt">></span> <span class="nt"><m:properties></span> <span class="nt"><d:ID</span> <span class="na">m:type=</span><span class="s">"Edm.Int32"</span><span class="nt">></span>0<span class="nt"></d:ID></span> <span class="nt"><d:Name></span>Exotic Liquids<span class="nt"></d:Name></span> <span class="nt"><d:Concurrency</span> <span class="na">m:type=</span><span class="s">"Edm.Int32"</span><span class="nt">></span>0<span class="nt"></d:Concurrency></span> <span class="nt"><d:Address</span> <span class="na">m:type=</span><span class="s">"ODataDemo.Address"</span><span class="nt">></span> <span class="nt"><d:Street></span>NE 228th<span class="nt"></d:Street></span> <span class="nt"><d:City></span>Sammamish<span class="nt"></d:City></span> <span class="nt"><d:State></span>WA<span class="nt"></d:State></span> <span class="nt"><d:ZipCode></span>98074<span class="nt"></d:ZipCode></span> <span class="nt"><d:Country></span>USA<span class="nt"></d:Country></span> <span class="nt"></d:Address></span> <span class="nt"></m:properties></span> <span class="nt"></content></span> <span class="nt"></entry></span></code></pre></figure> <h3><a id="RepresentingPrimitiveProperties" name="RepresentingPrimitiveProperties"></a> 2.5. Representing Primitive Properties</h3> <p>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 <a href="../atom-format#PrimitiveTypes"> Primitive Types</a> section above.</p> <p>See <a href="../atom-format#RepresentingPropertyValues">section 3.1</a> for the format of Properties when they are represented independently from their defining Entry (i.e. outside the context of the defining Entry).</p> <h3><a id="RepresentingComplexTypesProperties" name="RepresentingComplexTypesProperties"></a>2.6. Representing Complex Type Properties</h3> <p>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 <a href="../overview#AbstractDataModel"> complex type</a> 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.</p> <p>See <a href="../atom-format#xml_RepresentingComplexTypesProperties">section 3.1.2</a> 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).</p> <h2><a id="XMLRepresentations" name="XMLRepresentations"></a>3. XML Representations</h2> <p>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.</p> <p>To enable this scenario, as described in the <a href="../uri-conventions#ResourcePath"> Resource Path</a> section in the <a href="../uri-conventions">[OData-URI]</a> 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.</p> <h3><a id="RepresentingPropertyValues" name="RepresentingPropertyValues"></a> 3.1. Representing Property Values</h3> <p>As described in the <a href="../uri-conventions#ResourcePath">Resource Path</a> section in the <a href="../uri-conventions">[OData-URI]</a> document, OData supports directly addressing a Property of an Entry. The following subsections describe how each type of Property is represented in XML.</p> <h4><a id="xml_RepresentingPrimitiveProperties" name="xml_RepresentingPrimitiveProperties"></a> 3.1.1. Representing Primitive Properties</h4> <p>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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version="1.0" encoding="utf-8" standalone="yes"?></span> <span class="nt"><Name</span> <span class="na">xmlns=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices"</span><span class="nt">></span>Bread<span class="nt"></Name></span></code></pre></figure> <h4><a id="xml_RepresentingComplexTypesProperties" name="RepresentingComplexTypesProperties"></a>3.1.2. Representing Complex Types Properties</h4> <p>When a Property whose type is a <a href="../overview#AbstractDataModel"> complex type</a> 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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version="1.0" encoding="utf-8" standalone="yes"?></span> <span class="nt"><Address</span> <span class="na">p1:type=</span><span class="s">"ODataDemo.Address"</span> <span class="na">xmlns:p1=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"</span> <span class="na">xmlns=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices"</span><span class="nt">></span> <span class="nt"><Street></span>NE 228th<span class="nt"></Street></span> <span class="nt"><City></span>Sammamish<span class="nt"></City></span> <span class="nt"><State></span>WA<span class="nt"></State></span> <span class="nt"><ZipCode></span>98074<span class="nt"></ZipCode></span> <span class="nt"><Country></span>USA<span class="nt"></Country></span> <span class="nt"></Address></span></code></pre></figure> <h4><a id="RepresentingtheRawvalueofaProperty" name="RepresentingtheRawvalueofaProperty"></a>3.1.3. Representing the Raw value of a Property</h4> <p>OData services may support <a href="../uri-conventions#AddressingEntries"> addressing the entry value of a primitive Property</a> (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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml">HTTP/1.1 200 OK DataServiceVersion: 1.0; Content-Type: text/plain;charset=utf-8 Food</code></pre></figure> <h3><a id="RepresentingLinks" name="RepresentingLinks"></a>3.2. Representing Links</h3> <p>A Link (or collection of Links) represents an associated Entry (or collection of associated Entries). As described in <a href="../operations">[OData-Operations]</a> 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.</p> <p>Note: in the paragraph above, "d" represents the <a href="../terminology#ODataDataNamespace"> OData Data Namespace</a>.</p> <p>For example, a link with multiplicity 1 (ex. Product is related to a <em>single</em> Supplier) would be represented in XML in a response as:</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version="1.0" encoding="utf-8" standalone="yes"?></span> <span class="nt"><uri</span> <span class="na">xmlns=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices"</span><span class="nt">></span> http://services.odata.org/OData/OData.svc/Suppliers(1) <span class="nt"></uri></span></code></pre></figure> <p>For example, a link with multiplicity greater than 1 (e.g. Supplier is related to <em>many</em> products) would be represented in a response as:</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version="1.0" encoding="utf-8" standalone="yes"?></span> <span class="nt"><links</span> <span class="na">xmlns=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices"</span><span class="nt">></span> <span class="nt"><uri></span>http://services.odata.org/OData/OData.svc/Products(1)<span class="nt"></uri></span> <span class="nt"><uri></span>http://services.odata.org/OData/OData.svc/Products(2)<span class="nt"></uri></span> <span class="nt"><uri></span>http://services.odata.org/OData/OData.svc/Products(3)<span class="nt"></uri></span> <span class="nt"><uri></span>http://services.odata.org/OData/OData.svc/Products(4)<span class="nt"></uri></span> <span class="nt"><uri></span>http://services.odata.org/OData/OData.svc/Products(5)<span class="nt"></uri></span> <span class="nt"><uri></span>http://services.odata.org/OData/OData.svc/Products(6)<span class="nt"></uri></span> <span class="nt"></links></span></code></pre></figure> <h3><a id="Representing Results from Service Operations" name="Representing Results from Service Operations"></a>3.3. Representing Results from Service Operations</h3> <p>As described in <a href="../operations">[OData-Operations]</a> OData services may expose custom behaviors via Service Operations, which may accept input parameters identified by the request URI (as described in <a href="../uri-conventions">[OData-URI]</a>). This section specifies how the results of a Service Operation are formatted using Atom or XML. Service operations support returning:</p> <ul> <li>A single primitive value or collection of primitive values</li> <li>A single complex type or collection of complex types</li> <li>A single Entry or collection of Entries</li> </ul> <p>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 <a href="../atom-format#RepresentingCollectionsofEntries"> Representing Collections of Entries</a> or <a href="../atom-format#RepresentingEntries">Representing an Entry</a> section.</p> <p>If a Service Operation returns a single primitive value, then it is formatted in XML as per the <a href="../atom-format#xml_RepresentingPrimitiveProperties">Representing Primitive Properties</a> section. Likewise, if a Service Operation returns a single Complex Type value, then it is represented in XML as per the <a href="../atom-format#xml_RepresentingComplexTypesProperties"> Representing Complex Type Properties</a> section.</p> <p>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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><GetInts</span> <span class="na">xmlns=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"</span><span class="nt">></span> <span class="nt"><element></span>0<span class="nt"></element></span> <span class="nt"><element></span>1<span class="nt"></element></span> <span class="nt"><element></span>2<span class="nt"></element></span> <span class="nt"></GetInts></span></code></pre></figure> <p>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 <a href="../atom-format#xml_RepresentingComplexTypesProperties"> Representing Complex Type Properties</a> 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.</p> <figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt"><GetAddressses</span> <span class="na">xmlns=</span><span class="s">"http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"</span><span class="nt">></span> <span class="nt"><element</span> <span class="na">type=</span><span class="s">"SampleNamespace.Address"</span><span class="nt">></span> <span class="nt"><street></span>123 Contoso Ave<span class="nt"></street></span> <span class="nt"><city></span>London<span class="nt"></street></span> <span class="nt"></element></span> <span class="c"><!-- additional Addresses returned go here --></span> <span class="nt"></GetAddresses></span></code></pre></figure> </div> <script src="//code.jquery.com/jquery-2.1.0.min.js"></script> <script src="//maxcdn.bootstrapcdn.com/bootstrap/3.2.0/js/bootstrap.min.js"></script> <script src=http://www.odata.org/public/site.js></script> <script type="text/javascript"> (function(w,d,t,u,n,s,e){w['SwiftypeObject']=n;w[n]=w[n]||function(){ (w[n].q=w[n].q||[]).push(arguments);};s=d.createElement(t); e=d.getElementsByTagName(t)[0];s.async=1;s.src=u;e.parentNode.insertBefore(s,e); })(window,document,'script','//s.swiftypecdn.com/install/v2/st.js','_st'); _st('install','23hsA6tEyP4R5VmqqdcD','2.0.0'); </script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-55977038-1', 'auto'); ga('send', 'pageview'); </script> </body> <footer class="content-info" role="contentinfo"> <div class="container" style=" text-align: center"> <p>© 2015 OData – The Protocol for REST APIs </p> </div> </footer> </html>