Annotations Overview

OData annotations attach metadata to schema elements (types, properties, entity sets). They do not change query behavior; they tell clients how to present the data. A UI5 app on an OData V4 model reads them through the model's metadata, and SAP Fiori Elements (part of SAPUI5) builds whole pages from them.

What annotations are

An annotation binds a term to a value and applies that binding to a target element. Terms are defined by vocabularies (like Core, UI, Common, Capabilities).

Example in CSDL XML output:

<EntityType Name="Product">
  <Property Name="id" Type="Edm.Int64"/>
  <Property Name="name" Type="Edm.String"/>
  <Annotation Term="Org.OData.Core.V1.Description" String="A product in the catalog"/>
</EntityType>

Annotation values

The library supports three kinds of annotation values:

Type	Class	Example
Constant	ConstantAnnotationValue	A string, number, or boolean
Record	RecordAnnotationValue	A named set of properties (key-value pairs)
Collection	CollectionAnnotationValue	An ordered list of values

Qualifiers

When multiple annotations of the same term are applied to the same element, qualifiers disambiguate them:

new Annotation(
    term: 'com.sap.vocabularies.UI.v1.LineItem',
    qualifier: 'Table1',
    value: $lineItemValue,
);

How annotations get into the schema

There are two paths:

1. Automatic discovery — place vocabulary attributes (#[Description], #[Label], #[Hidden], etc.) on your Eloquent model classes and properties. When registered via discoverModel(), ModelDiscovery reads them and attaches them to the EntityType and Property objects automatically.

2. Programmatic — pass Annotation objects to the annotations parameter of EntityType, Property, and other Edm constructors when building the schema manually.

See Applying Annotations for details on both approaches, including the PHP 8.4 property hooks required for property-level attribute annotations on Eloquent models.

How clients consume annotations

A UI5 client can read annotations from the $metadata document to:

• Generate table columns from UI.LineItem
• Create form fields from UI.FieldGroup
• Apply display formats from UI.DisplayFormat
• Show labels from Common.Label
• Hide fields with UI.Hidden
• Declare capabilities with Capabilities.FilterRestrictions

In OpenUI5 your views and sap.ui.mdc delegates do this through the OData V4 model's ODataMetaModel, for example /Products/@com.sap.vocabularies.UI.v1.LineItem. SAP Fiori Elements, which ships with SAPUI5, does it without code.