2.2.3.7.2 Conceptual Schema Definition Language Document for Data Services

All data services SHOULD expose a conceptual schema definition language (CSDL) based metadata endpoint that describes the structure and organization of all the resources exposed as HTTP endpoints by a data service.

This document defines data-service-specific extensions and mappings to the constructs of a CSDL document. These extensions MUST be used by a data service in conjunction with the "dataservices" node defined in [MC-EDMX] such that an Entity Data Model Extensions (EDMX) document is returned from the URI identifying the serviceRoot with a "/$metadata" path segment appended to the path.

The syntax of the metadata document of a data service returned as the content of the dataservices element is described in [MC-EDMX]. As noted in [MC-EDMX], the contents of the edmx:Edmx element, in the context of a data service, is an edmx:DataServices element that contains one or more CSDL documents, as specified in [MC-CSDL], with data service annotations.

The data service CSDL annotations are described and highlighted in the XML schema that follows, as specified in [XMLSCHEMA1/2]. Elements that do not include data-service-specific annotations have been omitted from the XSD document. See [MC-CSDL] for a complete structural description of a CSDL document.

 <?xml version="1.0" encoding="utf-8"?>
 <xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:cg="http://schemas.microsoft.com/ado/2006/04/codegeneration" xmlns:edm="http://schemas.microsoft.com/ado/2006/04/edm"
 xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices"
 targetNamespace="http://schemas.microsoft.com/ado/2006/04/edm">
  
  
 <!-- Elements not annotated for data services have been omitted.  See [MC-CSDL] for a complete structural description of a CSDL document -->
  
  <!-- Elements extended to specify mime type content for data services -->
  
  <xs:element name="Property" type="edm:TComplexTypeProperty" minOccurs="0"
              maxOccurs="unbounded" />
  
  <xs:complexType name="TComplexTypeProperty">
    <xs:sequence>
       <xs:group ref="edm:GEmptyElementExtensibility" minOccurs="0"
                 maxOccurs="1" />
    </xs:sequence>
    <xs:attributeGroup ref="edm:TCommonPropertyAttributes" />
    <!-- The m:TWebCustomizableFeedsAttributes attributeGroup is 
  supported only in Oata 2.0 and OData 3.0 (see section 2.2.3.7.2.1)  -->
    <xs:attributeGroup ref="m:TWebCustomizableFeedsAttributes" />
    <xs:anyAttribute namespace="##other" processContents="lax" />
  </xs:complexType>
  
  <xs:attributeGroup name="TCommonPropertyAttributes">
     <xs:attribute name="Name" type="edm:TSimpleIdentifier" use="required" />
     <xs:attribute name="Type" type="edm:TPropertyType" use="required" />
     <xs:attribute name="Nullable" type="xs:boolean" default="true"
                   use="optional" />
     <xs:attribute name="DefaultValue" type="xs:string" use="optional" />
     <!-- Start Facets -->
     <xs:attribute name="MaxLength" type="edm:TMaxLengthFacet"
                   use="optional" />
     <xs:attribute name="FixedLength" type="edm:TIsFixedLengthFacet"
                   use="optional" />
     <xs:attribute name="Precision" type="edm:TPrecisionFacet"
                   use="optional" />
     <xs:attribute name="Scale" type="edm:TScaleFacet" use="optional" />
     <xs:attribute name="Unicode" type="edm:TIsUnicodeFacet"
                   use="optional" />
     <xs:attribute name="Collation" type="edm:TCollationFacet"
                    use="optional" />
     <!--End Facets -->
     <xs:attribute name="ConcurrencyMode" type="edm:TConcurrencyMode"
                   use="optional" />
     <xs:attribute ref="cg:SetterAccess" use="optional" />
     <xs:attribute ref="cg:GetterAccess" use="optional" />
     <!-- Data Service Attributes -->
     <xs:attribute name="m:MimeType" type="xs:string" use="optional" />
  </xs:attributeGroup>
  
  <!-- Elements extended to specify HTTP method information
      for data services -->
  <xs:element name="FunctionImport">
    <xs:complexType>
       <xs:sequence>
          <xs:element name="Documentation" type="edm:TDocumentation"
                      minOccurs="0" maxOccurs="1" />
          <xs:element name="Parameter" type="edm:TFunctionImportParameter"
                      minOccurs="0" maxOccurs="unbounded" />
       </xs:sequence>
       <xs:attributeGroup ref="edm:TFunctionImportAttributes" />
    </xs:complexType>
  </xs:element>
  
  <xs:attributeGroup name="TFunctionImportAttributes">
    <xs:attribute name="Name" type="edm:TSimpleIdentifier" use="required" />
    <xs:attribute name="ReturnType" type="edm:TFunctionType" use="optional" />
    <xs:attribute name="EntitySet" type="edm:TSimpleIdentifier" use="optional" />
    <xs:attribute ref="cg:MethodAccess" use="optional" />
    <xs:attribute ref="m:HttpMethod" type="m:HttpMethod" use="optional" />
    <xs:attribute ref="m:IsAlwaysBindable" type="xs:boolean" default="false" />
    <xs:anyAttribute namespace="##other" processContents="lax" />
  </xs:attributeGroup>
  
  <xs:simpleType name="m:HttpMethod">
    <xs:restriction base="xs:string">
       <xs:enumeration value="POST" />
       <xs:enumeration value="PUT" />
       <xs:enumeration value="GET" />
       <xs:enumeration value="MERGE" />
       <xs:enumeration value="DELETE" />
       <xs:enumeration value="PATCH" />
    </xs:restriction>
  </xs:simpleType>
  
 <xs:element name="EntityType" type="edm:TEntityType" minOccurs="0" maxOccurs="unbounded" />
   <xs:complexType name="TEntityType">
     <xs:sequence>
       <xs:element name="Documentation" type="edm:TDocumentation"
  minOccurs="0" maxOccurs="1" 
         />
       <xs:element name="Key" type="edm:TEntityKeyElement" minOccurs="0"
  maxOccurs="1" />
       <xs:choice minOccurs="0" maxOccurs="unbounded">
         <xs:element name="Property" type="edm:TEntityProperty" minOccurs="0" 
            maxOccurs="unbounded" />
         <xs:element name="NavigationProperty" type="edm:TNavigationProperty"
  minOccurs="0" 
            maxOccurs="unbounded" />
       </xs:choice>
       <xs:any namespace="##other" processContents="lax" minOccurs="0"
  maxOccurs="unbounded" 
            />
     </xs:sequence>
     <xs:attributeGroup ref="edm:TDerivableTypeAttributes" />
     <--Data Service Attribute group. The m:TWebCustomizableFeedsAttributes attributeGroup   
        is supported only in OData 2.0 and OData 3.0 (see section 2.2.3.7.2.1)  -->
     <xs:attributeGroup ref="m:TWebCustomizableFeedsAttributes" />
     <xs:attribute name="m:HasStream" type="xs:boolean" use="optional" />
     <xs:attribute ref="cg:TypeAccess" use="optional" />
     <xs:anyAttribute namespace="##other" processContents="lax" />
   </xs:complexType>
  </xs:element>
  
  <xs:complexType name="TEntityProperty">
     <xs:sequence>
       <xs:group ref="edm:GEmptyElementExtensibility" minOccurs="0"
  maxOccurs="1" />
     </xs:sequence>
     <xs:attributeGroup ref="edm:TCommonPropertyAttributes" />
     <xs:anyAttribute namespace="##other" processContents="lax" />
     <--Data Service Attribute group. The m:TWebCustomizableFeedsAttributes
         attributeGroup is supported only in OData 2.0 and OData 3.0 (see section 2.2.3.7.2.1)  -->
      <xs:attributeGroup ref="m:TWebCustomizableFeedsAttributes" />
   </xs:complexType>
 </xs:schema>

