RAP / CDS / ODatabeginner

CDS Annotations Part 1: What Annotations Are and Where They Apply

Key takeaway

Understand what CDS annotations are, where they can be placed, which families exist (ABAP, semantics, UI, consumption, search, analytics), how they propagate through view layers and where they end up in OData.

What this complete series covers

Learn CDS Annotations in a clear, practical sequence — from the basic idea to real project use, troubleshooting, and interview-ready understanding.

Who it is for: Best for SAP consultants, developers, and learners who want a practical understanding of CDS Annotations.
Prerequisites: Basic ABAP and ADT in Eclipse are recommended. The series explains the RAP/CDS/OData concepts as they are introduced.
Final outcome: By the end, you should be able to explain CDS Annotations clearly, follow the main end-to-end flow, apply it in a project scenario, and troubleshoot the most common issues.

Part 1: CDS Annotations Part 1: What Annotations Are and Where They Apply
Understand CDS annotations as metadata contracts for semantics, UI, analytics, authorization, and framework behavior, including how annotations are placed, inherited, propagated, o
Part 2: CDS Annotations Part 2: Semantic Annotations for Currency, Units and Texts
Model amount-currency, quantity-unit, text, and business semantics correctly so downstream SAP consumers can format, aggregate, navigate, and interpret CDS data without hard-coded assumptions.
Part 3: CDS Annotations Part 3: Fiori UI Annotations — Line Items, Facets and Selection Fields
Design Fiori Elements metadata deliberately by mapping business tasks to LineItem, Identification, Facets and SelectionFields instead of treating annotations as a visual styling language.
Part 4: CDS Annotations Part 4: Metadata Extensions — Separating UI from the Data Model
Use CDS metadata extensions to keep reusable business data models independent from application-specific presentation while preserving controlled annotation ownership and upgrade-safe layering.
Part 5: CDS Annotations Part 5: Troubleshooting Precedence, Metadata and UI Behavior
Diagnose annotation problems by tracing the effective metadata from CDS and metadata extensions through service binding to the Fiori consumer instead of changing annotations blindly.

System and release assumptions: Examples target recent SAP S/4HANA / ABAP Cloud capabilities. RAP, CDS, OData, and Fiori Elements syntax and tooling can differ by ABAP platform release.

Explanation

📌 KEY POINTS
✅ Annotations add metadata to CDS entities and elements — they do not change the SELECT result.
✅ Scopes: entity (header), element, parameter; each annotation allows only certain scopes.
✅ Families: ABAP (@AbapCatalog, @AccessControl, @EndUserText), @Semantics, @ObjectModel, @UI, @Consumption, @Search, @Analytics.
⚠️ Element annotations propagate from lower views — know where a value comes from.

━━━━━━━━━━━━━━━━━━━━
▶ WHAT THIS SERIES COVERS

Part 1 — what annotations are and where they apply (this lesson)
Part 2 — semantic annotations: currency, units, texts, admin fields
Part 3 — Fiori UI annotations: line items, facets, selection fields
Part 4 — metadata extensions: separating UI from the data model
Part 5 — troubleshooting precedence, metadata and UI behavior

━━━━━━━━━━━━━━━━━━━━
▶ WHAT ANNOTATIONS DO
A CDS view defines data. Annotations describe that data for tools and frameworks:

"This decimal is an amount in the currency of that field" → correct formatting and aggregation.
"Show this field as the first column of the list" → Fiori Elements renders it.
"Authorization must be checked" → access control is expected.
"This element is searchable" → free-text search works.

The database ignores them; frameworks read them from the CDS metadata.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE THEY CAN BE PLACED (SCOPE)

Entity/header annotations — before "define view entity": @EndUserText.label, @AccessControl.authorizationCheck, @UI.headerInfo, @Search.searchable, @Metadata.allowExtensions.
Element annotations — before an element: @Semantics.amount.currencyCode, @UI.lineItem, @Consumption.valueHelpDefinition.
Parameter annotations — before a parameter: @Environment.systemField, @Consumption.defaultValue.

Placing an annotation at the wrong scope gives a syntax warning or is ignored — ADT code completion shows valid annotations per position.

━━━━━━━━━━━━━━━━━━━━
▶ THE MAIN FAMILIES

ABAP / core: @AbapCatalog (classic views), @AccessControl, @EndUserText, @Metadata.
Semantics: @Semantics.* — amounts, quantities, units, currency codes, texts, languages, admin fields.
Object model: @ObjectModel.* — text elements and associations, representative key, usage type, data category.
UI: @UI.* — Fiori Elements layout: headerInfo, lineItem, identification, facet, fieldGroup, selectionField, hidden.
Consumption: @Consumption.* — value helps, default values, filter behavior, hidden in consumption.
Search: @Search.* — searchable entity, default search elements, fuzziness.
Analytics: @Analytics.* and @AnalyticsDetails.* — cubes, dimensions, queries.

