Introduction to Annotation tags and properties in OData

 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:

  • 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

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:

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

    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

Previous
Next Post »