2.2.6.2.12 Annotations

In OData 3.0, just as annotations can be applied to metadata constructs in the service metadata document (section 2.2.3.7.2), annotations MAY also be applied to elements in an AtomPub payload. Annotations are represented as annotation elements that follow the rules detailed in this section.

Any AtomPub element that represents an Entity Data Model (EDM) construct (for more details, see [MC-CSDL] section 2.2.6.2 and its subsections) MAY be annotated. Parsers MAY choose to ignore annotations.

Rules for Instance Annotations: An instance annotation is represented as an XML element with the name "annotation" in the metadata namespace (see section 2.2.6.1). The annotation element MUST have a term attribute that specifies the fully qualified name of the term being applied.

If the type of the annotation value is anything other than Edm.String, a type attribute MUST be present with a value that is equal to the name of the type.

The value of the element that represents a value annotation whose type is a primitive value MUST be an EDM primitive value that is formatted as per section 2.2.6.1.

The value of the element the represents a value annotation whose type is a collection MUST be the individual elements of that collection formatted as direct child elements of the annotation element, as specified in Collection Property of Complex Type (section 2.2.6.2.9.1) and Collection of EDMSimple Type (section 2.2.6.5.7).

Each property of an annotation whose type is a ComplexType or EntityType MUST be represented as a direct child element of the annotation element. The name of the child element MUST be the name of the property and MUST be in the data service namespace (for more information, see Common Serialization Rules for XML-based Formats (section 2.2.6.1)). Further formatting rules that MUST be adhered to when representing properties within an annotation are the same as the rules for primitive and complex properties of an EntityType or ComplexType in an AtomPub payload, as defined in section 2.2.6.2.2 or 2.2.6.2.3, respectively, and their respective subsections.

target Attribute: The annotation element MAY have a target attribute to state the target element that is being annotated. Legal values for this annotation are '.' or the name of the target element that is being annotated.

If the value of the target attribute is '.' or if the target attribute is omitted, the target of the annotation is the model element that is represented by the direct parent element that the annotation is within.

If the value of the target attribute is the name of the target element that is being annotated, that element MUST be a sibling of the annotation element. If multiple possible target elements exist, the value of this attribute MUST be a namespace qualified (namespacePrefix.targetElementName) element name.

When annotating a property, the annotation element MUST be a direct child of the properties element that is defined in the metadata namespace, and the value of the target attribute MUST specify the property that is being annotated.

When annotating a navigation property, named stream, or other element that is represented by a link element, the annotation element MUST be a direct child of the link element that represents the navigation property.

When annotating an entity, the annotation element MUST be a direct child of the entry element that represents the entity.

When annotating a feed, the annotation element MUST be a direct child of the feed element.

When annotating an error, the annotation element MUST be a direct child of the error element and MAY target the code, message, or innererror, or the error itself if target is not specified or is specified with a value of ".".

Instance annotations are not supported when serializing single EdmSimpleType properties in XML, as described in 2.2.6.5.3.

The following example shows an annotated collection of the Customer Entities described in Appendix A: Sample Entity Data Model and CSDL Document (section 6) with the following annotations.

 <?xml version="1.0" encoding="utf-8" standalone="yes"?>
 <feed xml:base="http://host/service.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://host/service.svc/Customers</id>
   <updated>2009-03-27T23:41:29Z</updated>
   <link rel="self" title="Customers" href="Customers" />
   <!-- instance annotation targetting the collection of Customers -->
   <annotation term="com.contoso.customervocab.setkind">VIPs</annotation>
   <entry>
     <!-- instance annotation targetting the Entity Type instance --> 
     <annotation term="com.contoso.customervocab.kind">VIP</annotation>  
     <id> http://host/service.svc/Customers('ALFKI')</id>
     <title type="text"></title>
     <updated>2009-03-27T23:41:29Z</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">
       <!-- instance annotation targetting the Orders navigation property -->
       <annotation term="com.contoso.purchaseordervocab.priority" m:type="Edm.Int">1</annotation>
     </link>
     <!-- Note: navigation properties have been removed to limit the size of this example -->
     <content type="application/xml">
       <m:properties>
         <!-- instance of a structured annotation targetting the CompanyName property -->
         <annotation term="con.contoso.displayvocabulary.displayInfo m:target="CompanyName">  
             <d:title m:type="Edm.Boolean">true</d:title>   
             <d:order m:type="Edm.Int">1</d:order>
         </annotation>
         <d:CustomerID>ALFKI</d:CustomerID>
         <d:CompanyName>Alfreds Futterkiste</d:CompanyName>
         <d:ContactName> Alfreds Futterkiste </d:ContactName>
         <d:ContactTitle>Sales Representative</d:ContactTitle>
         <d:Address>Obere Str. 578</d:Address>
         <d:City>Toronto</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>
 </feed> 
 <?xml version="1.0" encoding="utf-8" standalone="yes"?>
 <feed xml:base="http://host/service.svc"
  xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
  xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
  xmlns:cust="http://contoso.com/customervocab"
  xmlns:display="http://contoso.com/displayvocab"
  xmlns:po="http://contoso.com/purchaseordervocab"
  xmlns="http://www.w3.org/2005/Atom">
   <title type="text">Customers</title>
   <id>http://host/service.svc/Customers</id>
   <updated>2009-03-27T23:41:29Z</updated>
   <link rel="self" title="Customers" href="Customers" />
   <!-- instance  value annotation targetting the collection of Customers -->
   <cust:setkind m:target=".">VIPs</cust:setkind>
   <entry>
     <!-- instance value annotation targetting the Entity Type instance --> 
     <cust:kind m:target="." m:type="Edm.String">VIP</cust:kind>  
     <id> http://host/service.svc/Customers('ALFKI')</id>
     <title type="text"></title>
     <updated>2009-03-27T23:41:29Z</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">
       <!-- instance value annotation targetting the Orders navigation property -->
       <po:priority m:target="." m:type="Edm.Int">1</po:priority>
     </link>
     <!-- Note: navigation properties have been removed to limit the size of this example -->
     <content type="application/xml">
       <m:properties>
         <!-- instance of a type annotation targetting the CompanyName property -->
         <display:display m:target="CompanyName">  
             <display:title m:type="Edm.Boolean">true</display:title>   
             <display:order m:type="Edm.Int">1</display:order>
         </display:display>
         <d:CustomerID>ALFKI</d:CustomerID>
         <d:CompanyName>Alfreds Futterkiste</d:CompanyName>
         <d:ContactName> Alfreds Futterkiste </d:ContactName>
         <d:ContactTitle>Sales Representative</d:ContactTitle>
         <d:Address>Obere Str. 578</d:Address>
         <d:City>Toronto</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>
 </feed>