━━━━━━━━━━━━━━━━━━━━
▶ PROPAGATION THROUGH LAYERS
Element annotations of a view are, by default, also visible in views built on top of it for the same element (propagation). Example: @Semantics.amount.currencyCode on the interface view is known in the consumption view without repeating it.

Header annotations are not propagated.
@Metadata.ignorePropagatedAnnotations: true stops propagation into a view.
A value defined directly on a view (or in its metadata extension) overrides a propagated one.

💡 TIP: ADT's "Active Annotations" view shows the effective annotations of each element and where they come from.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE THEY END UP
In a RAP service, the relevant annotations of the exposed projections are translated into OData vocabularies in $metadata (e.g. UI.LineItem, Common.Text, Measures.ISOCurrency). Fiori Elements reads them from there.

✅ CHECKPOINT: you can read an annotated view and say which framework uses each annotation. Part 2 starts with the most important family: semantics.

Code example

ABAP Code

// ===== Annotation scopes in one view =====@EndUserText.label: 'Sales Order'                        // header: ABAP/core@AccessControl.authorizationCheck: #CHECK                // header: access control expected@Metadata.allowExtensions: true                          // header: metadata extensions allowed@Search.searchable: true                                  // header: search frameworkdefine view entity ZI_SalesOrder  with parameters    @Environment.systemField: #SYSTEM_DATE              // parameter annotation    p_keydate : abap.dats  as select from zso_head{      @Search.defaultSearchElement: true                  // element: search  key sales_order     as SalesOrder,       @EndUserText.label: 'Sold-To Party'                 // element: label      customer_id     as Customer,       @Semantics.amount.currencyCode: 'CurrencyCode'      // element: semantics      net_amount      as NetAmount,      currency_code   as CurrencyCode,       @Semantics.systemDateTime.lastChangedAt: true       // element: admin field      last_changed_at as LastChangedAt} // ===== Propagation =====// A view on top of ZI_SalesOrder does NOT need to repeat// @Semantics.amount.currencyCode for NetAmount - it is propagated.//// define view entity ZC_SalesOrderAnalysis//   as select from ZI_SalesOrder( p_keydate: $session.system_date )//   { key SalesOrder, NetAmount, CurrencyCode }   // NetAmount still knows its currency//// Stop propagation (rarely needed)://   @Metadata.ignorePropagatedAnnotations: true // ===== In OData $metadata (V4), for example =====//   <Annotation Term="Measures.ISOCurrency" Path="CurrencyCode"/>//   <Annotation Term="Common.Label" String="Sold-To Party"/>

Real project scenario

A team put all UI annotations, semantic annotations and search annotations directly into their interface views because "that is where the fields are". When a second app reused the interface view, it inherited list columns and labels designed for the first app, and nobody could change one app without affecting the other.
They reorganized: semantics (currency, units, texts) stayed in interface views because they describe the data; UI and search annotations moved into metadata extensions of each app's projection. The ADT Active Annotations view was used to verify the effective result per view.

Common mistakes

Treating annotations as if they changed the data returned.
Placing annotations at the wrong scope and ignoring the warning.
Putting app-specific UI annotations into reusable interface views.
Repeating propagated annotations unnecessarily, or not knowing where a value comes from.
Using classic @AbapCatalog.sqlViewName in new view entities.

Best practices

Semantics in interface views; UI in metadata extensions of projections.
Use ADT code completion and the Active Annotations view.
Always label entities and key elements with @EndUserText.label.
Set @Metadata.allowExtensions: true on projections that get metadata extensions.
Check the resulting OData $metadata when UI behavior is unexpected.

Interview angle

Questions: "What are CDS annotations?", "What scopes exist?", "What is annotation propagation?", "Where should UI annotations live?"
Strong answer: annotations are metadata read by frameworks, not by the database; scopes are entity, element and parameter; families include semantics, object model, UI, consumption, search and analytics. Element annotations propagate to views on top unless overridden or ignored. Semantic annotations belong in interface views; UI annotations in metadata extensions of consumer projections.

Practice this lesson

Quick check

1. Which statement about CDS annotation propagation is correct?

2. A CDS view exposes an amount field together with a separate currency key field. Which annotation must be added to the amount field so that Fiori Elements and OData correctly format and display it as a currency amount?

3. Which annotation, when applied to a CDS view used as a RAP projection, can be set to indicate that authorization checks are already handled elsewhere and should not be performed again by the framework for that entity?

Interview questions

1. What are CDS annotations, which scopes and families exist, and how do they propagate?

Answer it in your own words first, then compare.

2. You inherit CDS views full of annotations. What do you review first?