Introduction to Annotation Tags and Properties

rajnish_tiwari2 · ‎2019 Feb 25

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: