SData Specification

Previous Page Arrow Next Page Arrow

4.2 Resource Kind Definition

Here is a typical resource kind definition extracted from the previous schema:

  <xs:element name="salesOrder" type="tns:salesOrder--type"
    sme:role="resourceKind" sme:pluralName="salesOrders" sme:label="Sales Order"
    sme:canGet="true" sme:canPost="true" sme:canPut="true" sme:canDelete="true" sme:hasTemplate="true"
    sme:canPageNext="true" sme:canPagePrevious="true" sme:canPageIndex="true"
    sme:hasUuid="true" sme:supportsETag="true" sme:batchingMode="syncOrAsync" />
  <xs:complexType name="salesOrder--type">
    <xs:all>
      <xs:element name="orderNumber" type="xs:string" minOccurs="0"
                  sme:label="#" sme:canSort="true" sme:canFilter="true" sme:precedence="1" 
                  sme:isUnique="true" sme:isReadOnly="true"/>
      <xs:element name="orderDate" type="xs:date" minOccurs="0"
                  sme:label="Date" sme:canSort="true" sme:canFilter="true" sme:precedence="2" />
      <xs:element name="shipDate" type="xs:date" minOccurs="0" nillable="true"
                  sme:label="Shipping Date" sme:canSort="true" sme:canFilter="true" sme:precedence="3" />
      <xs:element name="subTotal" type="xs:decimal" minOccurs="0"
                  sme:label="Sub-total" sme:canSort="true" sme:canFilter="true" sme:precedence="2"
                  sme:isReadOnly="true" />
      <xs:element name="billAddress" type="tns:address--type" minOccurs="0"
                  sme:relationship="child" sme:isCollection="false" sme:label="Billing Address"
                  sme:canGet="true" sme:canPut="true" />
      <xs:element name="shipAddress" type="tns:address--type" minOccurs="0"
                  sme:relationship="child" sme:isCollection="false" sme:label="Shipping Address"
                  sme:canGet="true" sme:canPut="true" />
      <xs:element name="orderLines" type="tns:salesOrderLine--list" minOccurs="0"
                  sme:relationship="child" sme:isCollection="true" sme:label="Order Lines"
                  sme:canGet="true" sme:canPost="true" />
      <xs:element name="contact" type="tns:contact--type" minOccurs="0"
                  sme:relationship="reference" sme:label="Contact"
                  sme:canGet="true" />
    </xs:all>
  </xs:complexType>
  <xs:complexType name="salesOrder--list">
    <xs:sequence>
      <xs:element minOccurs="0" maxOccurs="unbounded" name="salesOrder" type="tns:salesOrder--type" />
    </xs:sequence>
  </xs:complexType>

This definition starts with an element definition:

  <xs:element name="salesOrder" type="tns:salesOrderType" 
    sme:role="resourceKind" sme:pluralName="salesOrders" sme:label="Sales Order"
    sme:canGet="true" sme:canPost="true" sme:canPut="true" sme:canDelete="true"
    sme:canPageNext="true" sme:canPagePrevious="true" sme:canPageIndex="true" 
    sme:supportsETag="true" sme:batchingMode="syncOrAsync" />

This element definition contains a mix of standard XSD attributes and SData extensions. The following table describes the attributes that are relevant in a resource kind definition:

Attribute Value Description Compliance
sme:role resourceKind Allows a service consumer to tell the difference between XSD elements that describe resource kinds and XSD elements that describe service operations. It MUST be set to resourceKind on elements that on elements that describe resource kinds. MUST
name string Name of the resource kind in singular form. For example,  account. MUST
sme:pluralName string Name of the resource kind in plural form. For example, accounts. The XML payload elements use the singular form. For example, <account>. On the other hand, URLs use the plural form. For example, http://.../accounts. Both should be in the schema so that generic components and tools have access to both forms. MUST
type complexType reference Reference to the complex type element that describes the resource structure. This name MUST be formed by appending --type to the name of the resource kind. For example, account--type. The reference must be prefixed with the prefix that has been associated to the target namespace. In the example it is tns:. MUST
sme:path relative URL URL (relative to the dataset segment) where the resources can be queried. If this attribute is omitted, the relative URL is assumed to be the plural name. In the example it is the value of the sme:pluralName attribute. This attribute is nevertheless useful when the resource kinds are organized in functional groups because the plural name is the last element of the relative path in this case. See [Resource Collection URL](2.1 Resource Collection URL "2.1 Resource Collection URL") section. MAY
sme:label string A friendly name for the element (localized). Use it to build menus with lists of resource kinds. SHOULD
sme:canGet true (default) false Does the resource kind support read and query operations (HTTP GET)? MUST (if true)
sme:canPost true false (default) Does the resource kind support create operations (HTTP POST)? MUST (if true)
sme:canPut true false (default) Does the resource kind support update operations (HTTP PUT)? MUST (if true)
sme:canDelete true false (default) Does the resource kind support delete operations (HTTP DELETE)? MUST (if true)
sme:hasTemplate true false Does the resource kind support the $templateUrl If this attribute is absent, true is assumed if canPost=true, false otherwise. SHOULD (if true)
sme:canSearch true false (default) Does the resource kind support full-text search through the search query parameter? See [Query Parameters](2.11 Query Parameters "2.11 Query Parameters") section for details. SHOULD (if true)
sme:canPagePrevious true false (default) Does the resource kind support sequential paging in backwards direction? When this attribute is true, feeds MUST contain previous and last link (no previous link on first page, though) MUST (if true)
sme:canPageNext true false (default) Does the resource kind support sequential paging in forwards direction? When this attribute is true, feeds MUST contain next and first links (no next link on last page, though) MUST (if true)
sme:canPageIndex true false (default) Does the resource kind support indexed paging? When this attribute is true, feeds MUST contain opensearch elements. Also, startIndex and count parameters should be supported in query URLs. MUST (if true)
sme:hasUuid true false (default) Does the resource kind use UUIDs to identify resources? When this attribute is set, feeds payload MUST carry sdata:uuid attributes. MUST (if true)
sme:supportsETag true false (default) Does the resource kind support the ETag mechanism to control [concurrent updates](9.3 Update Concurrency Handling)? MUST (if true)
sme:batchingMode none (default) sync async syncOrAsync Does the resource kind support [batching](13.2 Metadata Extension for Batching)? If so, what invocation modes does it support? MUST (if batching supported)
sme:unsupported true false (default) Is the resource kind part of a global contract that is not supported by this specific provider? SHOULD (if true)
sme:tags comma separated string List of tags that apply to the resource kind. SData does not impose any predefined list of tags. Instead, each contract is free to define its own list of tags. This feature is an extensibility mechanism. It should be used when the information cannot be captured by one of the other SME attributes, not as a replacement for existing SME attributes. MAY (1.1)
sme:protocolFilters comma separated string list of protocol filter variables that the provider supports in where parameters and resource selectors See [Query Language](2.12 Query Language "2.12 Query Language") for details MAY (1.1)

