2.2.3.7.2.1 Conceptual Schema Definition Language Document Extensions for Customizable Feeds

Applies to the OData 2.0 and OData 3.0 protocols

This section defines OData protocol specific extensions (shown in the XML schema that follows) to the data-service-specific metadata document that is defined in the preceding section. These attributes define customizable feed property mappings for the AtomPub format. Customizable feed property mappings are defined in the OData 2.0 and OData 3.0 protocols.

 <?xml version="1.0" encoding="utf-8"?>
 <xs:schema attributeFormDefault="qualified" 
            elementFormDefault="qualified" 
            targetNamespace="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" 
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
  
   <xs:attributeGroup name="TWebCustomizableFeedsAttributes">
     <xs:attribute name="FC_KeepInContent"/>
     <xs:attribute name="FC_ContentKind"/>
     <xs:attribute name="FC_NsPrefix"/>
     <xs:attribute name="FC_NsUri" />
     <xs:attribute name="FC_SourcePath" />
     <xs:attribute name="FC_TargetPath" />
     <xs:attribute name="FC_Criteria" />
     <xs:attribute name="FC_CriteriaValue" />
   </xs:attributeGroup>
 </xs:schema>

Listing: Conceptual Schema Definition Language Document XSD Schema Extensions for Customizable Feeds

The customizable feed property mappings are used to define a mapping from the properties of an EntityType to elements or attributes in any namespace (including the Atom namespace) in an AtomPub document. When a property is mapped to an element or to an attribute of an element, the value for the property is equal to the value of the specified element or attribute in the AtomPub document. An example of a mapped property value is described in Retrieve a Single Entity with a Mapped Property by Using the AtomPub Format (section 4.2.2.1).

The following example shows a Conceptual Schema Definition Language (CSDL) definition of an entity type that includes customizable feed property mappings. The customizable feed annotations that are defined on the entity type map the EmployeeName property of the Employee entity type to the atom:title element in the Atom namespace. The following example also includes a mapping that specifies the City property of the Address ComplexType property to be represented by using the service-defined XML element emp:Location xmlns:"http://www.microsoft.com".

 <EntityType Name="Employee" m:FC_KeepInContent="true"
    m:FC_TargetPath="Location" m:FC_SourcePath="Address/City" 
    m:FC_NsUri="http://www.microsoft.com" m:FC_NsPrefix="emp">
    <Key>
       <PropertyRef Name="EmployeeID" />
    </Key>
    <Property Name="EmployeeID" Type="Edm.String" Nullable="false"
       MaxLength="5" Unicode="true" FixedLength="true" />
    <Property Name="EmployeeName" Type="Edm.String" Nullable="false"
       MaxLength="40" Unicode="true" FixedLength="false" 
       m:FC_KeepInContent="false"          
       m:FC_TargetPath="SyndicationTitle"/>
    <Property Name="Address" Type="Sample.EAddress" Nullable="true" />
    <Property Name="Version" Type="Edm.Binary" Nullable="true" MaxLength="8"
       FixedLength="true" ConcurrencyMode="Fixed" />
 </EntityType>
  
 <ComplexType Name="EAddress">
   <Property Name="Street" Type="Edm.String" Unicode="true" />
   <Property Name="City" Type="Edm.String" Unicode="true"/>
 </ComplexType>

A property mapping MUST be defined as an attribute on the Property element of an entity type (as in the previous example) or on the EntityType element that contains the property to be mapped. A single EntityType property MUST NOT have more than one property mapping defined.

The following listing describes the extensions to CSDL [MC-CSDL] that are defined by this section (and are shown in the preceding XML schema). These extensions are supported only in the OData 2.0 and OData 3.0 protocols.

FC_ContentKind: The FC_ContentKind attribute specifies the content type of the value of the property being mapped via a customizable feed mapping.

The syntax of the FC_ContentKind attribute is defined as follows.

 FC_ContentKind = "text " / "html" / "xhtml"

If the FC_ContentKind property is not defined for an EntityType property, the value of the property is assumed to be "text ".

FC_KeepInContent: The FC_KeepInContent attribute specifies whether the value of the property on the EntityType of this attribute is to be included in both the element specified via the customizable feed mapping as well as the original m:properties elements inside the atom:content element, as specified in section 2.2.6.2.2. The value for the FC_KeepInContent attribute MUST have either the value "true" or "false". If the FC_KeepInContent attribute is not supplied in the mapping, the data service MUST function as if it were specified with a value of true.

