Annotations Overview

OData annotations attach metadata to schema elements (types, properties, entity sets). They do not change query behavior but provide hints to clients -- especially SAP UI5 SmartControls, which use annotations to auto-generate UIs.

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

SAP UI5 reads 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