Introduction to Annotations & Vocabularies

Introduction

Annotations can be used to specify an individual fact about an element, such as whether it is read-only, or to define a common concept, such as a person or a book. Applied annotations consist of a term (the namespace-qualified name of the annotation being applied), a target (the model or instance element to which the term is applied), and a value. The value may be a static value, or an expression that may contain a path to one or more properties of an annotated entity. Annotation terms are defined in metadata and have a name and a type. A set of related terms in a common namespace comprises a Vocabulary.

What is Vocabularies?

Vocabularies provide the ability to annotate metadata as well as instance data, and define a powerful extensibility point for OData. Metadata annotations can be used to define additional characteristics or capabilities of a metadata element, such as a service, entity type, property, function, action or parameter. For example, a metadata annotation may define ranges of valid values for a property. Metadata annotations appear in $metadata. Instance annotations can be used to define additional information associated with a result, entity, property, or error; for example, whether a property is read-only for a instance.

Annotations are a powerful way of extending OData services. By annotating a service you add information that tells clients how to interpret the service and its data. This additional information can be purely static and descriptive, or it can be dynamic, i.e. a “formula” that allows clients to compute new data from the data provided by the service. And it can be provided by the service designer and embedded in the service’s metadata, or it can be provided by someone else as a separate web resource that references the annotated service.

How to create annotations: In its simplest form you just tag parts of a service to tell clients how to interpret a piece of data. For example, the OData Core vocabulary defines a term IsLanguageDependent. Tagging a string-valued property with this term tells clients that the value they receive may depend on the Content-Language of the response they got. A more business-related use case is marking a numeric property as a monetary amount and linking the amount to its currency. With OData 2.0 we had to invent SAP-specific annotations to express business semantics. A typical example of an annotated metadata document would look like this:

 <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” Scale=“3” 
          sap:unit=“Currency” sap:precision=“DisplayScale” />
<Property Name=“DisplayScale” Type=“Edm.Byte” />
<Property Name=“Currency” Type=“Edm.String” MaxLength=“3”
          sap:semantics=“currency-code” sap:text=“CurrencyText” />
<Property Name=“CurrencyText” Type=“Edm.String” />

The drawback of using custom annotations was that non-SAP client libraries at best gracefully ignore these SAP annotations, but to consume these annotations we had to provide SAP-specific libraries or library extensions, reducing some of the benefit we get from using a standardized protocol.

Conclusion

All annotations are expressed as <Annotation> elements that name the term that is applied to a model element as well as the value for this term. Here the value is described by the Path attribute, meaning “follow this path in the current entity to find the value for the term”, i.e. the consumer now knows that the ISO currency for the amount in the Price property can be found in the Currency property next to the Price property etc.

In next blog a detailed explanation about the annotation property and it’s tags detailed overview.

Technical Articles

Introduction to Annotations & Vocabularies

Introduction

Assigned Tags