The following listing describes the extensions to CSDL [MC-CSDL] that are defined by this document (and shown in the previous XML schema).

IsDefaultEntityContainer: This attribute MUST be used on an EntityContainer element [MC-CSDL] to indicate which EntityContainer is the default container for the data service. Each CSDL document that is used to describe a data service MUST mark exactly one EntityContainer with this attribute to denote that it is the default.

The valid values for this attribute are "true" or "false". True signifies that the container is the default container and, therefore, does not need to be specified in a resource path (section 2.2.3.3). False signifies that the container is not the default container and needs to be specified in the URI according to the URI construction rules that are noted in section 2.2.3.4.

MimeType: This attribute MAY<51> be used on a Property element [MC-CSDL] to indicate the media type of the content to be stored in the property that is being defined by the XML element. Each Property element that defines an EDMSimpleType property MAY include exactly one occurrence of this attribute.

Any media type (see [IANA-MMT]) is a valid value for this attribute. If this attribute is present on a property definition, any RetrieveValue Request (RetrieveValue Request (section 2.2.7.2.5)) for the property MUST return a response that uses the specified MIME type as the content type of the response body.

HttpMethod: This attribute MUST be used on a FunctionImport element [MC-CSDL] (section 2.1.15)] to indicate the HTTP method that is to be used to invoke the ServiceOperation that exposes the FunctionImport. If this attribute is present, the FunctionImport MUST be callable by using the HTTP method that is specified.

