OData services provide a uniform interface for interacting with their resources, and in addition are self-describing:
$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.
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 https://www.w3.org/2007/app, 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.
app:serviceThe 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.
app:collectionThe 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 search to 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.It can also contain the attribute sap:addressable with the same value as for the corresponding entity set in the 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. For binary attributes the meaning is described for the value true.
edm:SchemaSchemas 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.
| Attribute Name | Default Value | Meaning | Replaced by |
|---|---|---|---|
| schema-version | 0000 | A non-negative number indicating the version of the schema. This can be considered a sub/minor version of the service version. It should be incremented whenever additive changes are made in a subsequent shipment of the same service version, and it can be used by clients to detect whether the service meets their minimal data provisioning needs. | Core.SchemaVersion |
edm:EntityContainerEntity containers 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.
| Attribute Name | Default Value | Meaning |
|---|---|---|
| message-scope-supported | false | Service supports the request header sap-message-scope |
| supported-formats | atom json | A white-space separated list of format shortnames. Possible list items: • atom • json • xlsx The default is sap:supported-formats="atom json". |
| use-batch | false | Wrap all requests to resources of this service in batch requests; only the service document and the metadata document can be accessed unwrapped.This av oids exposing sensitive data in URLs (even with HTTPS URLs can be visible in log files) |
edm:EntitySetEntity 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 |
|---|---|---|
| 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. Must not be present if updatable-path is present. |
| updatable-path | - | Entities in this set can be updated or not depending on their state. The value of this attribute is a path expression that identifies a Boolean property in the context of the entity type of the entity set. The value of this property indicates whether the entity can be updated or not. Must not be present if updatable is present. See section below for details. |
| deletable | true | Entities can be deleted from this set. Must not be present if deletable-path is present. |
| deletable-path | - | Entities in this set can be deleted or not depending on their state. The value of this attribute is a path expression that identifies a Boolean property in the context of the entity type of the entity set. The value of this property indicates whether the entity can be deleted or not. Must not be present if deletable is present. See section below for details. |
| searchable | false | Supports custom query option search |
| pageable | true | Supports system query options $top and $skip |
| topable | true | Supports system query option $top |
| countable | true | Supports system query option $inlinecount=allpages and path suffix /$count |
| addressable | true | Use false if this entity set can only be accessed within its containing entity, e.g. Conditions within SalesOrders through SalesOrders(4711)/Conditions. Direct access to non-addressable entity collections will result in a 4xx response code. The set may however allow access to single entities identified by their key properties values, e.g. SalesOrderConditions(OrderID=4711,ConditionID=3) |
| 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 |
| change-tracking | false | Changes to entities of this set can be tracked. Consumers can subscribe by adding an HTTP Prefer header odata.track-changes to the request. The response will then include a delta link for requesting information about changes in the future. |
| maxpagesize | - | Maximum number of entities returned in an OData response. If more entities are included in the result of an OData request, the service applies server-driven paging. |
| delta-link-validity | - | The maximum duration in seconds a delta link in an OData response remains valid. Afterwards, resources associated with the change tracking subscription may be cleaned up and will be no longer available. |
| semantics | - | See table below |
updatable and updatable-pathThe combined meaning of the annotations updatable and updatable-path is:
updatable nor updatable-path, its entities can be updatedupdatable and updatable-path, the service is broken and the client should assume that entities in this set cannot be updatedupdatable=true, its entities can be updatedupdatable=false, its entities cannot be updatedupdatable-path, its entities can be updated depending on the value of the Boolean property identified with this path expression:
updatable-path points to a property that does not exist, the service is broken and the client should assume that the entity cannot be updatedupdatable-path points to a property that does not have the type Edm.Boolean, the service is broken and the client should assume that the entity cannot be updatedupdatable-path points to a property of type Edm.Boolean that exists, and this property has the value true, the entity can be updatedupdatable-path points to a property of type Edm.Boolean that exists, and this property has the value false, the entity cannot be updatedupdatable-path points to a property of type Edm.Boolean that exists, and this property has the value null, the service does not know whether the property can be updated. Semantically such a service is broken and the client should assume that the entity cannot be updatedThe same rules apply to the combination of deletable and deletable-path on entity sets and the combination of creatable and creatable-path on navigation properties.
sap:semanticsThis attribute can take the following values in the context of an entity type:
| Value | Meaning |
|---|---|
| aggregate | The entities of this set are automatically aggregated if the query option $select is specified. Each property listed in $select is treated according to its aggregation role. See description of attribute sap:semantics="aggregate" for Edm:EntityType below. |
| timeseries | The entities of this set are snapshots of data that changes over time. One of the key properties represents the temporal dimension. |
edm:EntityTypeEntity types can be annotated with the following attributes:
| Attribute Name | Meaning |
|---|---|
| label | Description, will also be used as sap:member-title in the service document |
| semantics | See table below |
sap:semanticsThis attribute can take the following values in the context of an entity type:
| 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 another entity type to which it has a collection-valued association |
| aggregate | Entity sets of a type with this semantics return result feeds with aggregated values for properties annotated with sap:aggregation-role="measure" mentioned in the $select system query option. The result consists of entities for all combinations of distinct values of all dimension properties annotated with sap:aggregation-role="dimension" mentioned in the \(select system query option of the request matching the `\)filterexpression. See also description of annotationsap:aggregation-role`. |
| variant | This entity type represents query selection variants bundling parameter selections and filter expressions for obtaining specific query results |
edm:PropertyThe annotation sap:label is required for properties. All other annotations are optional.
| Attribute Name | Default Value | Meaning |
|---|---|---|
| label | - | A short, human-readable text suitable for labels and captions in UIs |
| heading | - | A short, human-readable text suitable for column headings in UIs |
| quickinfo | - | A human-readable text suitable for tool tips in UIs |
| 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 set level. If updatability can change per entity or based on the entities' state, do not use this static annotation and use sap:field-control instead. |
| 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 | - | A path expression that identifies a property in the context of the entity type containing a human-readable text for the value of this property. |
| unit | - | A path expression that identifies a property in the context of the entity type containing the currency code or unit of measure for a numeric value. |
| precision | - | A path expression that identifies a property in the context of the entity type containing the number of significant decimal places for a numeric value. |
| visible | true | Values of this property are typically visible to end users. If visibility can change per entity or based on the entities' state, do not use this static annotation and use sap:field-control instead. |
| field-control | 3 | A path expression that identifies a property containing a numeric value that controls visibility: • 0 = hidden, • 1 = read-only, • 3 = optional, • 7 = mandatory See section below for details |
| validation-regexp | - | Values for this property have to match the specified regular expression. The regular expression is a JavaScript Regular Expression. |
| display-format | - | There are currently three possible values: • Date indicates that only the date part of an Edm.DateTime value is relevant• NonNegative indicates that only non-negative numeric values are provided and persisted, other input will lead to errors. Intended for Edm.String fields that are internally stored as NUMC• UpperCase indicates that uppercase values are provided and persisted, lowercase input will be converted |
| value-list | - | A string indicating whether this property has a value list attached: • fixed-values - there is a short list of allowed field values that rarely changes over time • standard - no restriction on number and volatility of allowed field values The list of allowed values is provided as a separate entity set that can be found by interpreting the V4-style annotation Common.ValueList on the same property. |
| 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 non-key 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. An OData request with a $filter condition testing equality of a property holding hierarchy node IDs with a specific node ID selects all entities in the sub-hierarchy with the root node identified by the given node ID. |
| hierarchy-node-external-key-for | - | A property holding the external key of a hierarchy node includes this attribute. The external key is a human-readable identification of a node. 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. |
| 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 related property holding the hierarchy node ID. A property holding level numbers has an integer data type. The root node of the hierarchy is at level 0. |
| 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 related property holding the hierarchy node ID. For the root node of the hierarchy the parent node ID is null. |
| hierarchy-parent-navigation-for | - | A navigation property for accessing the parent entity of a node. It offers an alternative method for accessing the parent node ID, if the entity type does not have a dedicated property for that. |
| 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. For an expanded node, its children are included in the result collection. For a collapsed node, the children are included in the entity set, but they are not part of the result collection. Retrieving them requires a relaxed filter expression or a separate request filtering on the parent node ID with the ID of the collapsed node. A leaf does not have any child in the entity set. |
| hierarchy-node-descendant-count-for | - | A property holding the descendant count for a hierarchy node includes this attribute. The descendant count of a node is the number of its descendants in the hierarchy structure of the result considering only those nodes matching any specified $filter and $search. 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. A property holding descendant counts has an integer data type. |
| hierarchy-preorder-rank-for | - | A property holding the preorder rank for a hierarchy node includes this attribute. The preorder rank of a node expresses its position in the sequence of nodes created from preorder traversal of the hierarchy structure after evaluating the $filter expression in the request excluding any conditions on key properties. 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. A property holding preorder ranks has an integer data type. The first node in preorder traversal has rank 0. |
| hierarchy-sibling-rank-for | - | A property holding the sibling rank for a hierarchy node includes this attribute. The sibling rank of a node is the index of the node in the sequence of all nodes with the same parent created by preorder traversal of the hierarchy structure after evaluating the $filter expression in the request excluding any conditions on key properties. 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. A property holding sibling positions has an integer data type. The first sibling is at position 0. |
| 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 a path expression that identifies a Boolean property in the context of the entity type. This related property indicates whether the annotated property can be updated for the containing entity or not. Note: if used in addition to the more expressive field-control annotation, the values of the two must be in sync. |
| 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. |
| variable-scale | false | A property of type Edm.Decimal that does not have a Scale facet and is annotated with true will contain floating-point values.This indicates that the underlying data store field uses a data type with decimal mantissa and variable or floating scale which cannot be expressed in the OData V2 type system. Note: omitted Scale for type Edm.Decimal usually means Scale="0", restricting the value range to integers. |
| text-for | - | A data type with decimal mantissa and variable or floating scale that identifies a property in the context of the entity type for which this property provides an additional human-readable text. |
sap:unit and sap:precisionAmounts 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 ISO currency or unit of measure with 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 with the sap:precision attribute.
Example in metadata document:
<Property Name="OrderedQuantity" Type="Edm.Int16" sap:unit="OrderedUnit" />
<Property Name="OrderedUnit" Type="Edm.String" sap:semantics="unit-of-measure" />
<Property Name ="Price" Type ="Edm.Decimal" Precision="10" Scale ="3" sap:unit ="Currency" sap:precision="DisplayScale" />
<Property Name="DisplayScale" Type ="Edm.Byte" />
<Property Name="Currency" Type ="Edm.String" sap:semantics="currency-code" sap:text="CurrencyText" />
<Property Name="CurrencyText" Type="Edm.String" />Example in Atom entry:
<d:OrderedQuantity>50</d:OrderedQuantity>
<d:OrderedUnit>KGM</d:OrderedUnit>
<d:Price>86.9</d:Price>
<d:DisplayScale>2</d:DisplayScale>
<d:Currency>EUR</d:Currency>
<d:CurrencyText>Euro</d:CurrencyText>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).
sap:field-controlWhether a property can or must contain a value may depend on the state of its entity, so it is impossible to express this up-front via metadata annotations. In these cases the "edit state" of the property can be expressed via a separate "field control" property, and the link between data properties and their field-control properties is expressed with the sap:field-control attribute.
Example in metadata document:
<Property Name="Street" Type="Edm.String" sap:field-control="Address_fc" />
<Property Name="City" Type="Edm.String" sap:field-control="Address_fc" />
<Property Name="Address_fc" Type="Edm.Byte" />The field-control property can be in the same type as shown above, or it can be in a nested complex type, or in an entity type that is associated 1:1. This allows separating field-control data from "real" data. If for example the field-control property is contained in a complex property or navigation property named fc, the attribute value is a path relative to the parent of the annotated property, e.g. sap:field-control="fc/Address".
The possible values for a field-control property are:
| Value | Meaning |
|---|---|
| 7 | Mandatory - property must contain a value |
| 3 | Optional - property may contain a null value |
| 1 | Read-only - property cannot be changed |
| 0 | Hidden - property should not be visible on user interfaces |
sap:semanticsThe possible values in the context of a property are:
| 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;type=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 person |
| 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, see xs:duration |
| 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 |
| year | Calendar: year as string following the regex pattern (-?)YYYY(Y*) consisting of an optional minus sign for years B.C. followed by at least four digits |
| yearmonth | Calendar: year and month as string following the regex pattern (-?)YYYY(Y*)MM consisting of an optional minus sign for years B.C. followed by at least six digits, the last two digits are a number between 01 and 12 representing the months January to December |
| yearmonthday | Calendar: year, month and day as string following the logical pattern (-?)YYYY(Y*)MMDD consisting of an optional minus sign for years B.C. followed by at least eight digits, where the last four digits represent the months January to December (MM) and the day of the month (DD). The string matches the regex pattern -?([1-9][0-9]{3,}│0[0-9]{3})(0[1-9]│1[0-2])(0[1-9]│[12][0-9]│3[01]). The regex pattern does not reflect the additional constraint for "Day-of-month Values": The day value must be no more than 30 if month is one of 04, 06, 09, or 11, no more than 28 if month is 02 and year is not divisible by 4, or is divisible by 100 but not by 400, and no more than 29 if month is 02 and year is divisible by 400, or by 4 but not by 100 |
| 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 | Currency code, preferably ISO |
| unit-of-measure | Unit of measure, preferably ISO |
| count | Aggregation: the number of unaggregated entities that have been aggregated into the response entity (count(*) in SQL). Only valid for one property of an entity type that is annotated with sap:semantics="aggregate". |
For tel the type values are (see vCard, section 6.4.1:
home to indicate a telephone number associated with a residencework to indicate a telephone number associated with a place of workpref to indicate a preferred-use telephone numbertext to indicate a telephone number supporting text messages (SMS)voice to indicate a voice telephone numberfax to indicate a facsimile telephone numbercell to indicate a cellular telephone numbervideo to indicate a video conferencing telephone numberpager to indicate a paging device telephone numbertextphone to indicate a telecommunication device for people with hearing or speech difficultiesFor email the type values are:
home to indicate an email address associated with a residencework to indicate an email address associated with a place of workpref to indicate a preferred-use email addressFor url and constituents of an address the type values are:
home to indicate an address associated with a residencework to indicate an address associated with a place of workorg to indicate an address associated with the organizationpref to indicate a preferred addressother to indicate some other addressThese type values can be specified as a value list (like type=work,pref).
sap:filter-restrictionA property can be annotated with this attribute, if filter restrictions exist. The attribute can take the following values:
| 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. |
sap:aggregation-roleA property can be annotated with this attribute, if it has an aggregation role. The attribute can take the following values:
| Value | Meaning |
|---|---|
| dimension | The property represents the key of a dimension and is used to control the aggregating behavior. 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. |
sap:parameterA property can be annotated with this attribute, if it represents a parameter. The attribute can take the following values:
| 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). For parameters of other types, the default value conveyed in the metadata should be assigned, if the parameter shall be omitted. |
sap:preserve-flag-forA 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. All three properties supports preservation, as shown here for the unit price:
<Property Name="UnitPrice" Type="Edm.Decimal" />
<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.
edm:NavigationProperty| Attribute Name | Default Value | Meaning |
|---|---|---|
| creatable | true | New related entities can be created |
| creatable-path | - | Related entities can be created or not depending on the state of the source entity. The value of this attribute is a path expression that identifies a Boolean property in the context of the source entity type. The value of this property indicates whether related entities can be created or not. See section Combined Meaning for combined meaning of creatable and creatable-path. |
| filterable | true | Can be used as a path segment for properties in $filter system query option |
edm:FunctionImport| Attribute Name | Meaning |
|---|---|
| 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. |
| applicable-path | Value is a path to a Boolean property in the entity type named in the action-for attribute. The property indicates whether the function import can be invoked for the entity. The path can be the name of a Boolean property, or the name of a complex property followed by a forward slash and the path to a Boolean property in the complex type. |
| label | Description |
| planning-function | This function processes or generates plan data that may be exposed by entity sets of aggregate entity types in the same service. Its logic may have side-effects on these entity sets. |
Example: a function import that allows approving a leave request. The LeaveRequest entity type has a single key property ID and a complex property ControlData with a Boolean property NeedsApproval that controls the applicability of two alternative actions, approval and rejection:
<FunctionImport Name="LeaveRequestApproval"
ReturnType="ThisModel.ApprovalResult"
m:HttpMethod="POST"
sap:label="Approve"
sap:action-for="ThisModel.LeaveRequest"
sap:applicable-path="ControlData/NeedsApproval">
<Parameter Name="ID" Type="Edm.Guid" Mode="In" />
</FunctionImport>
<FunctionImport Name="LeaveRequestRejection"
ReturnType="ThisModel.ApprovalResult"
m:HttpMethod="POST"
sap:label="Reject"
sap:action-for="ThisModel.LeaveRequest"
sap:applicable-path="ControlData/NeedsApproval">
<Parameter Name="ID" Type="Edm.Guid" Mode="In" />
<Parameter Name="Reason" Type="Edm.String" Mode="In" />
</FunctionImport>A function import can optionally include an annotation with an sap:value-constraint element.
sap:value-constraintThis element describes a dependency of function import parameters to key properties of an entity set, comparable to a referential constraint. Example: For a function import with two parameters for country and region, the possible arguments can be determined via some Regions entity set.
<sap:value-constraint set="Regions">
<sap: parameter-ref name="Country" />
<sap:parameter-ref name="Region" />
</sap:value-constraint>It has a set attribute that identifies the entity set containing the list of allowed parameter value combinations.
Nested sap:parameter-ref elements link the function import parameters specified with the name attribute to a key property of the entity type of the specified entity set. The sequence of sap:parameter-ref elements matches the sequence of the edm:PropertyRef elements of the Key element.
edm:Parameter| Attribute Name | Meaning |
|---|---|
| label | Description |
| variable-scale | A parameter of type Edm.Decimal that does not have a Scale facet and is annotated with true will accept floating-point values.This indicates that the underlying data store field has type DECFLOAT, which cannot be expressed in the OData V2 type system. Note: omitted Scale for type Edm.Decimal usually means Scale="0", restricting the value range to integers. |
edm:AssociationSet| Attribute Name | Default Value | Meaning |
|---|---|---|
| creatable | true | Relations can be created |
| updatable | true | Relations can be changed |
| deletable | true | Relations can be deleted |
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. A single entity can have multiple instance annotations, for each of which an extra property gets added to the underlying type:
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:field-control="Address_FC" />
<Property Name="City" Type="Edm.String" Nullable="true" sap:field-control="Address_FC" />
<Property Name="Address_FC" Type="Edm.Byte" Nullable="true" sap:is-annotation="true" />searchModern 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=blueto 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 SAP Gateway Foundation Developer Guide for details. Note that search works similar to $filter: it will return a subset of the entities that are returned when no search term is specified. And it combines with $filter, returning only entities that fulfill both conditions.
Entities can be organized in a tree if the underlying type contains additional properties allowing to determine the position of each entity in that tree. These are:
node ID property is annotated with hierarchy-node-forhierarchy-parent-node-forhierarchy-parent-navigation-forIn addition, further useful hierarchy information can be added via properties annotated with hierarchy-level-for, hierarchy-external-key-for, hierarchy-drill-state-for, hierarchy-node-descendant-count, hierarchy-preorder-rank-for, and hierarchy-sibling-rank-for.
If a request against an entity set with annotated hierarchy addresses the node ID property of a hierarchy in $select, the provider should ensure that the query result is a well-formed partial tree of that hierarchy. This means that for every entity in the result its ancestors in the hierarchy are also part of the result; the result should not contain any dangling hierarchy nodes.
If the request includes a $filter expression with a condition testing equality of the node ID property with a specific node ID, the result is a sub-hierarchy whose root node is identified by the given node ID. The result can contain multiple sub-hierarchies if the $filter expression has multiple equality conditions for specific node IDs, combined with or. For a $filter expression with a parent filter condition testing the parent node ID property or the node ID property reached via the parent navigation property against a literal node ID, the result is the set of child nodes matching the condition.
A $filter expression is processed first to determine the set of matching entities, which is then enriched with additional node entities needed to complete all hierarchy paths as appropriate: from the matching entities up to the root node entity of a selected sub-hierarchy, or up to the root of the entire hierarchy, or in case of parent filter condition or an equality condition on the hierarchy level no further nodes are added to the result.
A result should contain the entities in pre-order for the selected sub-hierarchies, or for the entire hierarchy if not filtered to sub-hierarchies. The sort order of sibling node entities in the result can be controlled with $orderby.