CDS Annotations: Layers, Precedence and Silent Failures

CDS annotations are metadata tags attached above a CDS statement or field, written as @Namespace.property: value. They do not move data and do not execute; they describe how an entity should be interpreted by something downstream - the OData metadata document generator, the Fiori elements rendering engine, the CDS access control framework, or the analytics engine that decides how aggregation happens. The one structural fact that explains most confusion: annotations are consumed at different points in the lifecycle by different actors. Some are resolved at CDS activation time by the ABAP compiler, some are baked into the OData $metadata payload only when the service is generated or republished, and some are read live by Fiori elements every time it renders a floorplan. An annotation placed on the wrong view, or sitting in a metadata extension that was never activated against the right consuming service, does not raise an activation error. It is silently ignored, which is why tickets read 'I added the annotation, nothing changed' rather than 'I got an error'.

Use annotations to declare facts about data and its intended presentation rather than to write logic: field labels, list report columns, value helps, semantic typing of amounts and quantities, criticality colouring, filter defaults, and exposure decisions for a service. Put them at the layer closest to the thing they affect - UI-facing annotations on the projection or consumption view actually bound to the app, semantic annotations (currency, unit, language dependency) on the interface or basic view since those are facts about the data independent of any UI. Reaching for annotations to implement conditional behaviour - show this field only if that field has a certain value, computed at runtime based on business logic - is a mistake; that belongs in determinations, virtual elements or the app's own UI logic, not in a static tag. Annotating a reused interface view with UI-specific tags meant for one consuming app is also a mistake, because every other projection built on that view inherits the same UI decision whether it wants it or not.

Below annotations sit the CDS entities themselves - view entities, table functions, associations - the things annotations attach to. Above sit the consumers: the OData service metadata generator invoked when a service definition is bound, the Fiori elements engine that reads the resulting $metadata document at runtime, the CDS access control (DCL) evaluation, and the analytics/aggregation engine for cube-like views. Metadata extensions sit alongside the base view as a separate DDIC object, letting annotations be added or overridden without touching the original view - essential when extending an SAP-delivered CDS view that must not be modified. Annotations replace what used to be hardcoded floorplan configuration or embedded UI logic in classic ABAP development; the intent - what a field means, how it should be labelled, whether it is filterable - moves out of code and into declarative metadata that any compliant consumer can interpret the same way.

A RAP-managed business object for a sales order header has an interface (basic) view carrying semantic annotations for currency and amount fields, and a projection view exposed through a service definition and service binding, carrying @UI.lineItem and @UI.selectionField for the Fiori elements list report. A column that was just annotated with @UI.lineItem does not appear in the running app. The check sequence: confirm the annotation sits on the projection view actually referenced by the service definition, not on the interface view or a different projection built on the same interface; open the service metadata document directly (via the service binding's preview or a metadata request) to see whether the annotation actually made it into the published $metadata - if it did not, the service binding needs to be republished, since metadata is generated once and cached, not read live from the CDS source on every request; if the metadata is correct but the app still shows the old layout, the Fiori launchpad or browser is serving a cached app descriptor and needs a hard refresh or cache invalidation on the front-end side.

Annotations are the intended mechanism for adjusting UI and service behaviour on S/4HANA in a clean-core-compliant way: extend an SAP-delivered CDS view by adding a metadata extension in the customer namespace rather than modifying the original view, which is not permitted on released objects and does not survive upgrades. ECC had no equivalent declarative layer; the same intent was expressed as hardcoded floorplan configuration or embedded logic tightly coupled to a specific transaction, which is exactly the pattern clean-core extensibility is meant to replace. Where an SAP-delivered view does not expose an association or field needed for a required annotation, that is a signal to look at the supported extension option for that object rather than forcing an annotation onto something not designed to carry it.

Applying the annotation is a developer task, but deciding which layer it belongs in - interface view, projection view, or metadata extension - is an architecture decision, especially where a CDS view is reused across several apps. Functional consultants specify the desired UI outcome; developers translate it into the correctly layered annotation. Handover should record the exact CDS view name, the annotation and value, the layering choice and rationale, and the transport carrying the metadata extension if one was used.

Read cds-view-entities-versus-classic-cds-ddic-views for the object type annotations attach to, extending-a-rap-business-object and rap-business-object-composition for how interface, projection and consumption layers relate in a RAP business object, fiori-elements-list-report-and-object-page for the biggest single consumer of UI annotations, and cds-access-controls-and-dcl for the annotation-adjacent mechanism that governs row-level access rather than presentation.