16. Local XML Annotations

16. Local XML Annotations for Fiori Elements and SmartFields

This section collects the main XML annotations most often used when developing Fiori Elements and SmartFields applications. Annotations allow you to control the display of filters, table columns, facets, action buttons, value helps, and other UI elements without writing a lot of JavaScript code.

Main annotation namespaces

  • com.sap.vocabularies.UI.v1 — UI annotations (LineItem, FieldGroup, Facet, Action, etc.)
  • com.sap.vocabularies.Common.v1 — Common annotations (ValueList, Text, SemanticKey, etc.)
  • com.sap.vocabularies.SelectionPresentationVariant.v1 — Presentation and selection variants

1. Filters (SelectionFields)

Defines fields to be displayed in the filter (SmartFilterBar).

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.SelectionFields">
    <Collection>
      <PropertyPath>Field1</PropertyPath>
      <PropertyPath>Field2</PropertyPath>
    </Collection>
  </Annotation>
</Annotations>

2. Table fields (LineItem)

Defines columns for SmartTable/ListReport.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.LineItem">
    <Collection>
      <Record Type="com.sap.vocabularies.UI.v1.DataField">
        <PropertyValue Property="Value" Path="Field1"/>
      </Record>
      <Record Type="com.sap.vocabularies.UI.v1.DataField">
        <PropertyValue Property="Value" Path="Field2"/>
      </Record>
    </Collection>
  </Annotation>
</Annotations>

3. Facets

Groups fields on the Object Page (e.g., sections, tabs, groups).

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.Facets">
    <Collection>
      <Record Type="com.sap.vocabularies.UI.v1.CollectionFacet">
        <PropertyValue Property="Label" String="General Data"/>
        <PropertyValue Property="Facets">
          <Collection>
            <Record Type="com.sap.vocabularies.UI.v1.ReferenceFacet">
              <PropertyValue Property="Target" AnnotationPath="@com.sap.vocabularies.UI.v1.FieldGroup#General"/>
              <PropertyValue Property="Label" String="Main Information"/>
            </Record>
          </Collection>
        </PropertyValue>
      </Record>
    </Collection>
  </Annotation>
</Annotations>

<!-- Example FieldGroup -->
<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.FieldGroup" Qualifier="General">
    <Record>
      <PropertyValue Property="Label" String="Main Information"/>
      <PropertyValue Property="Data">
        <Collection>
          <Record Type="com.sap.vocabularies.UI.v1.DataField">
            <PropertyValue Property="Value" Path="Field1"/>
          </Record>
          <Record Type="com.sap.vocabularies.UI.v1.DataField">
            <PropertyValue Property="Value" Path="Field2"/>
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</Annotations>

4. Action buttons (Actions)

Adds buttons for actions (e.g., Approve, Reject) in the table or on the Object Page.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.LineItem">
    <Collection>
      <!-- ... other fields ... -->
      <Record Type="com.sap.vocabularies.UI.v1.DataFieldForAction">
        <PropertyValue Property="Label" String="Approve"/>
        <PropertyValue Property="Action" String="MyService.EntityType_Approve"/>
      </Record>
    </Collection>
  </Annotation>
</Annotations>

5. ValueHelp (ValueList)

Defines a value help (F4 help) for a field.

<Annotations Target="MyService.EntityType/Field1">
  <Annotation Term="com.sap.vocabularies.Common.v1.ValueList">
    <Record Type="com.sap.vocabularies.Common.v1.ValueListType">
      <PropertyValue Property="CollectionPath" String="ValueHelpEntitySet"/>
      <PropertyValue Property="Parameters">
        <Collection>
          <Record Type="com.sap.vocabularies.Common.v1.ValueListParameterOut">
            <PropertyValue Property="LocalDataProperty" PropertyPath="Field1"/>
            <PropertyValue Property="ValueListProperty" String="ID"/>
          </Record>
          <Record Type="com.sap.vocabularies.Common.v1.ValueListParameterDisplayOnly">
            <PropertyValue Property="ValueListProperty" String="Description"/>
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Annotation>
</Annotations>

6. Displaying text instead of ID (Text)

Allows you to show text instead of a technical key.

<Annotations Target="MyService.EntityType/Field1">
  <Annotation Term="com.sap.vocabularies.Common.v1.Text" Path="DescriptionField"/>
</Annotations>

7. Criticality

Used to display statuses (colors, icons) in tables and objects.

<Annotations Target="MyService.EntityType/StatusField">
  <Annotation Term="com.sap.vocabularies.UI.v1.Criticality" EnumMember="com.sap.vocabularies.UI.v1.CriticalityType/Negative"/>
</Annotations>

8. Object header and description (HeaderInfo)

Defines which fields are used as the header and description on the Object Page.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.UI.v1.HeaderInfo">
    <Record>
      <PropertyValue Property="TypeName" String="Document"/>
      <PropertyValue Property="TypeNamePlural" String="Documents"/>
      <PropertyValue Property="Title">
        <Record Type="com.sap.vocabularies.UI.v1.DataField">
          <PropertyValue Property="Value" Path="ID"/>
        </Record>
      </PropertyValue>
      <PropertyValue Property="Description">
        <Record Type="com.sap.vocabularies.UI.v1.DataField">
          <PropertyValue Property="Value" Path="Description"/>
        </Record>
      </PropertyValue>
    </Record>
  </Annotation>
</Annotations>

9. SemanticKey

Defines key fields for navigation and object uniqueness.

<Annotations Target="MyService.EntityType">
  <Annotation Term="com.sap.vocabularies.Common.v1.SemanticKey">
    <Collection>
      <PropertyPath>ID</PropertyPath>
    </Collection>
  </Annotation>
</Annotations>

10. Other useful annotations

  • UI.Hidden — hide a field in the UI
  • UI.Importance — field importance (High, Medium, Low)
  • UI.DataPoint — visualization of numeric values (e.g., progress bar)
  • UI.Chart — chart definition
  • UI.PresentationVariant — sorting, grouping, top-N
  • UI.SelectionPresentationVariant — combination of filters and presentation

Note:
Annotations can be added both in the backend (CDS, MPC_EXT) and in local XML files (e.g., annotation.xml), which are connected via manifest.json.

See also