ord.md

Customizing ORD Document

The cap-js ORD plugin has a default behavior where all the values of the ORD document are generated automatically by the plugin without the user giving them explicitly.

If this default behavior is to be overwritten, then there are two ways in which it could be done.

For all the application global information, it can be done using present configuration ( in ./cdsrc.json under ord section).

Example:

// cdsrc.json or package.json cds context
  "ord": {
    "namespace": "sap.sample",
    "description": "this is my custom description",
    "policyLevel": "sap:core:v1"
  }

For all the service level information, they can be added / overwritten using annotations (in the .cds files as @ORD.Extensions).

Example:

annotate ProcessorService with @ORD.Extensions : {
    title : 'This is Processor Service title',
    industry      : [
        'Retail',
        'Consumer Products'
    ],
    lineOfBusiness: ['Sales'],
    extensible    : {supported: 'no'}
};

Also note that annotations like @Core.Description and @description are also read.

Adding Custom Ord Content

The ORD plugin provides capability to add custom ord content, it can be done using customOrdContentFile ( in ./cdsrc.json under ord section).

The overwriting happens in the following priority: customOrdContent > ord.extensions annotations > cap annotations > defaults.

Example:

// cdsrc.json
  "ord": {
    "namespace": "sap.sample",
    "description": "this is my custom description",
    "policyLevel": "sap:core:v1",
    "customOrdContentFile": "./path/to/custom.ord.json"
  }

Custom ORD File In the custom ORD file, you can:

• Add new ORD resources that are not supported by the CAP framework, e.g., dataProducts.
• Enhance the list of generated ORD resources, e.g., adding a new package or a manually implemented apiResource where no CAP service exists.
• Patch/customize default generated ORD resources, e.g. package, where no CAP service exists:
  • Overriding properties (string, array, object) generated by the plugin.
  • Adding new properties (string, array, object).
  • Deleting properties by setting them to null.

// custom.ord.json
{
    "packages": [
        {
            "description": null,
            "packageLinks": [
                {
                    "type": "terms-of-service",
                    "url": "https://www.sap.com/corporate/en/legal/terms-of-use.html"
                }
            ],
            "lineOfBusiness": [
                    "Sales"
                ]
        }
    ],
    "dataProducts": [
        {
            "ordId": "sap.sm:dataProduct:Supplier:v1",
            ...
        }
    ]
}

Ord Root Property

More information, see ord document

ORD Field	Type	Defaults	Preset/Annotation	Usage Example	Description
$schema	string	"https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json"	Preset	"$schema": "https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json"	Optional URL to the Open Resource Discovery document schema (defined as a JSON Schema).
openResourceDiscovery	string	-	-	-	1.9 (generated by plugin)
policyLevel	string	"none"	Preset	"policyLevel": "sap:core:v1"	The policy level (aka. compliance level) that this ORD Document or part of it needs to be compliant with.
description	string	"description": "this is an application description"	Preset	"description": "this is a custom description"	The description of the ORD Document itself.
Products Array	Array of JSON objects	----------	Preset ( as a full product list which will be overwritten)	-----------------	A product in ORD is understood as a commercial product or service.
ordId	string	"ordId": "customer:product:<namespace>:"		"ordId": "customer:product:sampleORDdemo:	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.
title	string	"title": "ORD App Title for <namespace>"		"title": "ORD App Title for sampleORDdemo"	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks.
shortDescription	string	"shortDescription": " shortDescription for products"		"shortDescription": " shortDescription for products"	Plain text short description.MUST NOT exceed 255 chars. MUST NOT contain line breaks.
vendor	string	"vendor": "customer:vendor:SAPCustomer:"		"vendor": "sap:vendor:SAPCustomer:"	Vendor / organization that is responsible for the Product.
groups Array	Array of JSON objects	-	-	-	Group (instance) that resources can be assigned to.hey express a "part of" relationship to the chosen group concept.
groupId	string	"groupId": "sap.cds:service:customer.<namespace>:sap.capire.incidents.ProcessorService"	-	-	The Group ID consists of two Concept IDs separated by a :.
groupTypeId	string	"groupTypeId": "sap.cds:service"	-	-	Group Type ID.
title	string	"title": "This is Processor Service title"	Annotation	annotate AdminService with @ORD.Extensions : {title : 'This is Admin Service title'};	Human readable title of the group assignment (for UI).
packages	Array of JSON objects	-	Present (as a full product list which will be overwritten)	-	A Package organizes a set of related resources together, by publishing and catalog presentation concerns.
ordId	string	"ordId":"customer.<namespace>:package:<namespace>:v1"			The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.
title	string	"title": "sample title for <namespace>"	-	-	Human-readable title.MUST NOT exceed 255 chars. MUST NOT contain line breaks.
shortDescription	string	"shortDescription": "Here is the shortDescription for packages"	-	-	Plain text short description.MUST NOT exceed 255 chars. MUST NOT contain line breaks.
description	string	"description": "Here is the description for packages",	-	-	Full description, notated in CommonMark (Markdown).
version	string	"version": "1.0.0"	-	-	The complete SemVer version string.
partOfProducts	Array of strings	"partOfProducts": ["customer:product:<namespace>:"]	-	-	List of products this resource is a part of.
vendor	string	"vendor": "customer:vendor:SAP:"	-	-	Vendor / organization that is the creator (or responsible party) of the resources that are part of the Package.
consumptionBundles	string	Array of JSON objects	Present (as a full consumptionBundles list which will be overwritten)	-	A Consumption Bundle groups APIs and Events together that can be consumed with the credentials and auth mechanism. Ideally it also includes instructions and details how to request access and credentials for resources.
ordId	string	"ordId": "customer.<namespace>:consumptionBundle:unknown:v1"	-	-	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.
version	string	"version": "1.0.0"	-	-	The complete SemVer version string.
title	string	"title": "Unprotected resources"	-	-	Human-readable title.MUST NOT exceed 255 chars. MUST NOT contain line breaks.
shortDescription	string	"shortDescription": "If we have another protected API then it will be another object"	-	-	Plain text short description.MUST NOT exceed 255 chars.MUST NOT contain line breaks.
description	string	"description": "This Consumption Bundle contains all resources of the reference app which are unprotected and do not require authentication"	-	-	Full description, notated in CommonMark (Markdown)
apiResources	Array of JSON Objects		Cannot be modified by the user ( The plugin generates based on the number of services defined in the CAP Application)		The API Resource provides a high-level description of an exposed API.
eventResources	Array of JSON Objects	-	Cannot be modified by the user ( The plugin generates based on the number of services that have events defined in the CAP Application)		The event resource provides a high-level description of a collection of related Events. More detailed information, such as the event resource definitions.