How to Work with OData V3 Annotations

A brief on Annotations.

An annotation is metadata (for example, a comment, explanation, and presentational markup) attached to text, image, or other data. Often annotations refer to a specific part of the original data.

An annotation consists of:

A Target: The construct against which the annotation is applied. May be any model construct (type, property, and many more).

A Term: The global name of the annotation. For example org.odata.display.Title

A Value: The value for the annotation. May be a static value, path or expression.

A Vocabulary: Is a set of terms in a common namespace.

SAP Gateway SP07 supports a certain set of vocabularies. These vocabularies define Measure, Capabilities, Core types, and so on.

Annotations can be defined in stand-alone annotation files or in-place as part of a service's metadata document, as shown in the examples below:

<Annotations Target="ExampleModel.Person">
        <!- TypeAnnotation always within Annotations element ->
        <TypeAnnotation Term="Validation.Range">
          <PropertyValue Property="Min" Decimal="16" Path="Age"/>
        </TypeAnnotation>
      </Annotations>

      <Annotations Target="ExampleModel.Material">
        <TypeAnnotation Term="Market.Product">
          <PropertyValue Property="Title" Path="Name"/>
          <PropertyValue Property="Description" Path="Description"/>
          <PropertyValue Property="Reviews" Path="CustomerFeedback"/>
          <NavigationProperty Name=CustomerFeedback"
ToRole="CustomerFeedback" FromRole="Material" Relationship="ExampleModel.MaterialFeedback" />
        </TypeAnnotation>
      </Annotations>

<EntityType Name="Person">
        <!- ValueAnnotation always within annotated metadata element ->
        <ValueAnnotation Term="Display.Title" Path="LastName"/>
        <Key>
          <PropertyRef Name="PersonId"/>
        </Key>
        <Property Name="PersonId" Type="Int32" Nullable="false"/>
        <Property Name="FirstName" Type="String" Nullable="true"/>
        <Property Name="LastName" Type="String" Nullable="true"/>
        <Property Name="Age" Type="Int32" Nullable="true">
          <!- DefaultValue="true" is used if no value is given in annotation ->
          <ValueAnnotation Term="Display.Hide"/>
        </Property>
      </EntityType>

Expressions are described as core and extended expressions. Core expressions are required to be supported by any Entity Data Model (EDM) client.