Working with Annotations

You can add annotations to data model artifacts to provide additional data or descriptive information about an artifact to specify how the data is to be displayed by an OData service. Use standard SAP annotations at design time to add semantics that describe certain behavior applicable to an artifact such as creatable, updatable or sortable, for example, or to provide consumption hints such as which fields form an address or which fields logically belong together, for example.

Annotations represent a consensus between the data model developer and the consumer of the data model as to how the data model is ideally to be used. While annotations provide precise instructions as to how a data model should be consumed they also act as an extension point to provide additional information that is useful for the consumption of the data model.

Two types of annotations exist:

• Annotations that describe the original parts of the data model (precision)

• Annotations that describe additional parts of the Entity Data Model (EDM) for the consumer (extension)

By annotating metadata and instance data at design time you have the flexibility to add more precise information about an artifact that would not otherwise be possible using the core SAP attributes alone. Some artifacts within a given data model will, for reasons of logic, not permit all the possible interactions that are supported by a given interface and you can use annotations to convey such restrictions in the data model definition. At entity type or entity set level, for example, you can use annotations to define whether the artifact is searchable or updatable and which properties may be used in filter expressions.

Annotations comprise the following key entries:

• Target (for example, entity type, entity set, complex type, property, or association to which the annotation applies)

• Term (entry that can define the artifact type (for example, Scale or Unit) or usage (for example, Countable, Navigable, Expandable))

• Qualifier (free qualifier that defines context)

An annotation is a combination of these three entries, which together result in the specific usage and/or presentation of a particular artifact instance. For this reason, only one annotation may exist for a particular artifact in a data model. Essentially, annotations provide you with much greater freedom to define more precise and explicit information about an artifact than the definition of core attributes alone can allow. Annotations are consolidated in vocabularies and care should be taken to ensure that newly defined annotations can be clearly understood by a wide audience.

When you create a new project in the Service Builder, you are required to define the project type:

• Choose Service with SAP Annotations to use core attributes (standard SAP extensions such as Creatable, Updatable, Label, UnitProperty).

• Choose Service with Vocabulary-Based Annotations or Annotation Model for Referenced Service to use annotations (customer-specific extensions) defined in separate vocabulary files.

  A central Vocabulary Repository exists (choose  Extras  Vocabulary Repository  in the Service Builder menu) that includes some standard vocabulary files in the /IWBEP/ namespace for vocabulary-based annotations, but you can also upload customer-specific vocabulary files for greater flexibility. Use the standard vocabulary files as a template for defining your own vocabulary files if required. You can import one or more of the vocabulary files from the Vocabulary Repository to your data model contained in the Service Builder project.

For more information about working with annotations, see:

• Creating a Service Builder Project

• Uploading Vocabularies into the Vocabulary Repository

• Adding Vocabulary-Based Annotations to Data Model Artifacts