Descriptor for Applications, Components, and Libraries

The descriptor for applications, components, and libraries is inspired by the Web Application Manifest concept introduced by the W3C. The descriptor provides a central, machine-readable and easy-to-access location for storing metadata associated with an application, an application component, or a library.

The data is stored in json format in the manifest.json file. The developer creates the file with attributes in different namespaces. It contains, for example, the app ID, the version, the data sources used, along with the required components and libraries. The existence of the manifest.json file must be declared in the component metadata, which is then delivered as part of the application archive. After delivery, the file is read-only.

Descriptor Content

The content for the descriptor is contained in the following namespaces: without, sap.app, sap.ui, sap.ui5, sap.platform.abap, sap.platform.hcp, sap.fiori and sap.mobile. The following tables show the application-specific attributes provided by the respective namespaces:

Table 1: Attributes in the without namespace

Attribute

Description

start_url

Start page of your app, if available

Table 2: Attributes in the sap.app namespace

Attribute

Description

id

Mandatory attribute: Unique identifier of the app, which must correspond to the component ID/namespace

Note

The ID must not exceed 70 characters. It must be unique and must correspond to the component ID/namespace.

type

Possible values:

  • application

  • component

  • library

i18n

Relative URL to the properties file that contains the text symbols for the descriptor; default: "i18n/i18n.properties"

Note

The path to the i18n file must not exceed 100 characters.

applicationVersion

Mandatory attribute

embeds

Array of relative paths to the nested manifest.json files; attribute is mandatory if a nested manifest.json exists

embeddedBy

Relative path back to the manifest.json file of an embedding component or library; attribute is mandatory for a nested manifest.json

title

Mandatory attribute: The entry is language-dependent and specified via {{…}} syntax

subTitle

Language-dependent entry for a subtitle; specified via {{...}} syntax

description

Description; language-dependent entry that is specified via {{…}} syntax

tags

Containing an array of language-dependent keywords that are specified via {{…}} syntax

ach

Application component hierarchy; attribute is mandatory for SAP apps

dataSources

Unique key/alias for specifying the used data sources; contains the following information:
  • uri: Mandatory relative URL in the component; takes embeddedBy into account, if filled, or the server absolute of the data source, for example "/sap/opu/odata/snce/PO_S_SRV;v=2/"
  • type: OData (default)|ODataAnnotation|INA|XML|JSON
  • settings: Data source type-specific attributes (key, value pairs), such as:
    • odataVersion: 2.0 (default), 4.0
    • localUri: Relative URL to local metadata document or annotation uri
    • annotations: Array of annotations which references an existing data source of type "ODataAnnotation" under sap.app/dataSources

    • maxAge: Indicates the number of seconds the client is willing to accept with regard to the age of the data that is requested

cdsViews

Array of directly used CDS views

This attribute is optional and only added if used via INA protocol directly, not if used via OData service.

offline

Indicates whether the app is running offline; default is false (online)

sourceTemplate

If an app has been generated from a template, this attribute is filled automatically by the generation tool (SAP Web IDE):

  • id: ID of the template from which the app was generated

  • version: Version of the template from which the app was generated

openSourceComponents

Array of directly used open source libraries for documentation purposes; not used when open source libraries are used via SAPUI5 capsulation

  • name: Name of the open source component

  • version: Required if the open source component is part of the app; not required if the open source component is part of the SAPUI5 dist layer

  • packagedWithMySelf: Indicates if the open source component is part of the app (true) or not (false)

crossNavigation