In the example, the sales order resource kind supports all CRUD operations (GET, POST, PUT, DELETE). It also supports the ETag mechanism for concurrency handling and it supports batching in both synchronous and asynchronous modes.

There is an overlap between the canGet, canPost, ... SME attributes and the HTTP OPTIONS method. The attributes have nevertherless been introduced because they allow an SData consumer to get a global view of the service contract, without having to query several URLs to find out which operations are available on which entity. Also, these attributes describe what is statically supported or not by the contract. Not what the current user context allows or not. The access control rules can further restrict the operations a user can perform

This resource kind element is followed by a complexType definition:

    <xs:complexType name="salesOrder--type">
    <xs:all>
      <xs:element name="orderNumber" type="xs:string" minOccurs="0"
                  sme:label="#" sme:canSort="true" sme:canFilter="true" sme:precedence="1" 
                  sme:isUnique="true" sme:isReadOnly="true"/>
      <xs:element name="orderDate" type="xs:date" minOccurs="0"
                  sme:label="Date" sme:canSort="true" sme:canFilter="true" sme:precedence="2" />
      <xs:element name="shipDate" type="xs:date" minOccurs="0" nillable="true"
                  sme:label="Shipping Date" sme:canSort="true" sme:canFilter="true" sme:precedence="3" />
      <xs:element name="subTotal" type="xs:decimal" minOccurs="0"
                  sme:label="Sub-total" sme:canSort="true" sme:canFilter="true" sme:precedence="2"
                  sme:isReadOnly="true" />
      <xs:element name="billAddress" type="tns:address--type" minOccurs="0"
                  sme:relationship="child" sme:isCollection="false" sme:label="Billing Address"
                  sme:canGet="true" sme:canPut="true" />
      <xs:element name="shipAddress" type="tns:address--type" minOccurs="0"
                  sme:relationship="child" sme:isCollection="false" sme:label="Shipping Address"
                  sme:canGet="true" sme:canPut="true" />
      <xs:element name="orderLines" type="tns:salesOrderLine--list" minOccurs="0"
                  sme:relationship="child" sme:isCollection="true" sme:label="Order Lines"
                  sme:canGet="true" sme:canPost="true" />
      <xs:element name="contact" type="tns:contact--type" minOccurs="0"
                  sme:relationship="reference" sme:label="Contact"
                  sme:canGet="true" />
    </xs:all>
  </xs:complexType>

This complexType defines the resource structure as a set of property elements. The following sections describes property elements and their attributes.

SData needs these elements grouped under an <xs:all> element rather than an <xs:sequence> element because SData producers and consumers should not rely on a specific ordering of property values.

The last piece of the definition is a definition for a “list” type: 

  <xs:complexType name="salesOrder--list">
     <xs:sequence>
       <xs:element minOccurs="0" maxOccurs="unbounded" name="salesOrder" type="tns:salesOrder--type" />
    </xs:sequence>
  </xs:complexType>

This definition is an XML Scheme Definition (XSD) rule that simplifies the expression of 1 to N and N to M relationships.  All it does is define an Xxx–list as a sequence of Xxx-type elements.

This definition is not really necessary for all resource kinds, only for those that are involved in 1 to N or N to M relationships. But it is usually easier to append this list definition systematically.

SData providers MUST return a schema and MUST follow the rules above.
Previous Page Arrow Next Page Arrow