IsAlwaysBindable: This attribute MAY be used on a FunctionImport element [MC-CSDL] (section 2.1.15) to indicate whether the corresponding action or function can be bound to all instances of the binding parameter type. This attribute MUST not be specified if the IsBindable attribute is set to false or omitted (see sections 2.2.1.3 and 2.2.1.4).

HasStream: This attribute MUST only be used on an EntityType element [MC-CSDL]. The presence of this attribute with a value of "true" on an EntityType element states that the entity type is associated with a Media Resource (for example, the entity type represents a Media Link Entry [RFC5023]).

In addition to the extensions defined in the preceding example, the following mapping of data service constructs to CSDL constructs MUST be used by a data service to generate its metadata document.

Service Operations: A service operation MUST be represented as a FunctionImport element in the data services' CSDL document. The Name attribute on the element MUST be equal to the name of the service operation that is exposed by the data service.

For an example of a data services EDMX document, see Appendix A: Sample Entity Data Model and CSDL Document (section 6).

The following listing describes the extensions to the EDM for data services packaging format [MC-EDMX] that is defined by this document.

DataServiceVersion: This attribute MUST be in the data service metadata namespace (http://schemas.microsoft.com/ado/2007/08/dataservices) and SHOULD be present on an edmx:DataServices element [MC-EDMX] to indicate the version of the data service CSDL annotations (attributes in the data service metadata namespace) that are used by the document. Consumers of a data-service metadata endpoint ought to first read this attribute value to determine if they can safely interpret all constructs within the document. The value of this attribute MUST be 1.0 unless a "FC_KeepInContent" customizable feed annotation (section 2.2.3.7.2.1) with a value equal to false is present in the CSDL document within the edmx:DataServices node. In this case, the attribute value MUST be 2.0 or greater.

In the absence of DataServiceVersion, consumers of the CSDL document can assume the highest DataServiceVersion they can handle.

Named resource streams: A named resource stream MUST be represented as a Property of type Edm.Stream under the EntityType element in the data services' conceptual schema definition language (CSDL) document. The Name attribute of the Property MUST be equal to the name of the named resource stream exposed by the data service.

Properties of type Edm.Stream are used to define the named resource streams of an EntityType. For example, this EntityType has two named resource streams (Thumbnail and PrintReady).

       <EntityType Name="Photo" m:HasStream="true">
         <Key>
           <PropertyRef Name="ID" />
         </Key>
         <Property Name="ID" Type="Edm.Int32" Nullable="false" />
         <Property Name="Name" Type="Edm.String" Nullable="true" />
         <Property Name="Thumbnail" Type="Edm.Stream" />
         <Property Name="PrintReady" Type="Edm.Stream" />
  
       </EntityType>