Introduction
OData services provide a uniform interface for interacting with their resources, and in addition are self-describing:
- The service document (located at the service root) lists the available top-level resources, and
- The service metadata document (located at the address $metadata relative to the service root) describes the structure of all resources in the service.
This structural metadata makes it easy to understand a service, and human-readable documentation can be directly embedded into the metadata document, helping developers consume an OData service.
This alone is a huge benefit, yet metadata can be taken one step further by embedding machine-readable additional metadata that can be leveraged by development tools, client libraries, and generic clients to better interact with the service.
One area are semantic annotations that tell which of the OData properties contain e.g. a phone number, a part of a name or address, or something related to a calendar event or an analytic query. This is important for apps running on mobile devices that want to seamlessly integrate into contacts, calendar, and telephony.
The next area are capability annotations that describe which of the possible interactions defined by OData's uniform interface are supported by which parts of a concrete service. These annotations will e.g. tell whether an entity set allows inserts, updates, or deletes, whether it requires a filter, and which properties can be used in filter expressions. They also advertise capabilities that go beyond the base set defined by OData, e.g. whether an entity set allows free-text search via an SAP-defined query option.
Contents
AtomPub Service Document
AtomPub allows extending the service document with elements and attributes from XML namespaces other than AtomPub. The following sections describe which elements of the service document (namespace prefix app) can be annotated with attributes and elements from the namespace http://www.sap.com/Protocols/SAPData (namespace prefix sap) and from the namespace http://www.w3.org/2005/Atom (namespace prefix atom), and what these annotations mean.
Element app:service
The app:service element can be annotated with two elements from the atom namespace:
- <atom:link rel="self" href="..."/> contains the link to this service document, and
- <atom:link rel="latest-version" href="..."/> contains the link to latest version of this service.
If the latest-version link deviates from the self link, a client may inspect the newer version of the service and decide (probably after asking its user) to switch over to the newer service version.
Element app:collection
The app:collection element can be annotated with three elements:
- <sap:member-title> contains the human-readable name or caption for a single member of the collection. This typically is the singular form of the content of the <atom:title> element of this collection.
- <atom:link rel="search" href="..."/> contains the link to an OpenSearch description document that describes how to use free-text search for this collection. For those not familiar with OpenSearch: just append the SAP-specific query option searchto the URL of the collection.
- <atom:link rel=http://www.sap.com/Protocols/SAPData/rel#subscribe href="..."/> contains the link to the collection of the same service that allows subscribing to content changes of the annotated collection. For more information see the HowTo Guides - Subscription & Notification with SAP NetWeaver Gateway - Series.
Metadata Document
OData's Conceptual Schema Definition Language (CSDL) allows annotating most model elements with XML attributes or elements from foreign XML namespaces. The following sections describe which elements of the metadata document (namespace prefix edm) can be annotated with attributes and elements from the namespace http://www.sap.com/Protocols/SAPData (namespace prefix sap), and what these annotations mean.
Element edm:EntitySet
Entity sets can be annotated with the following attributes. If not stated explicitly, consumers can assume them to have the default value listed in the second column. This default value reflects the "normal" behavior that can be expected from any OData service.
| Attribute Name | Default Value | Meaning / Type / Values |
|---|---|---|
| label | - | Description, will also be used as atom:title in the service document |
| creatable | true | New entities can be created in this set |
| updatable | true | Entities in this set can be updated |
| deletable | true | Entities can be deleted from this set |
| searchable | false | Supports custom query option search |
| pageable | true | Supports system query options $top and $skip |
| topable | true | Supports system query option $top |
| addressable | true | Use “false” if this entity set can only be accessed within its containing entity, e.g. SalesOrderItems within SalesOrders through SalesOrders(4711)/Items. Direct access to non-addressable collections will result in a 404 response code; they are also not visible in the service document |
| requires-filter | false | Use “true” if this set cannot be queried without providing a $filter expression. If accessed without a filter expression, it will respond with a human-readable error message explaining which kinds of filter expressions are required as a minimum |
Element edm:EntityType
Entity types can be annotated with the following attributes:
| Attribute Name | Meaning / Type / Values |
|---|---|
| label | Description, will also be used as sap:member-title in the service document |
| semantics | See table below |
Attribute sap:semantics
This attribute can take the following values in the context of edm.EntityType:
| Value | Meaning |
|---|---|
| vcard | Entities of this type contain contact information following the vCard standard, see values for sap:semantics on property level |
| vevent | Entities of this type contain event/appointment information following the iCalendar standard, see values for sap:semantics on property level |
| vtodo | Entities of this type contain todo/task information following the iCalendar standard, see values for sap:semantics on property level |
| parameters | This entity type represents parameters for an analytical query |
| aggregate | Entity sets with this type return result feeds with aggregated values for properties annotated with sap:aggregation-role="measure". The aggregation takes into account the dimension properties specified in the $select system query option of the request. See also description of annotation sap:aggregation-role. |
| variant | This entity type represents query selection variants bundling parameter selections and filter expressions for obtaining specific query results |
Element edm:Property
The annotation sap:label is required for properties. All other annotations are optional.
| Attribute Name | Default Value | Meaning / Type / Values |
|---|---|---|
| label | - | Description |
| semantics | - | See table below |
| creatable | true | Values for this property can be chosen by client when creating an instance. “False” if value is always set by the server, e.g. document number from number range. |
| updatable | true | Values of this property can be changed. Must be “false” if it is “false” at entity type level. |
| sortable | true | Can be used in $orderby system query option. |
| filterable | true | Can be used in $filter system query option. |
| required-in-filter | false | Must be used in $filter system query option. |
| filter-restriction | - | See table below |
| text | - | The name of a property in the same type containing a human-readable text for the value of this property. |
| unit | - | The name of a property in the same type containing the currency code or unit of measure for a numeric value. |
| precision | - | The name of a property in the same type containing the number of significant decimal places for a numeric value. |
| display-format | - | The value “Date” indicates that only the date part of an Edm.DateTime value is relevant. |
| visible | true | The property should be displayed by the user agent |
| lower-boundary | - | A property holding the upper boundary of a value range includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property holding the related lower boundary. |
| upper-boundary | - | A property holding the lower boundary of a value range includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property holding the related upper boundary. |
| aggregation-role | - | See table below |
| super-ordinate | - | If values of this property are meaningful (unique) only in the context provided by the value of another property, then this attribute holds the name of the context-providing property. The value of this attribute is always the name of another property in the same type. |
| attribute-for | - | A property representing an attribute of another property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property for which this property is an attribute. |
| hierarchy-node-for | - | A property holding node IDs for a hierarchy structure of values of some other property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property for whose values the hierarchy is defined. |
| hierarchy-level-for | - | A property holding level numbers for a hierarchy structure of values of some other property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property for whose values the hierarchy is defined. |
| hierarchy-parent-node-for | - | A property holding parent node IDs for a hierarchy structure of values of some other property includes this attribute. The value of this attribute is always the name of another property in the same type. It points to the property for whose values the hierarchy is defined. |
| hierarchy-drill-state-for | - | A property holding the drill state of a hierarchy node includes this attribute. The drill state is indicated by one of the following values: collapsed, expanded, leaf. The value of this attribute is always the name of another property in the same type. It points to the related property holding the hierarchy node ID. |
| parameter | - | See table below |
| is-annotation | false | Represents an instance annotation. |
| updatable-path | - | If a property can be updated or not depending on the state of its entity, it can be annotated with this attribute. The value of this attribute is always the name of a Boolean property in the same type. This related property indicates whether the annotated property can be updated for the containing entity or not. |
| preserve-flag-for | - | See below |
| filter-for | - | A property whose value is a $filter expression includes this attribute. The $filter expression must be valid for the entity type specified in this attribute. |
Attribute sap:unit
Amounts in a currency or absolute measures MUST be represented as simple properties with an appropriate numeric Edm type, preferably Edm.Decimal. These numeric properties SHOULD refer to a string property containing the currency unit or unit of measure through the sap:unit attribute. They MAY refer to a numeric property containing the (non-negative) number of decimal places to be used for displaying the amount or measure.Example in metadata document:
<Property Name="OrderedQuantity" Type="Edm.Int16"
sap:unit="OrderedUnit"/>
<Property Name="OrderedUnit" Type="Edm.String"/>
<Property Name="Price" Type="Edm.Decimal"Precision="10" Scale="3"
sap:unit="Currency"sap:precision="DisplayScale"/>
<Property Name="Currency" Type="Edm.String"/>
<Property Name="DisplayScale" Type="Edm.Byte"/>
sap:unit="OrderedUnit"/>
<Property Name="OrderedUnit" Type="Edm.String"/>
<Property Name="Price" Type="Edm.Decimal"Precision="10" Scale="3"
sap:unit="Currency"sap:precision="DisplayScale"/>
<Property Name="Currency" Type="Edm.String"/>
<Property Name="DisplayScale" Type="Edm.Byte"/>
Example in Atom entry:
<d:OrderedQuantity sap:unit="OrderedUnit">50</d:OrderedQuantity>
<d:OrderedUnit>KGM</d:OrderedUnit>
<d:Price sap:unit="Currency">86.9</d:Price>
<d:Currency>EUR</d:Currency>
<d:DisplayScale>2</d:DisplayScale>
<d:OrderedUnit>KGM</d:OrderedUnit>
<d:Price sap:unit="Currency">86.9</d:Price>
<d:Currency>EUR</d:Currency>
<d:DisplayScale>2</d:DisplayScale>
Using a reference attribute instead of predefined complex types like Measure or Money with amount and unit properties allows several amounts to share the same unit. Transporting the amounts as “raw” numeric values instead of preformatted strings allows clients to format them according to device-specific settings (that may well differ from the server-side user settings) or process them on the client (if e.g. the client is Excel).
Attribute sap:semantics
This attribute can take the following values in the context of a property:
| Value | Meaning |
|---|---|
| tel | Telephone number |
| tel;type=cell,work | Work cellphone number; see explanation below table for more values |
| tel;type=fax | Fax number |
| Email address | |
| email;tyype=pref | Preferred email address |
| url | Web URL |
| name | Formatted text of the full name |
| givenname | First name or given name of a person |
| middlename | Middle name of a peron |
| familyname | Last name or family name of a person |
| nickname | Descriptive name given instead of or in addtion to the one marked as "name" |
| honorific | Title of a person (Ph.D., Dr., ...) |
| suffix | Suffix to the name of a person |
| note | Supplemental information or a comment that is associated with the vCard |
| photo | URL of a photo of a person |
| city | Address: city |
| street | Address: street |
| country | Address: country |
| region | Address: state or province |
zip | Address: postal code |
| pobox | Address: post office box |
| org | Organization name |
| org-unit | Organizational unit |
| org-role | Organizational role |
| title | Job title |
| bday | Birth date |
| summary | Calendar: summary of a calendar component |
| description | Calendar: description of a calendar component, detailing the summary |
| categories | Calendar: comma-separated list of categories for a calendar component |
| dtstart | Calendar: the date and time that a calendar component starts |
| dtend | Calendar: the date and time that a calendar component ends |
| duration | Calendar: duration as an alternative to dtend |
| due | Calendar: the date and time that a to-do is expected to be completed |
| completed | Calendar: the date and time that a to-do was actually completed |
| priority | Calendar: the relative priority for a calendar component, 0 for undefined, 1 for highest, ... 9 for lowest |
| class | Calendar: access classification for a calendar component |
| status | Calendar: overall status or confirmation for the calendar component |
| percent-complete | Calendar: percent completion of a to-do., ranging from 0 to 100 (integer) |
| contact | Calendar: contact information or alternatively a reference to contact information associated with the calendar component |
| location | Calendar: the intended venue for the activity defined by a calendar component |
| transp | Calendar: defines whether or not an event is transparaent to busy time searches |
| fbtype | Calendar: free/busy time type, see [iCalendar, Section 3.2.9] |
| wholeday | Calendar: "true" or "false, depending on whether an event is scheduled for an entire day |
| from | Mail: author of message, see [RFC5322, section 3.6.2] |
| sender | Mail: mailbox of agent responsible for actual transmission |
| to | Mai: comma-separated list of primary recipients, see [RFC5322, section 3.6.3] |
| cc | Mail: carbon copy, comma-separated |
| bcc | Mail: blind carbon copy, comma-separated |
| subject | Mail: topic of the message |
| body | Mail: message body |
| keywords | Mail: comma-separated list of important words and phrases that might be useful for the recipient |
| received | Mail: DateTime the message was received |
| geo-lon | Geolocation: longitude |
| geo-lat | Geolocation: latitude |
| currency-code | ISO currency code |
| unit-of-measure | Unit of measure, preferably ISO |
For “tel” the type values are (see [vCard, section 6.4.1]):
- "home" to indicate a telephone number associated with a residence
- "work" to indicate a telephone number associated with a place of work
- “pref" to indicate a preferred-use telephone number
- "text" to indicate a telephone number supporting text messages (SMS)
- "voice" to indicate a voice telephone number
- "fax" to indicate a facsimile telephone number
- "cell" to indicate a cellular telephone number
- "video" to indicate a video conferencing telephone number
- "pager" to indicate a paging device telephone number
- "textphone" to indicate a telecommunication device for people with hearing or speech difficulties
For “email” the type values are:
- "home" to indicate an email address associated with a residence
- "work" to indicate an email address associated with a place of work
- “pref" to indicate a preferred-use email address
For “url” and constituents of an address the type values are:
- "home" to indicate an address associated with a residence
- "work" to indicate an address associated with a place of work
- “org" to indicate an address associated with the organization
- “pref” to indicate a preferred address “other” to indicate some other address
These type values can be specified as a value list (like "type=work,pref").
Attribute sap:filter-restriction
This attribute can take the following values in the context of a property:
| Value | Meaning |
|---|---|
| single-value | Only a single “eq”clause is possible. |
| multi-value | Several “eq” clauses, separated by or, are possible. |
| interval | At most one “ge” and one “le” clause, separated by “and”, alternatively a single “eq” clause. |
Attribute sap:aggregation-role
This attribute can take the following values in the context of a property:
| Value | Meaning |
|---|---|
| dimension | The property represents the key of a dimension. Only valid for properties of an entity type that is annotated with sap:semantics=“aggregate“. |
| measure | The property represents a measure whose values will be aggregated according to the aggregating behavior of the containing entity type. Only valid for properties of an entity type that is annotated with sap:semantics=“aggregate“. |
| totaled-properties-list | The property value is a comma-separated list of totaled dimension property names. |
Attribute sap:parameter
This attribute can take the following values in the context of edm.Property:
| Value | Meaning |
|---|---|
| mandatory | A value must be supplied for this parameter. |
| optional | A value for this parameter can be left out by specifying an empty string (applicable only for parameter properties of type Edm.String). |
Attribute sap:preserve-flag-for
A property holding the preservation state for another property includes this attribute.
The preservation state is a Boolean flag indicating whether or not the value of a named entity property is protected against updates causedby side-effects of updates to the entity set.
Example: Consider an entity set holding order items with unit price, quantity, and total amount. products All three properties supportspreservation, as shown here for the unit price:
<Property Name="UnitPrice" Type="Edm.Decimal"/>
<Property Name="UnitPricePreserveFlag" Type="Edm.Boolean"
sap:preserve-flag-for="UnitPrice"/>
<Property Name="UnitPricePreserveFlag" Type="Edm.Boolean"
sap:preserve-flag-for="UnitPrice"/>
For a given order item, a consumer can set the preservation flag for the total amount and update the unit price. This would instruct the provider to recalculate the quantity instead of the total amount.
Element edm:NavigationProperty
| Attribute Name | Default Value | Meaning / Type / Values |
|---|---|---|
| filterable | true | Can be used as a path segment for properties in $filter system query option |
Element edm:FunctionImport
| Attribute Name | Meaning / Type / Values |
|---|---|
| action-for | Value is the qualified name of an entity type in scope. Indicates that the function or action operates on instances of that entity type. The function import MUST have a required parameter for each key property of that entity type. Parameter name and type must be identical to the name and type of the corresponding key property. |
| label | Description |
Element edm:Parameter
| Attribute Name | Meaning / Type / Values |
|---|---|
| label | Description |
Element edm:AssociationSet
| Attribute Name | Default Value | Meaning / Type / Values |
|---|---|---|
| creatable | true | Relations can be created |
| updatable | true | Relations can be changed |
| deletable | true | Relations can be deleted |
Instance Annotations
An annotation of an element in the OData metadata document adds information at the structural level of the service. Sometimes extra pieces of information are needed in the OData response for individual entities and their properties. To distinguish these two cases the former are called metadata annotations, while annotations of the entities in the OData response are called instance annotations.
Metadata annotations add information to the model structure. They are fully described by adding the appropriate AnnotationElement or AnnotationAttribute to a model element.
For instance annotations, this is different, because it must be possible to add different annotation values for every entity or every entity property, respectively. Therefore, if instance annotations are relevant for instances of some entity type, the structure of the entity type gets extended by properties specifically added for the purpose of holding annotation values in the result entities. These extra properties are also annotated with sap:is-annotation=”true” to identify them as
annotation holders and separate them from the other properties of the entity type.
annotation holders and separate them from the other properties of the entity type.
A single entity can have multiple instance annotations, for each of which an extra property gets added to the underlying type:
- Zero or more for the entity itself.
- Zero or more for every property contained in the entity.
Properties representing instance annotations are always introduced by AnnotationAttributes in the metadata document. The following sections describe the possible occurrences.
Example:
<Property Name="Street" Type="Edm.String" Nullable="true"
sap:updatable-path="AddressIsUpdatable"/>
<Property Name="City" Type="Edm.String" Nullable="true"
sap:updatable-path="AddressIsUpdatable"/>
<Property Name="AddressIsUpdatable" Type="Edm.Boolean" Nullable="true"
sap:is-annotation="true"/>
Query Option search
Modern user interfaces typically feature a search box for entering a free-text search term, and how exactly this search term is used to find "matching" things is up to the application. The custom query option search is intended exactly for passing such a free-text search term to the backend and let the backend decide against which properties of each entity in the entity set the term is matched, and how. It may also be matched against properties of related entities, e.g.
GET ~/Orders?search=blue
to find all orders with items that refer to a blue product. Service implementations using SAP NetWeaver Gateway OData Channel will receive the search term in the parameter IV_SEARCH_STRING of method GET_ENTITYSET, see http://help.sap.com/saphelp_gateway20sp06/helpdata/en/7b/7ea4676342455c99072ce8815f799d/frameset.htm for details.