Skip to Content
Technical Articles

Introduction to Annotation Tags and Properties

Introduction

OData services provide a uniform interface for interacting with their resources, the service metadata document (located at the address $metadata relative to the service root) describes the structure of all resources in the 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.

In annotation individual tags which will be used in vocabulary-based annotation can be described below

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.

 

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:

  • 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 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

 

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.

 

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

 

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:

  • “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.

parameter See table below

 

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).

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

 

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.

 

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.

 

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

 

Above mentioned properties which will be populated in the service in the subsequent blogs and defines the property of the columns which is being used in UI fields. In the next blog, how these annotation can be used in defining the service via ABAP gateway builder.

References:

 

Few of my other blogs:-

Be the first to leave a comment
You must be Logged on to comment or reply to a post.