Fiori annotations
Describing a service so a Fiori client can render it without hand-written UI code — titles, value helps, hierarchies and visibility expressed as model annotations rather than screen logic.
Showing artifacts, examples and content with confirmed Node.js applicability. View All CAP
Overview
@sap/cds@sap/cdsThe CAP Node.js runtime, which compiles the CDS model, serves the services declared in it, answers generic requests before any handler runs, and loads every cds-plugin.sap official, cap compiles the model's annotations and serves the metadata that carries them in one process, and the index page's Fiori preview renders a list page from them while the server runs. In a deployment the preview is turned on with cds.fiori.preview.
Not covered: At the terms the compiler translates, which is the door's boundary and not a Node.js one: the shortcuts reach labels, value lists on managed associations and recursive hierarchies, and every other term is written in the vocabulary's own structure.
Every community provider on this capability states this flavor: the three of them are cds-plugins, which @sap/cds loads.
Artifacts
Tasks
Carry a vocabulary SAP does not ship into the OData metadata
Annotations written with terms of somebody's own reach the service's OData metadata, with the reference to their vocabulary document beside them, instead of being dropped in translation.
Covers getting the terms into the metadata. What reads them at the other end is not part of it: a Fiori elements client reads the OASIS and SAP terms, and anything else needs a renderer of its own.
@sap/cdscds.cdsc.odataVocabularies names a further vocabulary's alias, namespace and URI, and from then on every annotation prefixed with it is translated and the metadata carries the edmx:Reference to the vocabulary document beside the annotation.
Remaining work: Make the URI reachable where that matters, and write whatever reads the terms. The compiler has no access to the vocabulary's content, so it checks neither the values nor that a term is applied where its own definition allows.
urp-vocabA vocabulary of its author's own, used from CDS as using urp from 'urp-vocab' and applied as @urp.display and five further terms. Whether its terms reach the OData metadata is not established: its readme names the terms and the widget types but says nothing about registering the vocabulary with the compiler, nothing about cds.cdsc.odataVocabularies, and nothing about what reads the terms. Its declared repository, github.com/your-username/urp-vocab, is an unedited placeholder, so the package's own files are the only record there is.
Remaining work: Read the published package's files before treating it as an answer here. On what is written down, it is a vocabulary definition and not a translation path.
Put a value help on a field a Fiori client renders
A field in a Fiori elements app offers the values it allows instead of a free-text input, with the list coming from the model rather than from code in the app.
Covers getting the value-list annotation onto the field. Where the values are kept — a code list entity, a CDS enum, a table of its own — is the model's design and not this outcome, and so is anything the app adds on top of the control.
@mpah/enum-value-helpAnswers the case the shortcut leaves alone, a field typed by a CDS enum. @enumValueHelp on the field makes the plugin add @Common.ValueList against a generated EnumValueHelpView that serves the enum's own values by entity and field, and @enumValueHelpFixedValues adds @Common.ValueListWithFixedValues as well, which is what makes the control a dropdown rather than a search dialog. It scans for the annotations while the CDS model loads and exposes the view to the services that hold an annotated entity.
Remaining work: Mark each enum field, and @enumValueHelpFixedValues as well where the list should be fixed. Nothing picks the fields.
@sap/cdsTwo ways, both from the model. @cds.odata.valuelist on the entity that holds the values gives every managed association targeting it a value list, and the reuse types of @sap/cds/common already carry it, so a field typed from a code list there arrives with one. Any other case is the @Common.ValueList record written out in the vocabulary's own structure, which the compiler translates because the mapping is generic rather than written per term.
Conditions: The shortcut reaches a field only where that field is a managed association to the annotated entity. A field that is not an association needs the @Common.ValueList record written by hand, naming the collection and the parameters that tie the local property to the value-list property.
Remaining work: Model the entity the values come from and expose it on the service, then decide field by field whether the shortcut applies or the record has to be written out.
See the annotations rendered before any Fiori app exists
A developer changing @UI annotations sees the page they produce straight away, with no UI application in the project to generate or rebuild first.
Covers the loop while the annotations are being written. It is not a way to ship a screen: what answers this outcome is a page the server renders, not an app, and the distinction is where the decision sits.
@sap/cdsThe index page carries a Fiori preview link for every entity exposed over OData V4 and serves a Fiori elements list page from that entity's annotations, so the effect of an annotation change is visible without creating a UI application.
Conditions: The entity has to be exposed over OData V4; the link appears for those entities and not for others. It is disabled in production. cds.fiori.preview set to true turns it back on in a cloud deployment for a test or a demo.
Remaining work: Nothing in the project for the local loop. A real app still has to be generated once the page in question is more than a list report.
Show a self-referencing entity as a Fiori tree table
An entity whose rows point at their own parent is rendered as an expandable tree in a Fiori elements list report instead of a flat list.
Covers the annotations the service carries and the one setting in the app's manifest.json that the guide requires with them. Building the hierarchy in the data, and anything the app does inside the tree's rows, is outside it.
@sap/cds@hierarchy on the entity expands at compile time to the Fiori-level annotate and extend statements the tree would otherwise need written by hand, and the runtime serves the result.
Conditions: The entity needs a recursive association to itself, which is what the shortcut reads. The UI5 app's manifest.json has to name the hierarchy qualifier and set the table type to TreeTable; the qualifier follows the pattern <entity name in service>Hierarchy.
Remaining work: Add the controlConfiguration block to the app's manifest.json, and keep the qualifier in step with the entity's name in the service, because the pattern is derived from it.
Seen working
Neither the package manifest nor the repository tree declares a licence.
Neither the package manifest nor the repository tree declares a licence.
Neither the package manifest nor the repository tree declares a licence.
Neither the package manifest nor the repository tree declares a licence.
Neither the package manifest nor the repository tree declares a licence.
Neither the package manifest nor the repository tree declares a licence.
Details
Coverage
For your agent
- Ref
capability:fiori-annotations- JSON
- /capabilities/fiori-annotations.json
- MCP
- Connecting an agent