In
this blog, we will cover the basic concept of annotation tags and properties.
The
OData service metadata describes the structure of all resources in the service.
It 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 such area is semantic annoations, 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.
Another such area is 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.
In annotation individual tags which will be used in
vocabulary-based annotation can be described below:
1) Element edm:Schema
Schemas 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 |
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. |
2) Element edm:EntityContainer
Entity
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 |
supported-formats |
atom json |
A white-space separated list of format
shortnames. Possible list items:
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 avoids exposing sensitive data in
URLs (even with HTTPS URLs can be visible in log files) |
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. |
deletable |
true |
Entities can be deleted from this set. Must
not be present if deletable-path is present. |
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 |
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. |
semantics |
– |
See table below |
3) 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 sap:semantics
This
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:aggregation-role below |
timeseries |
The entities of this set are snapshots of
data that changes over time. One of the key properties represents the
temporal dimension. |
4) Element edm:EntityType
Entity
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 |
Attribute sap:semantic
This
attribute can take the following values in the context of an entity type:
Value |
Meaning |
parameters |
This entity type represents parameters for
another entity type to which it has a collection-valued association |
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 |
5) Element edm:Property
The
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 |
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. |
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. |
display-format |
– |
There are currently three possible values:
|
value-list |
– |
A string indicating whether this property
has a value list attached:
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. |
parameter |
– |
See table below |
a) Attributes sap:unit and sap:precision
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 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 pre-formatted
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).
b) Attribute sap:semantics
The
possible values in the context of a property are:
Value |
Meaning |
url |
Web URL |
name |
Formatted text of the full name |
org |
Organization name |
org-unit |
Organizational unit |
org-role |
Organizational role |
title |
Job title |
c) Attribute sap:aggregation-role
A
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. 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. |
d) Attribute sap:parameter
A
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). 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. |
6) Element 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 |
ConversionConversion EmoticonEmoticon