Cross-navigation for specifying inbounds and outbounds

  • scopes: Scope of a site

    sapSite

  • inbounds: Unique key or alias to specify inbounds (mandatory); contains:

    • semanticObject (mandatory)

    • action (mandatory)

    • icon: Used to overwrite sap.ui/icons/icon

    • title: Used to overwrite sap.app/title (language-dependent entry to be specified via {{...}} syntax)

    • subTitle: Used to overwrite sap.app/subTitle (language-dependent entry to be specified via {{...}} syntax)

    • indicatorDataSource; specifies the data source; contains:

      • dataSource: reference to sap.app/dataSources (mandatory)

      • path: Relative path to sap.app/dataSources uri (mandatory)

      • refresh: Defines the refresh interval

    • deviceTypes: Contains objects with device types on which the app is running; if empty, use the default from sap.ui/deviceTypes; the following device types can be defined (true/false):

      • desktop

      • tablet

      • phone

    • signature: Specifies the signature; contains:

      • parameters (mandatory): Contains parameter names with the following information:

        • required (true/false)

        • filter: Represents the filter only if the input parameter matches the filter; with mandatory attributes value and format ("plain", "regexp", "reference")

        • defaultValue: Specifies the default value; has mandatory attirbutes value (depending on the format this is a verbatim default value) and format ("plain", "reference")

        • renameTo: Used for parameter mapping to specify the parameter name in legacy ABAP applications, for example, RF05L_BUKRS for the CompanyCode parameter

      • additionalParameters (mandatory): Indicates, how additional parameters to the declared signature are handeled; values can be, for example, "ignored", "notallowed", "allowed"

  • outbounds: Specifies outbounds with a unique key or alias containing:

    • semanticObject (mandatory)

    • action (mandatory)

    • parameters: Specifies the parameters containing the parameter name with an empty object

Table 3: Attributes in the sap.ui namespace

Attribute

Description

technology

Specifies the UI technology; value is UI5

icons

Contains object with app-specific icons, for example:
  • icon: Icon of the app
  • favIcon: ICO file to be used inside the browser and for desktop shortcuts
  • phone: 57x57 pixel version for non-retina iPhones
  • phone@2: 114x114 pixel version for retina iPhones
  • tablet: 72x72 pixel version for non-retina iPads
  • tablet@2: 144x144 pixel version for retina iPads

deviceTypes

Mandatory; contains objects with device types on which the app is running, such as:
  • desktop: Indicator for whether desktop devices are supported, true, false
  • tablet: Indicator for whether tablet devices are supported, true, false
  • phone: Indicator for whether phone devices are supported, true, false

supportedThemes

Mandatory; array of supported SAP themes, such as sap_hcb, sap_bluecrystal

fullWidth

Indicates whether an app shall run in full screen mode (true), or not (false)

The sap.ui5 namespace is aligned with the previous component metadata and contributes the following SAPUI5-specific attributes for the application descriptor, see Migrating from Component Metadata to Descriptor for more details.

Table 4: Attributes in the sap.ui5 namespace

Attribute

Description

resources

Relative URLs in the component, taking embeddedBy into account if filled, pointing to js (JavaScript) and css resources that are needed by the app for specifying the uri and an id (optional) for CSS. The JavaScript files are loaded by the require mechanism. The CSS files are added to the head of the HTML page as a link tag. The resources are resolved relative to the location of the manifest.json file.

dependencies

Specifies the external dependencies that are loaded by the SAPUI5 core during the initialization phase of the component and used afterwards, such as libraries or components:
  • minUI5Version: Minimum version of SAPUI5 that your component requires; this information ensures that the features of the SAPUI5 runtime version of the component are available. As SAPUI5 does not currently enforce use of the correct version, the minUI5Version is used for information purposes only. If the minimum SAPUI5 version criteria is not fulfilled, a warning is issued in the console log.

  • libs: ID (namespace) of the libraries that the SAPUI5 core should load for use in the component. If your app requires a minimum version of the lib, specify the minVersion for information purposes. Specify lazy to indicate that the lib shall be lazy loaded.

  • components: ID (namespace) of the components that the SAPUI5 core should load for use in your component. If your app requires a minimum version of the component, specify the minVersion for information purposes. Specify lazy to indicate that the component shall be lazy loaded.

models

