2.2.6.2.2 Entity Type (as an Atom Entry Element)

An EntityType instance MUST be represented as an atom:entry element, as specified in [RFC4287], section 4.1.2. This section adds additional constraints to the formatting rules defined in Atom for atom:entry elements.

An Atom-formatted EntityType instance MUST adhere to the rules defined in this section.

atom:entry element: This element is specified in [RFC4287] section 4.1.2

atom:entry child elements: If the entity represents an AtomPub Entry Resource [RFC5023] (section 4.2), the atom:content element MUST contain a "type" attribute with the value "application/xml". The atom:content element SHOULD<59> also contain one m:properties child element. The m:properties element MUST contain one child element for each EDMSimpleType, ComplexType, and Collection type property of the EntityType instance that is represented by the atom:entry element that is not otherwise mapped through a customizable feed property mapping in its Data Service Metadata Document (as defined in section 2.2.3.7.2.1). Child elements of the m:properties element that represent entity properties MUST have the same name as the property they represent, MUST belong to the data services namespace (section 2.2.6.1), and MAY have an m:type attribute to specify the EDM type of the property. If the m:type attribute is missing, the EDM type of the property MUST be assumed to be Edm.String. If the EntityType instance being represented was identified with a URI that includes a Select system query option (section 2.2.3.6.1.11), the prior rule is relaxed such that only the properties identified by the $select query option SHOULD be represented as child elements of the m:properties element. Each child element that represents a property MUST be defined in the data service namespace, as described in Common Serialization Rules for XML-Based Formats (section 2.2.6.1), and the element name has to be the same as the property it represents. The rules for how to represent an entity type as an atom:entry element that contains customizable feed property mappings are defined in Entity Type (as an Atom Entry Element) with a Customizable Feed Property Mapping (section 2.2.6.2.2.1).

If the entity represents an AtomPub Media Link Entry, as specified in [RFC5023] (section 4.2), the m:properties element MUST also contain the EDMSimpleType, ComplexType, and, in the OData 3.0 protocol, the collection properties of the EntityType instance, as described in the preceding paragraph. However, the m:properties element MUST be a direct child of the atom:entry element (as opposed to the atom:content element). Additionally, as specified in [RFC5023], an atom:link element SHOULD be included, which contains a rel="edit-media" attribute. If such an atom:link element identifies a Media Resource with an associated concurrency token, the element SHOULD include an m:etag attribute with a value equal to the ETag of the media resource identified by the atom:link element.

An atom:category element containing a term attribute and a scheme attribute MUST be included if the EntityType of the EntityType instance represented by the atom:entry object is part of an inheritance hierarchy, as described in [MC-CSDL] (section 1). If the EntityType is not part of an inheritance hierarchy, the atom:category element SHOULD be included. The value of the term attribute MUST be the namespace qualified name of the EntityType of the instance represented by the atom:entry element. The value of the scheme attribute MUST be a data service specific IRI which, as specified in [RFC4287], identifies the categorization scheme used. If a data service does not have a scheme IRI, it SHOULD use the URI shown in grammar rule dataServiceSchemeURI in the Entity Type Atom Representation URIs (ABNF Grammar) listing that follows in this section.

An m:etag attribute MAY be included on the entry element representing the EntityType instance. In this context, the "m" prefix refers to the data service metadata namespace defined in Common Serialization Rules for XML-Based Formats (section 2.2.6.1). When included, it MUST represent the concurrency token associated with the EntityType instance, as defined in ETag (section 2.2.5.4), and MUST be used instead of the ETag HTTP header defined in ETag (section 2.2.5.4), which, according to [RFC2616], is used to represent a single entity when multiple entities are present in a single payload.

