CDS Annotations Part 4: Metadata Extensions — Separating UI from the Data Model

📌 KEY POINTS
✅ A metadata extension (annotate entity … with) adds annotations to a view in a separate object.
✅ The view must allow it: @Metadata.allowExtensions: true.
✅ Layers decide precedence: #CUSTOMER > #PARTNER > #INDUSTRY > #LOCALIZATION > #CORE.
⚠️ Not every annotation is allowed in a metadata extension — semantics stay in the view.

━━━━━━━━━━━━━━━━━━━━
▶ WHERE WE ARE
Part 3 wrote UI annotations. This part explains the object that holds them — and why it keeps your data model clean.

━━━━━━━━━━━━━━━━━━━━
▶ 1. WHY METADATA EXTENSIONS

• The data model (fields, keys, associations, semantics) changes rarely.
• The UI (columns, positions, labels, sections) changes often.

Keeping UI annotations in a separate object means: UI changes do not touch the view, views stay readable, different teams can work in parallel, and changes to the UI need no re-activation of dependent views.

━━━━━━━━━━━━━━━━━━━━
▶ 2. SYNTAX
@Metadata.layer: #CUSTOMER
annotate entity ZC_PurchReq with
{
@UI.lineItem: [{ position: 10 }]
RequestID;
}

• One metadata extension per layer for a given entity; the file name is freely chosen (convention: same name as the view).
• You list elements by name, followed by a semicolon, with annotations in front.
• Header annotations (e.g. @UI.headerInfo) go before "annotate entity".

━━━━━━━━━━━━━━━━━━━━
▶ 3. ENABLING
The annotated view needs @Metadata.allowExtensions: true in its header. Without it, the extension is ignored (with a warning).

━━━━━━━━━━━━━━━━━━━━
▶ 4. LAYERS AND PRECEDENCE
Several extensions in different layers can annotate the same view. For the same annotation, the higher layer wins:
#CUSTOMER (highest) → #PARTNER → #INDUSTRY → #LOCALIZATION → #CORE (lowest).
Annotations in any metadata extension override those written directly in the view, which override propagated ones.
Customers and partners use this to adapt SAP-delivered UIs without modifying SAP objects.

━━━━━━━━━━━━━━━━━━━━
▶ 5. WHAT BELONGS IN AN EXTENSION
Allowed and typical: @UI.*, @EndUserText.*, @Consumption.* (e.g. value helps, filters), @Search.* on elements.
Not allowed or not sensible: annotations that define the data model's meaning or behavior — e.g. @Semantics amount/currency references, @ObjectModel text associations, @AccessControl. Those stay in the view.
💡 TIP: ADT marks annotations that are not permitted in a metadata extension with an error; the ABAP keyword documentation lists "MDE-enabled" annotations.

━━━━━━━━━━━━━━━━━━━━
▶ 6. ORGANIZING SEVERAL APPS

• Same BO, two apps (buyer app, approver app) → two projections (ZC_PurchReq, ZC_PurchReqApprove), each with its own metadata extension.
• Do not try to serve two layouts from one projection.

━━━━━━━━━━━━━━━━━━━━
▶ STEP BY STEP

1. Add @Metadata.allowExtensions: true to ZC_PurchReq and ZC_PurchReqItem.
2. Right-click the projection → New → Metadata Extension; choose layer #CUSTOMER.
3. Move all @UI annotations from the view into the extension.
4. Activate; check the preview — the UI must look the same.

✅ CHECKPOINT: your UI lives outside the data model. Part 5 shows how to debug annotations that "do not work".

A company used an SAP-delivered Fiori app but needed different column order and two extra filters. The first idea was to copy the SAP CDS views into Z-views — which would have meant maintaining copies forever and losing SAP updates.
Instead, a metadata extension in layer #CUSTOMER on the released consumption view changed positions and added selection fields. SAP upgrades kept delivering improvements to the underlying view, and the customer UI adjustments survived without modification. The same pattern was later used for their own RAP apps.

• Forgetting @Metadata.allowExtensions: true.
• Putting semantic or access annotations into the extension.
• Two extensions in the same layer for the same view.
• Not knowing that a higher layer overrides lower ones and the view.
• One projection trying to serve two different app layouts.
• Copying SAP views instead of extending their metadata.

• Data model and semantics in views; UI in metadata extensions.
• Use #CUSTOMER for own development unless your organization defines otherwise.
• One projection + one metadata extension per app.
• Name the extension like the view it annotates.
• Verify with the preview and the Active Annotations view.

Questions: "What is a metadata extension?", "What does @Metadata.allowExtensions do?", "Which layer wins?", "Which annotations are not allowed in MDEs?"
Strong answer: an MDE (annotate entity … with) adds annotations to a CDS entity in a separate object; the entity must allow extensions; layers #CORE < #LOCALIZATION < #INDUSTRY < #PARTNER < #CUSTOMER determine precedence, and MDE annotations override view annotations. UI, labels, consumption and search annotations fit; semantics, access control and model definitions stay in the view. Mention adapting SAP apps without copying views.