Defines models that should be created or destroyed along the component's lifecycle. The key represents the model name. Use an empty string ("") for the default model.
  • type: Model class name
  • uri: Relative URL in the component, taking embeddedBy into account if filled, or server for absolute model
  • settings: Object that is passed to the model constructor
  • dataSource: String of key or alias from sap.app dataSources to reference an existing data source; the type, uri and settings properties are set according to the data source's type, uri and settings (if not already defined). If the type under sap.app dataSources is OData, an OData Model V2 is created automatically. If you need an OData Model V1, specify the type as well.

rootView

Specifies the root view that shall be opened; can be the view name as a string for XML views, or the view configuration object with viewName for the view name as a string and type for the type (enumeration of sap.ui.core.mvc.ViewType) and other properties of sap.ui.core.mvc.view.

handleValidation

Possible values: true or false (default); used to enable or disable validation handling by the message manager for this component, see Managing UI and Server Messages

config

Static configuration; specify the name-value pairs that you need in your component.

routing

Provides configuration parameters for route and router, see Routing and Navigation

extends

Used to extend another component.

  • component: ID (namespace) of the component being extended

  • minVersion: Specifies the minimum version of the component being extended, for information purposes if your app requires a minimum version of the component

  • extensions: Component or view extensions, which enable you to replace and extend views and controllers and also to modify the views, see Extending Apps

contentDensities

Mandatory; contains an object with the content density modes that the app supports, see Content Densities

  • compact: Mandatory; indicates whether compact mode is supported (true, false)

  • cozy: Mandatory; indicates whether cozy mode is supported (true, false)

resourceRoots

Map of URL locations keyed by a resource name prefix; only relative paths inside the component are allowed and no ".." characters

This attribute is intended for actual sub-packages of the component only, meaning that it must not be used for the component namespace itself. The defined resource roots will be registered after the component controller is loaded and do not affect the modules being declared as dependencies in the component controller.

componentName

Name of the SAPUI5 component

Table 5: Attributes in the sap.platform.abap namespace

Attribute

Description

uri

Mandatory; specifies the app's URI in the ABAP system, for example /sap/bc/ui5_ui5/sap/appName

Table 6: Attributes in the sap.platform.hcp namespace

Attribute

Description

uri

Specifies the URI inside the SAP HANA Cloud Platform; default is ""
Table 7: Attributes in the sap.fiori namespace

Attribute

Description

registrationIds

Array of registration IDs, for example, the Fiori IDs for Fiori apps

archeType

Arche type of the app, such as transactional, analytical, fact sheet, and so on

_version

No namespace: Descriptor format version.

Inside namespace: Namespace format version.

