UI Annotations
UI annotations are metadata terms from SAP's OData UI vocabulary, such as UI.LineItem, UI.SelectionFields and UI.HeaderInfo, that describe how data should be presented: which columns a table shows, which fields appear in the filter bar and what an object page header displays. SAP Fiori elements reads them at runtime and renders the page accordingly.
Quick facts
- Type
- OData vocabulary annotations (SAP UI vocabulary)
- Layer
- Services & APIs, authored in the data model, consumed by the UI
- Where defined
- ABAP CDS (preferably metadata extensions), CAP CDS files, or local XML annotation files in the app
- Consumed by
- SAP Fiori elements for OData V2 and V4
- Tooling
- ABAP Development Tools; SAP Fiori tools in VS Code or SAP Business Application Studio
- Who works with it
- ABAP and CAP developers, SAP Fiori developers
- Applies to
- SAP S/4HANA (all deployment options), SAP BTP
Layer: Services & APIsWhere it sits ▾
Layer: Services & APIs
Also touches: Business logic & data model, UI applications
Open the architecture map →How do UI annotations work?
UI annotations travel from the data model to the screen in four steps:
- A developer annotates entities and fields in the back-end model: ABAP CDS in SAP S/4HANA or the SAP BTP ABAP environment, or CDS files in a CAP project.
- When the model is exposed as an OData service, the back end translates those annotations into OData vocabulary terms in XML, delivered with the service metadata or as a separate annotation document.
- The SAP Fiori elements app loads the service metadata plus any additional annotation sources declared in its app descriptor (manifest.json).
- The floorplan templates, such as the list report and the object page, read the terms and build the page: table columns from UI.LineItem, filter fields from UI.SelectionFields, the object page title from UI.HeaderInfo.
SAP describes the UI vocabulary as being about how data is used in a user interface, not about specific UI controls, which is why the same annotation can drive a desktop table and a phone list. UI annotations are therefore a contract between the service and the template, not code that the app executes.
Which UI annotations matter most?
| OData term | What it controls | ABAP CDS notation |
|---|---|---|
| UI.LineItem | Columns of a table or list | @UI.lineItem on each element, with a position |
| UI.SelectionFields | Fields shown by default in the filter bar | @UI.selectionField on each element |
| UI.HeaderInfo | Object type name and title in the object page header | @UI.headerInfo on the entity |
| UI.Facets | Sections of the object page | @UI.facet |
| UI.Identification, UI.FieldGroup | Groups of fields shown in object page sections | @UI.identification, @UI.fieldGroup |
| Common.Label, Common.Text | Field labels and descriptive texts | @EndUserText.label, @ObjectModel.text.element |
Two details save time. ABAP CDS uses element-level notation that the service exposure turns into the entity-level OData term. And one term can exist several times with different qualifiers, for example two line items for two tables. Learning these six families covers most of what a list report and object page need from UI annotations.
Where are UI annotations defined?
- ABAP CDS (RAP and its predecessor model): UI annotations can sit in the data definition or in a metadata extension. SAP recommends metadata extensions, which keep the data model readable and let UI metadata evolve separately.
- CAP: annotations are written in CDS with
annotate ... with @(...), using the OData term names directly; CAP recommends separate .cds files in the app folders, apart from the service definition. - Local annotation file: an XML file inside the SAP Fiori app, registered as an additional annotation source in manifest.json.
- Older SAP Gateway services (OData V2): annotations modeled in the Service Builder (SEGW) vocabulary repository, or provided by an annotation provider class registered with /IWBEP/REG_VOCAN.
When the same term exists in a local file and in the back end, the local definition replaces the back-end one term by term. SAP's guidance is to keep UI annotations in the back end, next to the data model and with its lifecycle, and to use local files when there is no back-end access or a single app needs an override.
Why don't my UI annotations show up in the app?
Work from the service outward before touching the UI:
- Check the service metadata. Open the metadata or annotation document of the service and search for the term. If it is not there, the problem is in the back end.
- Check the service binding type (RAP). A binding of category Web API carries no UI-specific metadata. A Fiori elements app needs a UI binding.
- Check the metadata extension. The entity must allow extensions with
@Metadata.allowExtensions: true, and the extension must be active. - Check for a local override. A UI.LineItem in a local annotation file replaces the whole back-end UI.LineItem, so a column added in CDS never appears.
- Check qualifiers. A qualified annotation is only used where the qualifier is referenced.
- Clear caches. Gateway metadata caches and the browser can serve old metadata. Run /IWFND/CACHE_CLEANUP on the SAP Gateway hub and /IWBEP/CACHE_CLEANUP in the back end (both in an embedded system), then reload the app.
Most missing UI annotations are exposure or precedence problems, not syntax errors.
Where do UI annotations stop?
UI annotations are the reason SAP Fiori elements apps can be built quickly and look consistent: the layout follows the SAP Fiori design guidelines, accessibility and responsiveness come with the template, and the app stays stable across SAPUI5 upgrades because it contains little code.
The same design draws the limits:
- Only what the template supports. Annotations select and arrange; they cannot invent a layout the floorplan does not offer. Anything beyond needs extension points or freestyle SAPUI5.
- Presentation, not behavior. Validations, actions and authorization logic live in RAP or CAP; an annotation can display a button, not implement it.
- Spread across layers. Back-end files, metadata extensions and local files combine at runtime, which makes reviewing the final result harder.
- Drift risk. Local annotations break silently when a property is renamed in the back end.
UI annotations work best when the team treats them as part of the data model and reviews them with it.
UI annotations in ABAP CDS vs. CAP CDS vs. a local annotation file: what is the difference?
| ABAP CDS (RAP) | CAP CDS | Local annotation file | |
|---|---|---|---|
| Where written | Data definition or metadata extension in the ABAP system | CDS files in the CAP project | XML file inside the SAP Fiori app |
| Notation | @UI annotations, partly element-level (e.g. @UI.lineItem) | OData term names (e.g. UI.LineItem) | OData XML (Annotation Term="UI.LineItem") |
| Lifecycle | Transported with the data model | Deployed with the CAP service | Deployed with the UI app |
| Precedence | Overridden term by term by local files | Overridden term by term by local files | Wins for the terms it defines |
| Best for | Reusable UI metadata for SAP S/4HANA and ABAP services | Services and apps built on SAP BTP | Single-app overrides or no back-end access |
All three produce the same OData terms; the choice decides who owns the UI metadata and how far it is reused.
FAQ
Are UI annotations the same as CDS annotations?
No. CDS annotations are a broad family that also covers ABAP catalog settings, access control, analytics and OData exposure. UI annotations are the subset that describes presentation for SAP Fiori elements, written as @UI annotations in ABAP CDS or as UI vocabulary terms in CAP and XML.
Do local annotations override back-end annotations?
Yes, term by term. If a local annotation file defines UI.LineItem for an entity, that definition replaces the back-end UI.LineItem completely, while back-end terms the local file does not define stay in effect.
Which tools help write UI annotations?
SAP Fiori tools in Visual Studio Code and SAP Business Application Studio offer the Page Map, Guided Development and annotation editors for CAP CDS and XML files. For ABAP CDS, Guided Development helps generate the annotations, and ABAP Development Tools validates them.
Can UI annotations be added to an SAP-delivered SAP Fiori elements app?
Yes, through an adaptation project when the app is enabled for it. The adaptation project can add local annotation files without modifying the SAP-delivered app or its back-end service.
Do UI annotations work with both OData V2 and OData V4?
Yes. SAP Fiori elements exists for OData V2 and OData V4 and both read UI annotations, but the supported terms and features differ between the two stacks, so check the documentation of the OData version the app uses.
Sources
- SAPUI5 SDK: Working With OData Annotations (SAP Fiori elements for OData V4)
- SAPUI5 SDK: Working With OData Annotations (SAP Fiori elements for OData V2)
- SAP Help Portal: Defining CDS Annotations for Metadata-Driven UIs (ABAP RESTful Application Programming Model)
- SAP Help Portal: Service Binding (binding types and UI vs. Web API)
- SAP Help Portal: Metadata Cache (SAP Gateway Foundation, hub and backend caching)
- Applies to
- SAP S/4HANA on-premise · SAP S/4HANA Cloud Private Edition · SAP S/4HANA Cloud Public Edition · SAP BTP
- Last reviewed