Using the Singleton Entity


After completing this lesson, you will be able to:

  • Explain how you can create and use the singleton entity in your apps

The Singleton Entity

A singleton is a special one-element entity introduced in OData V4. It can be referred by its name from the service root, without having to know its key and without requiring an entity set.

You can annotate an entity with @odata.singleton or @odata.singleton.nullable to use it as a singleton in your service in CAP projects.

Code snippet

service myService { 
  @odata.singleton entity MySingleton {
    key id : String; // can be omitted
    prop1 : String; 
    prop2 : Boolean;

In your CAP CDS annotations, you can reference properties from the singleton entity by using the $edmjson inline mechanism.

Let us consider a typical use case for singletons in self service apps. Here, you might want to load the user context describing the user's authorizations and default settings. In this case, the back end can simply use the log on ID of the user to send the relevant data through the corresponding singleton, exposing the user context.

Check another example of the use cases for singleton entities in SAP Fiori elements applications for OData V4 "Using Singletons to influence the visibility of the Create, Delete and Edit Buttons". For more information, see Actions.


$edmJson is supported only with CDS compiler 2.3.0 or higher.

For more information about using the $edmjson inline mechanismĀ in CAP CDS annotations, see Dynamic Expressions section in Serving OData APIs.

Use the Singleton Entity for Constant Values of the Bullet Micro Chart

Usage Scenario

In this exercise, you will see one of the use cases for using a singleton entity in SAP Fiori elements application for OData V4. Instead of assigning constant values to annotation properties, like you did in the previous exercise for the bullet micro chart, you will reference values from the singleton entity. Thus, you will modify the previous exercise in which you have added a bullet micro chart to the subobject page header.

Next, you will put the static boolean values into the corresponding CSV file for the singleton entity. With the use of singletons, you reduce the amount of metadata, and have all the constant values in one singleton file.

Task Flow

In this lesson, you will define a new entity called SupplementScope in your CAP data model. The annotation @odata.singleton will make it a singleton entity.

Next, you will create a corresponding CSV file for the SupplementScope entity and will add values for the entity's properties. Then, you will reference singleton properties in the annotations by using the inline $edmjson mechanism.


You have completed the exercise Add the Bullet Micro Chart and the Progress Indicator to the Header Area in the unit Shaping the Header Area of the Object Page (lesson: Enriching the Object Page Header with Micro Charts). Alternatively, you can check out its solution branch: solution/add-bullet-micro-chart-and-progress-indicator-to-op.

Watch the Simulation and Perform the Steps

This exercise contains a simulation that takes you through all the steps described below. You can follow the simulation and perform the steps using your own trial account.


  1. Open your CAP project in SAP Business Application Studio.

  2. Define the new entity SupplementScope and annotate it with @odata.singleton.

    1. To open Search files by names, press Ctrl+P on your keyboard.

    2. Choose schema.cds fiori-elements-v4-cap-advanced/db. The schema.cds file opens.

    3. Add the following code snippet to the schema.cds file:

      Code snippet
      entity SupplementScope {
        MinimumValue : Integer @Common.Label: 'Minimum Value';
        MaximumValue : Integer @Common.Label: 'Maximum Value';
        TargetValue : Integer @Common.Label: 'Target Value';
        DeviationRangeLowValue : Integer @Common.Label: 'Deviation Range Threshold';
        ToleranceRangeLowValue : Integer @Common.Label: 'Tolerance Range Threshold'; 
  3. Create a corresponding .csv file for the singleton entity and fill it with data.

    1. In the Explorer view, select Projects\db\data.

    2. Expand data.

    3. Right-click on data.

    4. Select New File....

    5. Enter the name of the new entity as

    6. Add the following properties and the corresponding values to the file:

      Code snippet
  4. Add the singleton entity SupplementScope to the service definition.

    1. To open Search files by names, press Ctrl+P on your keyboard.

    2. Choose travel-service.cds. The travel-service.cds file opens.

    3. Add the following code snippet to the travel-service.cds file.

      Code snippet
      entity SupplementScope as projection on my.SupplementScope;
  5. Replace the constant values in the @UI.DataPoint annotation with the corresponding paths to the singleton properties.

    1. In the Explorer view, select Projects\app\travel_processor\webapp.

    2. In the Explorer view, select Projects\app\travel_processor\webapp.

    3. Right-click on webapp.

    4. Select Show Page Map. The Page Map of the Travel application appears.

    5. Select the Edit icon of the subobject page. The Page Map of the BookingObjectPage appears.

    6. Expand the Header Sections.

    7. Select Total Supplements.

    8. In the right pane, select Edit in source file. The layout.cds file appears.

    9. To replace the existing constant values with the corresponding paths that refer to the singleton entity, add the following code snippet in the @UI.DataPoint annotation:

      Code snippet
      annotate TravelService.Booking with @(
        UI.DataPoint #TotalSupplPrice1: {
            Value : TotalSupplPrice,
            MinimumValue : {$edmJson: {$Path: '/SupplementScope/MinimumValue'}},
            MaximumValue : {$edmJson: {$Path: '/SupplementScope/MaximumValue'}},
            TargetValue : {$edmJson: {$Path: '/SupplementScope/TargetValue'}},
            Visualization : #BulletChart,
            // Criticality : TotalSupplPrice, // it has precedence over criticalityCalculation => in order to have the   criticality       color do not use it
           CriticalityCalculation: {
                $Type : 'UI.CriticalityCalculationType',
                ImprovementDirection : #Maximize,
                DeviationRangeLowValue: {$edmJson: {$Path: '/SupplementScope/DeviationRangeLowValue'}},
                ToleranceRangeLowValue: {$edmJson: {$Path: '/SupplementScope/ToleranceRangeLowValue'}}
  6. Check the newly created singleton entity in the $metadata file.

    1. Open the Welcome to @sap/cds Server page.

    2. Select /processor/$metadata.


      In the $metadata document, you can see that the new singleton entity SupplementScope is added to the EntityContainer. You can also see the @UI.DataPoint annotation in XML format.

  7. View the bullet micro chart on the header section.

    1. Open the Manage Travels app on the browser.

    2. Under Bookings, select the first row.


      You can see the bullet micro chart on the object page header.


In this lesson, you have learned to use a singleton entity in your SAP Fiori elements applications for OData V4.


Next Steps

For more information, see

Log in to track your progress & complete quizzes