Example
#!js
{
    "_version": "1.3.0" , //mandatory descriptor format version (not w3c)

    //without namespace are some w3c manifest standard attributes
    "start_url": "index.html",

    "sap.app": { //general application attributes - in sap.app namespace
        "_version": "1.3.0", //mandatory namespace format version
        "id": "sap.fiori.appName", //mandatory unique app identifier (must correspond to component id/namespace, could be id in project portal or maven artifact id)
        "type": "application", //possible values "application" (default) and "component"
        "i18n": "", //optional: relative path to the properties file containing descriptor text symbols, default is "i18n/i18n.properties"
        "applicationVersion": {
            "version": "1.2.2" //version number incl. patch version
        },
        "embeds": [ "mycomponent1" , "subpath/mycomponent2" ], //array of relative paths to the nested manifest.jsons (mandatory if it contains nested manifest.json)
        "embeddedBy": "../../", //relative path back to the manifest.json of an embedding component or library (mandatory for nested manifest.json)
        "title": "{{title}}", //mandatory, language-dependent - different languages via server API or on client
        "subTitle": "{{subtitle}}", //language-dependent - different languages via server API or on client
        "description": "{{description}}", //language-dependent - different languages via server API or on client
        "tags": {
            "keywords": ["{{keyWord1}}","{{keyWord2}}"], //general keywords, language-dependent - different languages via server API or on client
        },
        "ach" : "PA-FIO" , //application component hierarchy
        "dataSources": { //used data sources -> ui5-related information stored in sap.ui5 namespace (unique inside the app)
             "equipment": { //key is alias which is used below in e.g. sap.ui5 ...
                 "uri": "/sap/opu/odata/snce/PO_S_SRV;v=2/" , //version is part of uri, e.g. ";v=2", default is 1
                 "type": "OData" , //OData (default)|ODataAnnotation|INA|XML|JSON
                 "settings": { //data-source-type-specific attributes (key, value pairs)
                     "odataVersion": "2.0" , //possible values: 2.0 (default), 4.0
                     "annotations": [ "equipmentanno" ], //filled e.g. for Smart Template
                     "localUri": "model/metadata.xml" //optional, relative url to local metadata
        "maxAge": 360 //time in seconds
        }
             },
             "equipmentanno": {
                 "uri": "/sap/bc/bsp/sap/BSCBN_ANF_EAM/BSCBN_EQUIPMENT_SRV.anno.XML",
                 "type": "ODataAnnotation",
                 "settings": { //data-source-type-specific attributes (key, value pairs)
                     "localUri": "model/annotations.xml" //optional, relative url to local annotation uri
                 }
             }
        },
        "cdsViews": [ //only to be added if directly used via INA protocol and not if used via OData service
            "VIEW1", "VIEW2"
        ],
        "resources": "resources.json" , //relative url as reference to a file (naming convention: "resources.json") which contains list of all resources needed by the apps
        "offline": true //true, false (default)
        "sourceTemplate": { //filled if app had been generated from a template
                "id": "sap.ui.ui5-template-plugin.1worklist",
                "version": "1.0.0"
        },
        "destination": { //destination/system alias (can be used at runtime for absolute URL construction; can be either set in code-level descriptor as a logical destination, or later on configuration level with a concrete destination), usually empty for SAPUI5 apps on FeS and filles for legacy apps like WDA/SAP GUI
            "name": "SAP_ERP_FIN"
        },
        "openSourceComponents": [ //array of directly used open source libs (not when used via UI5 capsulation)
            {
                "name": "D3.js", //name of the OS component as appears on the web
                "packagedWithMySelf": false //indicator whether it is part of the app or not (values true/false)
            },
            ...
        ],

        "crossNavigation": { //cross navigation scopes, inbounds and outbounds
            "scopes": {
                "sapSite": { "value": "123"} //Unique ID of a site. The scope is set in runtime programmatically or by specific property. Which scope and scope value to set will be detailed in the documentation or applied by a tool.
            },
            "inbounds": {
                "contactCreate":
                    {
                        "semanticObject": "Contact",
                        "action": "create",
                        "icon": "sap-icon://add-contact", //optional, can overwrite sap.ui/icons/icon
                        "title": "{{title}}", //optional, can overwrite sap.app/title, language-dependent - different languages via server API or on client, see comments below
                        "subTitle": "{{subtitle}}", //optional, can overwrite sap.app/subTitle, language-dependent - different languages via server API or on client
                        "indicatorDataSource": { //only needed by FLP currently for dynamic App Launcher
                            "dataSource": "ppm", //reference to sap.app/dataSources
                            "path": "TaskListSet/$count", //relative path to sap.app/dataSources uri
                            "refresh": 5 //refresh interval
                        },
                        "deviceTypes": { //if empty: take default from sap.ui/deviceTypes
                            "desktop": true, //true, false
                            "tablet": true, //true, false
                            "phone": false //true, false
                        },
                        "signature": {
                            "parameters": {
                                "id": {
                                    "required": true
                                },
                                "ContactName": {
                                    "defaultValue": {
                                        "value": "anonymous"
                                    },
                                    "required": false,
                                    "renameTo": "NAME2"
                                },
                                "Gender": {
                                    "filter": {
                                        "value": "(male)|(female)",
                                        "format": "regexp"
                                    },
                                    "required": true
                                    "renameTo": "SEX"
                                }
                            },
                            "additionalParameters": "ignored" //"ignored", "allowed", "notallowed"
                        }
                    },
                "contactDisplay":
                    {
                        "semanticObject": "Contact",
                        "action": "display",
                        "signature": {
                            "parameters": {
                                "id": {
                                    "required": true
                                },
                                "Language": {
                                    "filter": {
                                        "value": "EN"
                                    },
                                    "required": true
                                },
                                "SomeValue": {
                                    "filter": {
                                        "value": "4711"
                                    }
                                },
                                "GLAccount": {
                                    "defaultValue": {
                                        "value": "1000"
                                    },
                                    "filter": {
                                        "value": "(1000)|(2000)",
                                        "format": "regexp"
                                    }
                                }
                            }
                        }
                    },
                "contactDisplayAlt":
                    {
                        "semanticObject": "Contact",
                        "action": "display",
                        "signature": {
                            "parameters": {
                                "GLAccount": {
                                    "defaultValue": {
                                        "value": "UserDefault.GLAccount",
                                        "format": "reference"
                                    },
                                    "filter": {
                                        "value": "\\d+",
                                        "format": "regexp"
                                    },
                                    "required": true
                                },
                                "SomePar": {
                                    "filter": {
                                        "value": "UserDefault.CostCenter",
                                        "format": "reference"
                                    },
                                    "required": true
                                }
                            }
                        }
                    }
            },
            "outbounds": {
                "addressDisplay":
                    {
                        "semanticObject": "Address",
                        "action": "display",
                        "parameters": {
                            "companyName": {}
                        }
                    },
                "companyDisplay":
                    {
                        "semanticObject": "Company",
                        "action": "display",
                        "parameters": {
                            "companyName": {}
                        }
                    }
            }
        }
    },

    "sap.ui": { //general ui attributes - in sap.ui namespace
        "_version": "1.3.0", //mandatory namespace format version

        "technology": "UI5" //app type such as UI5, WDA, NWBC, URL, GUI (new)
        "icons": { //name/value pairs with defined attribute names for the usage, formerly stored under "config"
            "icon": "sap-icon://add-contact",
            "favIcon": "icon/F1373_Approve_Purchase_Orders.ico", //the ICO file to be used inside the browser and for desktop shortcuts
            "phone": "icon/launchicon/57_iPhone_Desktop_Launch.png", //57x57 pixel version for non-retina iPhones
            "phone@2": "icon/launchicon/114_iPhone-Retina_Web_Clip.png", //114x114 pixel version for retina iPhones
            "tablet": "icon/launchicon/72_iPad_Desktop_Launch.png", //72x72 pixel version for non-retina iPads
            "tablet@2": "icon/launchicon/144_iPad_Retina_Web_Clip.png" //144x144 pixel version for retina iPads
        },
        "deviceTypes": { //mandatory, needed for docu
            "desktop": true, //true, false
            "tablet": true, //true, false
            "phone": false //true, false
        },
        "supportedThemes": [ //mandatory, only SAP themes, needed for docu
            "sap_hcb", "sap_bluecrystal"
        ],
        "fullWidth": true //to indicate whether app should run in full screen mode (formerly under sap.ui5/config), true, false
    },
   
    "sap.ui5": { //SAPUI5-specific attributes - in sap.ui5 namespace
        "_version": "1.1.0", //mandatory namespace format version

        "resources":{ //relative urls inside component, taking embeddedBy into account if filled, pointing to JavaScript/CSS resources that your app needs (app internal), formerly called "includes"
            "js": [{
                "uri": "component.js"
            }],
            "css": [{
                "uri": "component.css",
                "id": "componentcss" //id optional as style tags
            }]
        },
        "dependencies": { //external dependencies
            "minUI5Version": "1.34.0" , //minimum version of ui5 dist layer
            "libs": { //used ui5 libraries
                "sap.m": {
                    "minVersion": "1.34.0" //minimum version
                },
                "sap.ui.commons": {
                    "minVersion": "1.34.0" , //minimum version
                    "lazy": "true //values true/false (default: false)
                    }
                }
            }
            "components": {
                "sap.ui.app.other": {
                    "minVersion": "1.1.0" , //minimum version
                    "lazy": "true //values true/false (default: false)
                }
            }
        }, 
        "models": {
            "i18n": {
                "type": "sap.ui.model.resource.ResourceModel",
                "uri": "i18n/i18n.properties" //relative url inside component, taking embeddedBy into account if filled, or server absolute
            },
            "equipment": { //empty string "" is the default model
                "dataSource": "equipment", //reference of dataSource under sap.app - only enhance it with more settings for UI5 if needed
                "settings": {
                }
            }
        },
        "rootView": "sap.ui.test.view.Main", //root view
        "handleValidation": true, //true, false (default), to enable/disable validation handling by MessageManager for this component
        "config": {
            //configuration
        },
        "routing": {
            //navigation
        },
        "extends": { //extends another component
            "component": "sap.fiori.otherApp",
            "minVersion": "0.8.15" //minimal version
            "extensions": { //formerly called customizing
                //extensions
            }
        },
        "contentDensities": { //mandatory
            "compact": true, //mandatory, true, false
            "cozy": false    //mandatory, true, false
        },
        "resourceRoots": {
            ".myname": "./myname" //only relative paths inside component are allowed, no "..", for real sub-packages of the component only (must not be used for component namespace itself)
        };
        "componentName": "sap.fiori.appName" //UI5 component name (to be filled by Tools and Templates)  
    }, 

    "sap.platform.abap": { //ABAP-platform-specific attributes
        "_version": "1.1.0", //namespace format version
        "uri": "/sap/bc/ui5_ui5/sap/appName", //uri of the app in the ABAP system
        "uriNwbc": "" //represents alternative uri for starting application for legacy apps, such as WDA/SAP GUI, generated by export tool
    },

    "sap.platform.hcp": { //HANA-Cloud-Platform-specific attributes
        "_version": "1.1.0", //namespace format version
        "uri": "", //uri inside the SAP HANa cloud platform HTML5 application; default is ""
        "uriNwbc": "" //represents alternative uri for starting application for legacy apps, such as WDA/SAP GUI, generated by export tool
    },


    //other namespaces
    "sap.mobile": { //in Mobile responsibility
        ...
    },
    "sap.flp": { //in FLP responsibility
        ...
    },
    "sap.ui.generic.app": { //in Smart Template responsibility
        ...
    },
    "sap.ovp": { //in Overview Page responsibility
        ...
    },
    "sap.ui.smartbusiness.app": { //in Smart Business responsibility
         ...
    },
    "sap.wda": { //in Web Dypro ABAP responsibility
        ...
    },
    "sap.gui": { //in SAP GUI responsibility
        ...
    },
    "sap.cloud.portal": { //in SAP Cloud Portal responsibility
        ...
    },
    "sap.apf": { //in analysis path framework responsibility
        ...
    }
 }
Declaration in Component Metadata

The component declares the existence of the application descriptor by specifying manifest: "json" in the component metadata. Setting this flag makes the component load the manifest.json file and read the relevant entries for SAPUI5. This metadata is used to define the dependencies that need to be loaded in order to start the component. The following code snippet shows how to add the manifest link:

#!js
sap.ui.core.UIComponent.extend("sap.samples.Component", {
    metadata  : { 
        manifest: "json"
    }
}
SAPUI5 API

At runtime, the manifest.json content can be accessed from the component via the component metadata:

#!js
// get the component
jQuery.sap.require("sap.samples.Component");
var oComponent  = sap.samples.Component;

// getting complete manifest from component metadata
oComponent.getMetadata().getManifest();
//or getting a namespace
oComponent.getMetadata().getManifestEntry("sap.app");