FC_NsPrefix: The FC_NsPrefix attribute specifies the XML namespace prefix to use when an entity type's property is mapped to an XML element in a data-service-specific namespace. If the FC_TargetPath attribute of the property mapping does not specify an Atom element, then the FC_NsPrefix attribute is optional. If the entity type property is being mapped to an AtomPub element, then the FC_NsPrefix attribute MUST NOT be specified. If the FC_TargetPath attribute of the property mapping does not specify an Atom element and the FC_NsPrefix attribute is not supplied, then this document does not mandate a particular prefix be used.

FC_NsUri: The FC_NsUri attribute specifies the namespace to use when the FC_TargetPath of the entity type's property mapping does not specify an AtomPub element. If the FC_TargetPath of the entity type's property mapping does not specify an AtomPub element, then the FC_NsUri attribute MUST be specified on the entity type's definition. If the property is being mapped to an AtomPub element, then the FC_NsUri attribute MUST NOT be specified on the entity type's definition.

FC_TargetPath: The FC_TargetPath attribute identifies the element within an atom:entry element to which to map the entity type's property. All mapped properties MUST be mapped to distinct elements within the Atom feed.

If the mapping is not to an Atom element, the value of the FC_TargetPath MUST identify either an element or an attribute on an element in the AtomPub document. All paths' expressions MUST be rooted at the entry element in the Atom feed.

The syntax of the target path is defined as follows.

 targetPath = targetPathExpression ["/" attribute] / atomSpecificElement
  
 targetPathExpresion = targetPathExpression "/" targetPathExpression
                 / element
  
 element = <the name of an element in the AtomPub document>
  
 atomSpecificElementName = 
                      ; the following values are defined in OData 2.0 and OData 3.0
                          "SyndicationAuthorName"  
                           / "SyndicationAuthorEmail"
                           / "SyndicationAuthorUri"
                           / "SyndicationPublished" 
                           / "SyndicationRights"
                           / "SyndicationTitle"
                           / "SyndicationUpdated"
                           / "SyndicationContributorName"
                           / "SyndicationContributorEmail"
                           / "SyndicationContributorUri"
                           / "SyndicationSource"
  
 attribute = "@" <the name of an attribute in the AtomPub document>

A data service SHOULD allow customizable feed mappings for distinct entity type properties that have partially overlapping FC_TargetPaths (a set of FC_TargetPaths are overlapping when they have some target elements in common). A data service SHOULD support target paths that define elements with mixed content. For example, the following three target paths on distinct properties will create an element structure with overlapping target paths and XML elements with mixed content.

 TargetPath1: "a/b/c"
 TargetPath2: "a/b/d"
 TargetPath3: "a/b"

The following is the resulting element structure.

 <a>
    <b>
         <c>propertyValue1</c>
         <d>propertyValue2</d>
         propertyValue3
    </b>
 </a>

FC_SourcePath: The FC_SourcePath attribute specifies the entity type property that is the source property for the mapping. If the property mapping is specified directly on a property definition (properties are defined by using the Property element) in the CSDL and the property is a primitive property, the mapping cannot specify the FC_SourcePath attribute and the property identified by the Property element MUST be used as the source property of the mapping. If the property mapping is defined on an EntityType element, the FC_SourcePath attribute MUST be specified and the value MUST be the name of either a primitive property defined on the EntityType or a primitive property of a ComplexType, which is the type of a property on the EntityType.

The syntax of the FC_SourcePath is defined as follows.

 FC_SourcePath = FC_SourcePathExpression
  
 FC_SourcePathExpression = FC_SourcePathExpression "/" FC_SourcePathExpression
                 / element

The FC_SourcePath MUST NOT address an EntityType property that represents a ComplexType but MAY address a declared EDMSimpleType property that is defined on a ComplexType.

For example, using the EntityType Employee, as specified in Appendix A: Sample Entity Data Model and CSDL Document (section 6), specifying the City property of an Address ComplexType on an Employee EntityType, an FC_TargetPath value of "Location", an FC_NsPrefix value of "emp", and an FC_NsUri value of "http://www.microsoft.com" would create the following element under the atom:entry element.

 <emp:Location xmlns:emp="http://www.microsoft.com">Seattle</emp:Location>