Skip to content

Latest commit

 

History

History
74 lines (60 loc) · 7.38 KB

ord.md

File metadata and controls

74 lines (60 loc) · 7.38 KB
Raw

cap-js ORD (Open Resource Discovery) Plugin

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',
    shortDescription: 'short description for Processor Service',
    visibility : 'public',
    extensible : {
      supported : 'no'
    }
};

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

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

The below is the table for all the supported ORD Fields containing defaults and how to overwrite the same.

Note: namespace is usually taken from .cdsrc.json, with a fallback to the package.json name.

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.