An atom:link element SHOULD be included, which contains a rel="edit" or rel="self" attribute. The rel attribute MAY<60> be used to indicate that a resource is read-only (when the value of the attribute is "self") or read-write (when the attribute's value is "edit"). If such an atom:link element is included, it MUST have an href attribute whose value is a URI that identifies the entity represented by the atom:entry element.

In responses to retrieve requests, as specified in RetrieveEntity Request (section 2.2.7.2.2), servers MUST represent the URI that represents a related entity or collection of entities (NavigationProperty) of the EntityType as an atom:link element that is a child element of the atom:entry element. Each atom:link element MUST contain a rel attribute with the value defined by the relNavigationlLinkURI rule shown in the following grammar, as defined in the listing that follows. The element SHOULD also contain a title attribute with the value equal to the NavigationProperty name and MUST contain an href attribute with value equal to the URI which identifies the NavigationProperty on the EntityType.

Note   Atom also requires a type attribute, which MUST have a value of "application/atom+xml;type=entry" when the NavigationProperty identifies a single entity instance and "application/atom+xml;type=feed" when the property identifies an EntitySet.

 dataServiceNs       = "http://schemas.microsoft.com/ado/2007/08/dataservices"
                       / <Server specified "Data Service namespace" URI>
                          ; see section 2.2.6.1
  
 dataServiceSchemeURI= "http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"
 relNavigationLinkURI=  dataServiceNs
                         "/related/"
                         ; line below represents the name of the Navigation Property
                         ; (not type qualified) being represented by the current
                         ; atom:link element
                         entityNavProperty         ; section 2.2.3.1

In OData 3.0, responses to retrieve requests, as specified in RetrieveEntity Request (section 2.2.7.2.2), MAY represent the URI that identifies the association between the entity represented by the response payload and a related entity (or collection of entities) as an atom:link element that is a child element of the atom:entry element. If present, each atom:link element MUST contain a rel attribute with the value defined by the relAssociationlLinkURI rule shown in the grammar defined in the listing that follows. The element MUST also contain an href attribute with a value equal to the URI that identifies the association represented by the atom:link element (that is, the NavigationProperty on the EntityType).

Note  Atom also requires an atom:type attribute, which MUST have a value of "application/xml".

 relAssociationLinkURI=  dataServiceNs
                         "/relatedlinks/"
                         ; line below represents the name of the Navigation Property
                         ; (not type qualified) being represented by the current
                         ; atom:link element
                         entityNavProperty         ; section 2.2.3.1

Listing: URI of the atom:link rel attribute for Navigation Properties of an Entity Type (ABNF Grammar)

For example, the Customer EntityType instance described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) is represented in Atom as described in the following listing.

 <?xml version="1.0" encoding="utf-8"?>
 <entry xml:base="http://host/service.svc/"
        xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
        xmlns:gml="http://schemas.opengis.net/gml/3.1.1/profiles/gmlsfProfile/1.0.0/gmlsf.xsd"
        xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
        xmlns="http://www.w3.org/2005/Atom">
   <category term="SampleModel.Customer"
             scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
   <id>http://host/service.svc/Customers('ALFKI')</id>
   <title type="text" />
   <updated>2008-03-30T21:32:23Z</updated>
   <author>
     <name />
   </author>
   <link rel="edit" title="Customers" 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/relatedlinks/Orders" type="application/xml"  
        title="Orders"
        href="Customers('ALFKI')/$links/Orders" />
   <content type="application/xml">
     <m:properties>
       <d:CustomerID>ALFKI</d:CustomerID>
       <d:CompanyName>Alfreds Futterkiste</d:CompanyName>
       <d:Address>
         <d:Street>57 Contoso St</d:Street>
         <d:City>Seattle</d:City>
         <d:Location m:type="Edm.GeographyPoint"><gml:Point srsName="4326">-127.345345 48.23423</gml:Point></d:Location>
       </d:Address>
       <d:EmailAddresses m:type="Collection(Edm.String)">
         <d:element>altaddress1@company.com</d:element>             
         <d:element>altaddress2@company.com</d:element>             
       </d:EmailAddresses>
       <d:AlternateAddresses m:type="Collection(SampleModel.Address)">
         <d:element m:type="SampleModel.EAddress">
           <d:Street>123 contoso street</d:Street>
         </d:element>  
         <d:element>
           <d:Street>834 1st street</d:Street>
           <d:Apartment>102</d:Apartment>
         </d:element>
       </d:AlternateAddresses>
       <d:Version>AAAAAAAA+gE=</d:Version>
     </m:properties>
   </content>
 </entry>

Listing: OData 3.0 Atom-Formatted Customer Entity