@cap-js/ord 1.0.3 → 1.1.0

package/README.md

@@ -4,9 +4,15 @@
 
 ## About this project
 
-This plugin enables generation of ORD document for CAP based applications. When you adopt ORD, your application gains a single entry point, known as the Service Provider Interface. This interface allows you to discover and gather relevant information or metadata. You can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system landscapes.
+This plugin adds support for the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) (ORD) protocol for CAP based applications.
+When you add the ORD plugin, your application gains a single entry point, which allows to discover and gather machine-readable information or metadata about the application.
+You can use this information to construct a static metadata catalog or to perform a detailed runtime inspection of your actual system instances / system landscapes.
 
-Open Resource Discovery [(ORD)](https://sap.github.io/open-resource-discovery/) is a protocol that enables applications and services to self-describe their available resources and capabilities. It's not only useful for describing static documentation, but it also accurately reflects tenant-specific configurations and extensions at runtime. Typically, ORD is used to describe APIs and Events, but it also supports higher-level concepts like Entity Types (Business Objects) and Data Products (beta).
+For more information, have a look at the [Open Resource Discovery](https://sap.github.io/open-resource-discovery/) page.
+
+> ⚠ By installing this plugin, the metadata describing your CAP application will be made openly accessible. 
+> 
+> If you have a need to protect your metadata, please refrain from installing this plugin until we support metadata protection (planned).
 
 ## Requirements and Setup
 
@@ -21,13 +27,13 @@ npm install @cap-js/ord
 #### Programmatic API
 
 ```js
-const cds = require('@sap/cds')
-require('@cap-js/ord');
+const cds = require("@sap/cds");
+require("@cap-js/ord");
 ```
 
 ```js
-const csn = await cds.load(cds.env.folders.srv)
-const ord = cds.compile.to.ord(csn)
+const csn = await cds.load(cds.env.folders.srv);
+const ord = cds.compile.to.ord(csn);
 ```
 
 #### Command Line
@@ -40,24 +46,28 @@ cds compile <path to srv folder> --to ord [-o] [destinationFilePath]
 
 #### ORD Endpoints
 
-1) Run `cds watch` in the application's root.
-2) Check the following relative paths for ORD information - `/.well-known/open-resource-discovery` , `/open-resource-discovery/v1/documents/1`.
-
+1. Run `cds watch` in the application's root.
+2. Check the following relative paths for ORD information - `/.well-known/open-resource-discovery` , `/open-resource-discovery/v1/documents/1`.
 
 <img width="1300" alt="Sample Application Demo" style="border-radius:0.5rem;" src="./asset/etc/ordEndpoint.gif">
 
 ### Customizing ORD Document
 
-You can find more information, such as how to customize the ORD Document, in this [document](ord.md).
-
+You can find more information, such as how to customize the ORD Document, in this [document](./docs/ord.md).
 
 ## Support, Feedback, Contributing
 
 This project is open to feature requests/suggestions, bug reports etc. via [GitHub issues](https://github.com/cap-js/ord/issues). Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our [Contribution Guidelines](CONTRIBUTING.md).
 
 ## Security / Disclosure
+
 If you find any bug that may be a security problem, please follow our instructions at [in our security policy](https://github.com/cap-js/ord/issues/security/policy) on how to report it. Please do not create GitHub issues for security-related doubts or problems.
 
+At the current state, the plugin will expose static metadata with open access.
+This means that the CAP resources are described and documented openly, but it does not imply that the resources themselves can be accessed.
+
+If you have a need to protect your metadata, please refrain from installing this plugin until we support metadata protection.
+
 ## Code of Conduct
 
 We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its [Code of Conduct](https://github.com/cap-js/.github/blob/main/CODE_OF_CONDUCT.md) at all times.

package/lib/constants.js

@@ -0,0 +1,25 @@
+const ORD_RESOURCE_TYPE = Object.freeze(
+    {
+        "service": "service",
+        "entity": "entity",
+        "event": "event",
+        "api": "api"
+    });
+
+const COMPILER_TYPES = Object.freeze(
+    {
+        "oas3": "oas3",
+        "asyncapi2": "asyncapi2",
+        "edmx": "edmx"
+    });
+
+const CONTENT_MERGE_KEY = "ordId";
+
+const ORD_EXTENSIONS_PREFIX = "@ORD.Extensions.";
+
+module.exports = {
+    ORD_RESOURCE_TYPE,
+    COMPILER_TYPES,
+    CONTENT_MERGE_KEY,
+    ORD_EXTENSIONS_PREFIX
+};

package/lib/defaults.js

@@ -1,66 +1,84 @@
-
 const regexWithRemoval = (name) => {
-  if(name){
-    return name.replace(/[^a-zA-Z0-9]/g,'');
-  }
-}
-const regexWithUnderScore = (name) => {
-  return regexWithRemoval(name.charAt(0)) + name.slice(1, name.length).replace(/[^a-zA-Z0-9]/g,'_');
-}
+    if (name) {
+        return name.replace(/[^a-zA-Z0-9]/g, "");
+    }
+};
+
+const nameWithDot = (name) => {
+    return (
+        regexWithRemoval(name.charAt(0)) +
+        name.slice(1, name.length).replace(/[^a-zA-Z0-9]/g, ".")
+    );
+};
+
+const nameWithSpaces = (name) => {
+    return (
+        regexWithRemoval(name.charAt(0)) +
+        name.slice(1, name.length).replace(/[^a-zA-Z0-9]/g, " ")
+    );
+};
+
+const defaultProductOrdId = (name) => `customer:product:${nameWithDot(name)}:`;
 
 /**
  * Module containing default configuration for ORD Document.
  * @module defaults
  */
 module.exports = {
-  openResourceDiscovery: "1.9",
-  policyLevel: "none",
-  description: "this is an application description",
-  products: (name) => [
-    { 
-      ordId: `customer:product:${regexWithUnderScore(name)}:`,
-      title: `ORD App Title for ${regexWithRemoval(name)}`,
-      shortDescription: " shortDescription for products",
-      vendor: "customer:vendor:SAPCustomer:",
-    },
-  ],
-  groupTypeId: "sap.cds:service", 
-  packages: function getPackageData (name, policyLevel,capNamespace) {
-    function createPackage(name, tag) {
-      return {
-        ordId: `${regexWithRemoval(name)}:package:${capNamespace}${tag}`,
-        title: `sample title for ${regexWithRemoval(name)}`,
-        shortDescription: "Here is the shortDescription for packages",
-        description: "Here is the description for packages",
-        version: "1.0.0",
-        partOfProducts: [`customer:product:${regexWithUnderScore(name)}:`],
-        vendor: "customer:vendor:SAP:"
-      };
-    }
-    
-    if(policyLevel.split(':')[0].toLowerCase() === 'sap') {
-        return [createPackage(name, "-api:v1"), createPackage(name, "-event:v1")];
-    }
-    else {
-        return [createPackage(name, ":v1")];
-    }
-  },
-  consumptionBundles: (name) => [
-    {
-      ordId: `${regexWithRemoval(name)}:consumptionBundle:unknown:v1`,
-      version: "1.0.0",
-      title: "Unprotected resources",
-      shortDescription:
-        "If we have another protected API then it will be another object",
-      description:
-        "This Consumption Bundle contains all resources of the reference app which are unprotected and do not require authentication",
+    $schema:
+        "https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json",
+    openResourceDiscovery: "1.9",
+    policyLevel: "none",
+    description: "this is an application description",
+    products: (name) => [
+        {
+            ordId: defaultProductOrdId(name),
+            title: nameWithSpaces(name),
+            shortDescription: "Description for " + nameWithSpaces(name),
+            vendor: "customer:vendor:customer:",
+        },
+    ],
+    groupTypeId: "sap.cds:service",
+    packages: function getPackageData(name, policyLevel, ordNamespace) {
+        function createPackage(name, tag) {
+            return {
+                ordId: `${ordNamespace}:package:${regexWithRemoval(name
+                )}${tag}`,
+                title: nameWithSpaces(name),
+                shortDescription:
+                    "Short description for " + nameWithSpaces(name),
+                description: "Description for " + nameWithSpaces(name),
+                version: "1.0.0",
+                partOfProducts: [defaultProductOrdId(name)],
+                vendor: "customer:vendor:Customer:",
+            };
+        }
+
+        if (policyLevel.split(":")[0].toLowerCase() === "sap") {
+            return [
+                createPackage(name, "-api:v1"),
+                createPackage(name, "-event:v1"),
+            ];
+        } else {
+            return [createPackage(name, ":v1")];
+        }
     },
-  ],
- 
+    consumptionBundles: (name) => [
+        {
+            ordId: `${regexWithRemoval(name)}:consumptionBundle:unknown:v1`,
+            version: "1.0.0",
+            title: "Unprotected resources",
+            shortDescription:
+                "If we have another protected API then it will be another object",
+            description:
+                "This Consumption Bundle contains all resources of the reference app which are unprotected and do not require authentication",
+        },
+    ],
+
     apiResources: [],
     eventResources: [],
     entityTypes: [],
-    baseTemplate : {
+    baseTemplate: {
         openResourceDiscoveryV1: {
             documents: [
                 {
@@ -73,5 +91,5 @@ module.exports = {
                 },
             ],
         },
-    }
-}
+    },
+};

package/lib/extendOrdWithCustom.js

@@ -0,0 +1,67 @@
+const path = require("path");
+const cds = require("@sap/cds");
+const _ = require('lodash');
+const { CONTENT_MERGE_KEY } = require('./constants');
+
+
+function cleanNullProperties(obj) {
+    for (const key in obj) {
+        if (obj[key] === null) {
+            delete obj[key];
+        } else if (typeof obj[key] === 'object') {
+            cleanNullProperties(obj[key]);
+        }
+    }
+    return obj;
+}
+
+function patchGeneratedOrdResources(destinationObj, sourceObj) {
+    const destObj = _.keyBy(destinationObj, CONTENT_MERGE_KEY);
+    const srcObj = _.keyBy(sourceObj, CONTENT_MERGE_KEY);
+    for (const ordId in srcObj) {
+        if (ordId in destObj) {
+            destObj[ordId] = _.assignWith(structuredClone(destObj[ordId]), structuredClone(srcObj[ordId]));
+        } else {
+            destObj[ordId] = srcObj[ordId];
+        }
+    }
+    return cleanNullProperties(Object.values(destObj));
+}
+
+function compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent, logger) {
+    const clonedOrdContent = structuredClone(ordContent);
+    for (const key in customORDContent) {
+        const propertyType = typeof customORDContent[key];
+        if (propertyType !== 'object' && propertyType !== 'array') {
+            logger.warn('Found ord top level primitive ord property in customOrdFile:', key, ', please define it in .cdsrc.json.');
+            continue;
+        }
+        if (key in ordContent) {
+            clonedOrdContent[key] = patchGeneratedOrdResources(clonedOrdContent[key], customORDContent[key]);
+        } else {
+            clonedOrdContent[key] = customORDContent[key];
+        }
+    }
+    return clonedOrdContent;
+}
+
+function getCustomORDContent(appConfig) {
+    if (appConfig.env?.customOrdContentFile) {
+        const customORDContent = require(path.join(cds.root, appConfig.env.customOrdContentFile));
+        return customORDContent;
+    }
+    return {};
+}
+
+function extendCustomORDContentIfExists(appConfig, ordContent, logger) {
+    const customORDContent = getCustomORDContent(appConfig);
+
+    if (customORDContent) {
+        ordContent = compareAndHandleCustomORDContentWithExistingContent(ordContent, customORDContent, logger);
+    }
+    return ordContent;
+}
+
+module.exports = {
+    extendCustomORDContentIfExists,
+};

package/lib/metaData.js

@@ -1,43 +1,41 @@
 const cds = require('@sap/cds/lib');
-const { compile : openapi } = require('@cap-js/openapi')
-const { compile : asyncapi } = require('@cap-js/asyncapi');
+const { compile: openapi } = require('@cap-js/openapi')
+const { compile: asyncapi } = require('@cap-js/asyncapi');
+const { COMPILER_TYPES } = require('./constants');
 
-/**
- * Retrieves the compiled meta data for the specific service or event according to its compiled type
- * @param {string} data 
- * @returns {string, JSON|XML} contentType, response 
- */
 module.exports = async (data) => {
     const parts = data?.split("/").pop().replace(/\.json$/, '').split(".");
     const compilerType = parts.pop();
     const serviceName = parts.join(".");
     const csn = cds.services[serviceName].model;
 
-    let responseFile; 
+    let responseFile;
     const options = { service: serviceName, as: 'str', messages: [] }
-    if (compilerType === "oas3") {
-        try {
-            responseFile = openapi(csn, options);
-        } catch (error) {
-            console.error("OpenApi error:", error.message);
-            throw error;
-        }
-    } else if (compilerType === "asyncapi2") {
-        try {
-            responseFile = asyncapi(csn, options);
-        } catch (error) {
-            console.error("AsyncApi error:", error.message);
-            throw error;
-        }
-    } else if (compilerType === "edmx") {
-        try {
-            responseFile = await cds.compile(csn).to["edmx"](options);
-        } catch (error) {
-            console.error("Edmx error:", error.message);
-            throw error;
-        }
+    switch (compilerType) {
+        case COMPILER_TYPES.oas3:
+            try {
+                responseFile = openapi(csn, options);
+            } catch (error) {
+                console.error("OpenApi error:", error.message);
+                throw error;
+            }
+            break;
+        case COMPILER_TYPES.asyncapi2:
+            try {
+                responseFile = asyncapi(csn, options);
+            } catch (error) {
+                console.error("AsyncApi error:", error.message);
+                throw error;
+            }
+            break;
+        case COMPILER_TYPES.edmx:
+            try {
+                responseFile = await cds.compile(csn).to["edmx"](options);
+            } catch (error) {
+                console.error("Edmx error:", error.message);
+                throw error;
+            }
     }
-
     return {
         contentType: `application/${compilerType === "edmx" ? "xml" : "json"}`,
         response: responseFile

package/lib/ord.js

@@ -1,202 +1,166 @@
 const path = require("path");
 const cds = require("@sap/cds");
 const { exists } = cds.utils;
+const _ = require("lodash");
 const defaults = require("./defaults");
 const {
-    fCreateAPIResourceTemplate,
-    fCreateEventResourceTemplate,
-    fCreateGroupsTemplateForService,
-    fCreateGroupsTemplateForEvent,
-    fCreateEntityTypeTemplate
+    createAPIResourceTemplate,
+    createEventResourceTemplate,
+    createGroupsTemplateForService,
+    createEntityTypeTemplate
 } = require('./templates');
+const { extendCustomORDContentIfExists } = require('./extendOrdWithCustom');
+const { ORD_RESOURCE_TYPE } = require('./constants');
 
-/**
- * Initializes global object based on package.json and CSN object.
- * @param {Object} csn object
- * @returns {Object} An object containing global variables.
- */
-const fInitializeGlobal = (csn) => {
-    let packagejsonPath = path.join(cds.root,'package.json')
+const logger = cds.log('ord-plugin');
+
+const initializeAppConfig = (csn) => {
+    let packagejsonPath = path.join(cds.root, 'package.json')
     let packageJson;
     if (exists(packagejsonPath)) {
         packageJson = require(packagejsonPath);
     } else {
         throw new Error(`package.json not found in the project root directory`);
     }
+    const packageName = packageJson.name;
     const appName = packageJson.name.replace(/^[@]/, "").replace(/[@/]/g, "-");
-    const aModelKeys = Object.keys(csn.definitions);
-    const aEvents = [];
-    const aServices = [];
-    const aODMEntity = [];
-    
-    const capNamespace = csn.namespace;
-     // namespace variable value if present in cdsrc.json take it there or else from package.json
+    const modelKeys = Object.keys(csn.definitions);
+    const events = [];
+    const serviceNames = [];
+    let odmEntity = [];
+
+    // namespace variable value if present in cdsrc.json take it there or else from package.json
     //if cdsrc.json does not have applicationNamespace, then use just the namespace
-    const namespace = cds.env["ord"]?.namespace || `customer.${appName}`;
-    const applicationNamespace = cds.env?.export?.asyncapi?.applicationNamespace;
-    
-    if (applicationNamespace && fGetNamespaceComponents(namespace) !== fGetNamespaceComponents(applicationNamespace)) {
-        console.warn('ORD and AsyncAPI namespaces should be the same.');
-    }
+    const vendorNamespace = "customer";
+    const ordNamespace = cds.env["ord"]?.namespace || `${vendorNamespace}.${packageName.replace(/[^a-zA-Z0-9]/g, "")}`;
+    const eventApplicationNamespace = cds.env?.export?.asyncapi?.applicationNamespace;
 
-    const fEventFilter = (keyDefinition) => keyDefinition.kind === "event";
-    const fServicesFilter = (keyDefinition) => keyDefinition.kind === "service" && !keyDefinition['@cds.external'];
-    const fODMEntityFilter = (key, keyDefinition) => {
-        return keyDefinition.kind === "entity"
-            && key.includes(capNamespace)
-            && !key.includes(".texts")
-            && keyDefinition["@ODM.entityName"];
+    if (eventApplicationNamespace && ordNamespace !== eventApplicationNamespace) {
+        console.warn("ORD and AsyncAPI namespaces should be the same.");
     }
 
-    aModelKeys.forEach((key) => {
+    for (const key of modelKeys) {
         const keyDefinition = csn.definitions[key];
-        if(fServicesFilter(keyDefinition)){
-            aServices.push(key);
-        } else if(fODMEntityFilter(key, keyDefinition)) {
-            aODMEntity.push(fCreateEntityTypeTemplate(keyDefinition));
-        } else if(fEventFilter(keyDefinition)){
-            aEvents.push(key);
+        switch (keyDefinition.kind) {
+            case ORD_RESOURCE_TYPE.service:
+                if (!keyDefinition["@cds.external"]) {
+                    serviceNames.push(key);
+                }
+                break;
+            // TODO: should be rewritten
+            case ORD_RESOURCE_TYPE.entity:
+                if (!key.includes(".texts") && keyDefinition["@ODM.entityName"]) {
+                    odmEntity.push(createEntityTypeTemplate(keyDefinition));
+                }
+                break;
+            case ORD_RESOURCE_TYPE.event:
+                events.push(key);
+                break;
         }
-    });
+    }
 
+    odmEntity = _.uniqBy(odmEntity, "ordId");
 
     return {
         env: cds.env["ord"],
-        capNamespace,
         appName,
-        aEvents,
-        aServices,
-        aODMEntity,
-        namespace,
-        applicationNamespace
-    }
-}
+        events,
+        serviceNames,
+        odmEntity,
+        ordNamespace,
+        eventApplicationNamespace,
+        packageName,
+    };
+};
+
+const _getPolicyLevel = (appConfig) =>
+    appConfig.env?.policyLevel || defaults.policyLevel;
+
+const _getDescription = (appConfig) =>
+    appConfig.env?.description || defaults.description;
+
+const _getProducts = (appConfig) =>
+    appConfig.env?.products || defaults.products(appConfig.packageName);
 
-/**
- * Retrieves first two components of the namespace.
- * @param {string} namespace
- * @returns {string} The first two components of the namespace.
- */
-const fGetNamespaceComponents = (namespace) => namespace.split('.').slice(0, 2).join('.');
-
-/**
- * Retrieves the policy level.
- * Hierarchy to check data: cdsrc.json > defaults
- * @returns {string} The policy level.
- */
-const fGetPolicyLevel = (global) => global.env?.policyLevel || defaults.policyLevel;
-
-/**
- * Retrieves the root level ORD document description.
- * Hierarchy to check data: cdsrc.json > defaults
- * @returns {string} The ORD document description.
- */
-const fGetDescription = (global) => global.env?.description || defaults.description;
-
-/**
- * Retrieves the products.
- * Hierarchy to check data: cdsrc.json > defaults
- * @returns {Array<object>} The products array.
- * if global.namespace is defined in cdsrc.json, then use it, else use the appName from package.json
- */
-const fGetProducts = (global) => global.env?.products || defaults.products(global.namespace);
-
-/**
- * Retrieves the groups that services belongs to.
- * Gets list of groups from CDS runtime object.
- * @param {Object} csn object 
- * @returns {Array<object>} The groups array.
- */
-const fGetGroups = (csn, global) => {
-    // storing the group ids in a set to avoid duplicates
-    let groupIds = new Set();
-
-    let serviceGroups = global.aServices
-            .map((srv) => fCreateGroupsTemplateForService(srv, csn.definitions[srv], groupIds))
-            .filter((resource) => resource !== null && resource !== undefined);
-    let eventGroups = global.aEvents
-            .map((event) => fCreateGroupsTemplateForEvent(event, csn.definitions[event], groupIds))
-            .filter((resource) => resource !== null && resource !== undefined);
-
-    return [...serviceGroups, ...eventGroups];
+const _getGroups = (csn, appConfig) => {
+    return appConfig.serviceNames
+        .flatMap((serviceName) => createGroupsTemplateForService(serviceName, csn.definitions[serviceName], appConfig))
+        .filter((resource) => !!resource);
 };
 
-/**
- * Retrieves the packages.
- * Hierarchy to check data: cdsrc.json > defaults
- * @returns {Array<object>} The packages array.
- */
-const fGetPackages = (policyLevel,global) => global.env?.packages || (global.aEvents.length) ? defaults.packages(global.namespace,policyLevel,global.capNamespace) : defaults.packages(global.namespace,policyLevel,global.capNamespace).slice(0, 1)
-
-/**
- * Retrieves the consumption bundles.
- * Hierarchy to check data: cdsrc.json > defaults
- * @returns {Array<object>} The consumption bundles array.
- */
-const fGetConsumptionBundles = (global) => global.env?.consumptionBundles || (global.aEvents.length) ? defaults.consumptionBundles(global.capNamespace) : defaults.consumptionBundles(global.capNamespace).slice(0,1)
-
-/**
- * Retrieves the API Resources
- * Gets list of services from CSN object
- * @param {Object} csn object
- * @returns {Array<object>} The API Resources array.
- */
-const fGetAPIResources = (csn, global,packageIds) => {
-  const apiResources = [];
-  global.aServices.forEach((srv) => {
-    fCreateAPIResourceTemplate(srv, csn.definitions[srv], global,packageIds)?.forEach(
-      (resource) => {
-        if (resource !== null && resource !== undefined) {
-          apiResources.push(resource);
-        }
-      }
-    );
-  });
-  return apiResources;
+const _getPackages = (policyLevel, appConfig) =>
+    appConfig.env?.packages || appConfig.events.length
+        ? defaults.packages(appConfig.appName, policyLevel, appConfig.ordNamespace)
+        : defaults
+            .packages(appConfig.appName, policyLevel, appConfig.ordNamespace)
+            .slice(0, 1);
+
+const _getAPIResources = (csn, appConfig, packageIds) => {
+    return appConfig.serviceNames
+        .flatMap((serviceName) => createAPIResourceTemplate(serviceName, csn.definitions[serviceName], appConfig, packageIds) || [])
+        .filter((resource) => !!resource);
 };
 
-/**
- * Retrieves the Event Resources
- * Gets list of event from CSN object
- * @param {Object} csn object
- * @returns {Array<object>} The Event Resources array.
- */
-const fGetEventResources = (csn, global,packageIds) => global.aEvents.map((srv) => fCreateEventResourceTemplate(srv, csn.definitions[srv], global, packageIds)).filter((resource) => resource !== null && resource !== undefined);
+const _getEventResources = (csn, appConfig, packageIds) => {
+    if (appConfig.events.length === 0) return [];
+    return appConfig.serviceNames
+        .filter((serviceName) => appConfig.events.some((eventName) => eventName.startsWith(serviceName)))
+        .flatMap((serviceName) => createEventResourceTemplate(serviceName, csn.definitions[serviceName], appConfig, packageIds) || []);
+};
 
-module.exports = (csn) => {
-    const linkedCsn = cds.linked(csn);
-    Object.assign(global, fInitializeGlobal(linkedCsn));
-    const validateSystemNamespace = new RegExp(`^${global.applicationNamespace}\\.[^.]+\\..+$`);
-    if (global.namespace === undefined && !validateSystemNamespace.test(global.namespace)) {
-        let error = new Error(`Namespace is not defined in cdsrc.json or it is not in the format of ${global.applicationNamespace}.<appName>.<service>`);
-        console.error('Namespace error:', error.message);
+function validateNamespace(appConfig) {
+    const validateSystemNamespace = new RegExp(`^${appConfig.eventApplicationNamespace}\\.[^.]+\\..+$`);
+    if (
+        appConfig.ordNamespace === undefined &&
+        !validateSystemNamespace.test(appConfig.ordNamespace)
+    ) {
+        let error = new Error(
+            `Namespace is not defined in cdsrc.json or it is not in the format of ${appConfig.eventApplicationNamespace}.<appName>.<service>`
+        );
+        console.error("Namespace error:", error.message);
         throw error;
     }
+}
 
-    let oReturn = {openResourceDiscovery: "1.9",
-        policyLevel: fGetPolicyLevel(global),
-        description: fGetDescription(global),
-        products: fGetProducts(global),
-        groups: fGetGroups(linkedCsn, global),
+function createDefaultORDDocument(linkedCsn, appConfig) {
+    let ordDocument = {
+        $schema: "https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json",
+        openResourceDiscovery: "1.9",
+        policyLevel: _getPolicyLevel(appConfig),
+        description: _getDescription(appConfig),
+        products: _getProducts(appConfig),
+        groups: _getGroups(linkedCsn, appConfig),
     };
-    if(fGetAPIResources(linkedCsn, global).length > 0 && (fGetEventResources(linkedCsn, global).length>0)){
-        oReturn.packages = fGetPackages(oReturn.policyLevel, global);
-    }
 
-    // check if oReturn.packages is defined and extract the ordId from the packages and store in a set
-    let packageIds = new Set();
-    if(oReturn.packages){
-        oReturn.packages.forEach((pkg) => {
-            packageIds.add(pkg.ordId);
-        });
+    if (_getAPIResources(linkedCsn, appConfig).length && _getEventResources(linkedCsn, appConfig).length) {
+        ordDocument.packages = _getPackages(ordDocument.policyLevel, appConfig);
     }
-    oReturn = {
-        ...oReturn,
-        consumptionBundles: fGetConsumptionBundles(global),
-        apiResources: fGetAPIResources(linkedCsn, global,packageIds),
-    };
-    if(fGetEventResources(linkedCsn, global,packageIds).length > 0) {
-        oReturn.eventResources= fGetEventResources(linkedCsn, global,packageIds);
+    return ordDocument;
+}
+
+function extractPackageIds(ordDocument) {
+    const packageIds = new Set();
+    if (ordDocument.packages) {
+        ordDocument.packages.map((pkg) => packageIds.add(pkg.ordId));
     }
-    return oReturn;
+    return packageIds;
 }
+
+module.exports = (csn) => {
+    const linkedCsn = cds.linked(csn);
+    const appConfig = initializeAppConfig(linkedCsn);
+    validateNamespace(appConfig);
+
+    let ordDocument = createDefaultORDDocument(linkedCsn, appConfig);
+    const packageIds = extractPackageIds(ordDocument);
+    // TODO: add testcase without apiResources or event, no empty package
+    ordDocument.apiResources = _getAPIResources(linkedCsn, appConfig, packageIds);
+    const eventResources = _getEventResources(linkedCsn, appConfig, packageIds);
+    if (eventResources.length) {
+        ordDocument.eventResources = eventResources;
+    }
+
+    ordDocument = extendCustomORDContentIfExists(appConfig, ordDocument, logger);
+
+    return ordDocument;
+};

package/lib/templates.js

@@ -1,25 +1,26 @@
 const defaults = require("./defaults");
 const cds = require("@sap/cds");
-const fReplaceSpecialCharacters = (namespace) => {
-  return namespace.replace(/customer\.(.+)/, (match, group1) => 'customer.' + group1.replace(/[^a-zA-Z0-9]/g, ''))
+const _ = require("lodash");
+const { ORD_EXTENSIONS_PREFIX } = require("./constants");
+
+function unflatten(flattedObject) {
+    let result = {}
+    _.keys(flattedObject).forEach(function (key) {
+        _.set(result, key, flattedObject[key])
+    })
+    return result
 }
 
-/**
- * Reads the ORD (Open Resource Discovery) annotation from a given service definition object and returns them as an object.
- *
- * @param {Object} srv The service definition object.
- * @returns {Object} An object containing ORD annotation.
- */
-const fReadORDExtensions = (srv) =>
-  Object.entries(srv)
-    .filter(([key]) => key.startsWith("@ORD.Extensions."))
-    .reduce(
-      (ordExtensions, [key, value]) => ({
-        ...ordExtensions,
-        [key.slice("@ORD.Extensions.".length)]: value,
-      }),
-      {}
-    );
+function readORDExtensions(model) {
+    const ordExtensions = {};
+    for (const key in model) {
+        if (key.startsWith(ORD_EXTENSIONS_PREFIX)) {
+            const ordKey = key.replace(ORD_EXTENSIONS_PREFIX, "");
+            ordExtensions[ordKey] = model[key];
+        }
+    }
+    return unflatten(ordExtensions);
+}
 
 /**
  * Reads the service definition and returns an array of entryPoint paths.
@@ -29,28 +30,28 @@ const fReadORDExtensions = (srv) =>
  * @returns {Array} An array containing paths and it's kind.
  */
 
-const fGeneratePaths = (srv, srvDefinition) => {
-  const srvObj = { name: srv, definition: srvDefinition };
-  const protocols = cds.service.protocols;
+const _generatePaths = (srv, srvDefinition) => {
+    const srvObj = { name: srv, definition: srvDefinition };
+    const protocols = cds.service.protocols;
 
-  const paths = protocols.endpoints4(srvObj);
+    const paths = protocols.endpoints4(srvObj);
 
-  //TODO: check graphql replication in paths object and re-visit logic
-  //removing instances of graphql protocol from paths
-  for (var index = paths.length - 1; index >= 0; index--) {
-    if (paths[index].kind === "graphql") {
-      console.warn("Graphql protocol is not supported.");
-      paths.splice(index, 1);
+    //TODO: check graphql replication in paths object and re-visit logic
+    //removing instances of graphql protocol from paths
+    for (var index = paths.length - 1; index >= 0; index--) {
+        if (paths[index].kind === "graphql") {
+            console.warn("Graphql protocol is not supported.");
+            paths.splice(index, 1);
+        }
     }
-  }
 
-  //putting default as odata in case no supported protcol is there
-  if (paths.length === 0) {
-    srvDefinition["@odata"] = true;
-    paths.push({ kind: "odata", path: protocols.path4(srvDefinition) });
-  }
+    //putting default as odata in case no supported protcol is there
+    if (paths.length === 0) {
+        srvDefinition["@odata"] = true;
+        paths.push({ kind: "odata", path: protocols.path4(srvDefinition) });
+    }
 
-  return paths;
+    return paths;
 };
 
 /**
@@ -59,30 +60,21 @@ const fGeneratePaths = (srv, srvDefinition) => {
  * @param {string} entity The name of the entity.
  * @returns {Object} An object for the entity type.
  */
-const fCreateEntityTypeTemplate = (entity) => ({
-  ordId: `sap.odm:entityType:${entity["@ODM.entityName"]}:v1`,
+const createEntityTypeTemplate = (entity) => ({
+    ordId: `sap.odm:entityType:${entity["@ODM.entityName"]}:v1`,
 });
 
-/**
- * This is a template function to form the group id.
- * 
- * @param {string} fullyQualifiedName The fully qualified name of the service or event.
- * @param {string} groupTypeId The group type id.
- * @returns {string} a group id.
- */
-function _getGroupID(fullyQualifiedName, groupTypeId = defaults.groupTypeId, isService = true) {
-    if (isService) {
-        return `${groupTypeId}:${fReplaceSpecialCharacters(global.namespace)}:${fullyQualifiedName}`;
-    } else {
-        return `${groupTypeId}:${fReplaceSpecialCharacters(global.namespace)}:` +
-                `${fullyQualifiedName.slice(0, fullyQualifiedName.lastIndexOf("."))}`;
-    }
+function _getGroupID(
+    fullyQualifiedName,
+    groupTypeId = defaults.groupTypeId,
+    appConfig,
+) {
+    return `${groupTypeId}:${appConfig.ordNamespace}:${fullyQualifiedName}`;
 }
 
-
 /**
  * This is a function to resolve the title of the service group.
- * 
+ *
  * @param {string} srv The name of the service.
  * @returns {string} The title of the service group.
  */
@@ -90,265 +82,146 @@ function _getTitleFromServiceName(srv) {
     let serviceName = srv.substring(srv.lastIndexOf(".") + 1);
     let index = serviceName.indexOf("Service");
     if (index >= 0) {
-        return `${serviceName.substring(0, index)} Service Title`;
+        return `${serviceName.substring(0, index)} Service`;
     } else {
-        return `${serviceName} Service Title`;
+        return `${serviceName} Service`;
     }
 }
 
-
 /**
  * This is a template function to create group object of a service for groups array in ORD doc.
- * 
- * @param {string} srv The name of the service.
- * @param {object} srvDefinition The definition of the service
+ *
+ * @param {string} serviceName The name of the service.
+ * @param {object} serviceDefinition The definition of the service
  * @param {Set} groupIds A set of group ids.
  * @returns {Object} A group object.
  */
-const fCreateGroupsTemplateForService = (srv, srvDefinition, groupIds) => {
-    const ordExtensions = fReadORDExtensions(srvDefinition);
+const createGroupsTemplateForService = (serviceName, serviceDefinition, appConfig) => {
+    const ordExtensions = readORDExtensions(serviceDefinition);
 
-    let fullyQualifiedServiceName = srv;
-    if(!srv.includes(global.capNamespace)){
-      fullyQualifiedServiceName = global.capNamespace + "." + srv;
+    if (!serviceDefinition) {
+        console.warn("Unable to find service definition:", serviceName)
+        return undefined
     }
 
-    if (checkEntityFunctionAction(srvDefinition, global).length > 0) {
-      let groupId = _getGroupID(fullyQualifiedServiceName, defaults.groupTypeId);
-      if (groupIds.has(groupId)) {
-          return null;
-      } else {
-          groupIds.add(groupId);
-          return {
-              groupId: groupId,
-              groupTypeId: `${defaults.groupTypeId}`,
-              title: ordExtensions.title ?? _getTitleFromServiceName(srv)
-          };
-      }
-    }
-}
-
-/**
- * 
- * @param {string} event The name of the event. 
- * @returns {string} The title of the event group.
- */
-function _getEventTitle(event) {
-    let serviceName = event.substring(0, event.lastIndexOf("."));
-    return _getTitleFromServiceName(serviceName);
-}
-
-/**
- * This is a template function to create group object of an event for groups array in ORD doc.
- * 
- * @param {string} event The name of the event.
- * @param {object} eventDefinition The definition of the event.
- * @param {Set} groupIds A set of group ids.
- * @returns {Object} A group object.
- */
-const fCreateGroupsTemplateForEvent = (event, eventDefinition, groupIds) => {
-    const ordExtensions = fReadORDExtensions(eventDefinition);
-
-    let fullyQualifiedEventName = event;
-    if(!event.includes(global.capNamespace)){
-      fullyQualifiedEventName = global.capNamespace + "." + event;
-    }
-
-    let groupId = _getGroupID(fullyQualifiedEventName, defaults.groupTypeId, global, false);
-    if (groupIds.has(groupId)) {
-        return null;
-    } else {
-        groupIds.add(groupId);
-        return {
-            groupId: groupId,
-            groupTypeId: `${defaults.groupTypeId}`,
-            title: ordExtensions.title ?? _getEventTitle(event)
-        };
-    }
+    const groupId = _getGroupID(serviceName, defaults.groupTypeId, appConfig);
+    return {
+        groupId: groupId,
+        groupTypeId: defaults.groupTypeId,
+        title: ordExtensions.title ?? _getTitleFromServiceName(serviceName)
+    };
 }
 
 /**
  * This is a template function to create API Resource object for API Resource Array.
  *
- * @param {string} srv The name of the service.
- * @param {object} srvDefinition The definition of the service
+ * @param {string} serviceName The name of the service.
+ * @param {object} serviceDefinition The definition of the service
  * @returns {Array} An array of objects for the API Resources.
  */
-const fCreateAPIResourceTemplate = (srv, srvDefinition, global,packageIds) => {
-  const ordExtensions = fReadORDExtensions(srvDefinition);
-  const paths = fGeneratePaths(srv, srvDefinition);
-  const apiResources = [];
+const createAPIResourceTemplate = (serviceName, serviceDefinition, appConfig, packageIds) => {
+    const ordExtensions = readORDExtensions(serviceDefinition);
+    const paths = _generatePaths(serviceName, serviceDefinition);
+    const apiResources = [];
 
-  let srvName = srv;
-  if (!srvName.includes(global.capNamespace)) {
-    srvName = global.capNamespace + "." + srv;
-  }
-
-  if (checkEntityFunctionAction(srvDefinition, global).length > 0) {
     paths.forEach((generatedPath) => {
-      let resourceDefinitions = [
-        {
-          type: "openapi-v3",
-          mediaType: "application/json",
-          url: `/.well-known/open-resource-discovery/v1/api-metadata/${srv}.oas3.json`,
-          accessStrategies: [{ type: "open" }],
-        },
-      ];
+        let resourceDefinitions = [
+            {
+                type: "openapi-v3",
+                mediaType: "application/json",
+                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.oas3.json`,
+                accessStrategies: [{ type: "open" }],
+            },
+        ];
+
+        if (generatedPath.kind !== "rest") {
+            //edmx resource definition is not generated in case of 'rest' protocol
+            resourceDefinitions.push({
+                type: "edmx",
+                mediaType: "application/xml",
+                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.edmx`,
+                accessStrategies: [{ type: "open" }],
+            });
+        }
+
+        let obj = {
+            ordId: `${appConfig.ordNamespace}:apiResource:${serviceName}:v1`,
+            title:
+                serviceDefinition["@title"] ??
+                serviceDefinition["@Common.Label"] ??
+                serviceName,
+            shortDescription: serviceName,
+            description:
+                serviceDefinition["@Core.Description"] ??
+                serviceName,
+            version: "1.0.0",
+            visibility: "public",
+            partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, "api"),
+            partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
+            releaseStatus: "active",
+            apiProtocol:
+                generatedPath.kind === "odata" ? "odata-v4" : generatedPath.kind,
+            resourceDefinitions: resourceDefinitions,
+            entryPoints: [generatedPath.path],
+            extensible: {
+                supported: "no",
+            },
+            entityTypeMappings: [{ entityTypeTargets: appConfig.odmEntity }],
+
+            ...ordExtensions,
+        };
+
+        apiResources.push(obj);
+    });
 
-      if (generatedPath.kind !== "rest") {
-        //edmx resource definition is not generated in case of 'rest' protocol
-        resourceDefinitions.push({
-          type: "edmx",
-          mediaType: "application/xml",
-          url: `/.well-known/open-resource-discovery/v1/api-metadata/${srv}.edmx`,
-          accessStrategies: [{ type: "open" }],
-        });
-      }
+    if (apiResources.length > 0) return apiResources;
+};
 
-      let obj = {
-        ordId: `${fReplaceSpecialCharacters(global.namespace)}:apiResource:${srvName}:v1`,
+const createEventResourceTemplate = (serviceName, eventDefinition, appConfig, packageIds) => {
+    const ordExtensions = readORDExtensions(eventDefinition);
+    return {
+        ordId: `${appConfig.ordNamespace}:eventResource:${serviceName}:v1`,
         title:
-          ordExtensions.title ??
-          srvDefinition["@title"] ??
-          srvDefinition["@Common.Label"] ??
-          `The service is for ${srv}`,
-        shortDescription:
-          ordExtensions.shortDescription ??
-          `Here we have the shortDescription for ${srv}`,
+            eventDefinition["@title"] ??
+            eventDefinition["@Common.Label"] ??
+            `ODM ${appConfig.appName.replace(/[^a-zA-Z0-9]/g, "")} Events`,
+        shortDescription: `${serviceName} event resource`,
         description:
-          ordExtensions.description ??
-          srvDefinition["@Core.Description"] ??
-          `Here we have the description for ${srv}`,
-        version: ordExtensions.version ?? "1.0.0",
-        visibility: ordExtensions.visibility ?? "public",
-        partOfPackage: _getPackageID(global.capNamespace,packageIds,'api'),
-        partOfGroups: [_getGroupID(srvName, defaults.groupTypeId, global)],
-        releaseStatus: ordExtensions.active ?? "active",
-        partOfConsumptionBundles: [
-          {
-            ordId: `${fReplaceSpecialCharacters(global.namespace)}:consumptionBundle:noAuth:v1`,
-          },
+            eventDefinition['@description'] ?? eventDefinition['@Core.Description'] ??
+            "CAP Event resource describing events / messages.",
+        version: "1.0.0",
+        releaseStatus: "active",
+        partOfPackage: _getPackageID(appConfig.ordNamespace, packageIds, 'event'),
+        partOfGroups: [_getGroupID(serviceName, defaults.groupTypeId, appConfig)],
+        visibility: "public",
+        resourceDefinitions: [
+            {
+                type: "asyncapi-v2",
+                mediaType: "application/json",
+                url: `/.well-known/open-resource-discovery/v1/api-metadata/${serviceName}.asyncapi2.json`,
+                accessStrategies: [
+                    {
+                        type: "open",
+                    },
+                ],
+            },
         ],
-        apiProtocol:
-          generatedPath.kind === "odata" ? "odata-v4" : generatedPath.kind,
-        resourceDefinitions: resourceDefinitions,
-        entryPoints: [generatedPath.path],
-        extensible: {
-          supported: ordExtensions["extensible.supported"] ?? "no",
-        },
-        entityTypeMappings: [{ entityTypeTargets: global.aODMEntity }],
-      };
+        extensible: { supported: "no" },
 
-      apiResources.push(obj);
-    });
-  }
-  if (apiResources.length > 0) return apiResources;
-};
-
-/**
- * This is a template function to create Event Resource object for Event Resource Array.
- *
- * @param {string} srv The name of the event.
- * @param {object} srvDefinition The definition of the event.
- * @returns {Object} An object for the Event Resource.
- */
-const fCreateEventResourceTemplate = (srv, srvDefinition, global,packageIds) => {
-  const ordExtensions = fReadORDExtensions(srvDefinition);
-  let srvName = srv;
-  if(!srvName.includes(global.capNamespace)){
-    srvName = global.capNamespace + "." + srv;
-  }
-  return {
-    ordId: `${fReplaceSpecialCharacters(global.namespace)}:eventResource:${srvName}:v1`,
-    title:  ordExtensions.title ?? srvDefinition['@title'] ?? srvDefinition['@Common.Label'] ?? `ODM ${global.appName.replace(/[^a-zA-Z0-9]/g, '')} Events`,
-    shortDescription: ordExtensions.shortDescription ?? "Example ODM Event",
-    description:  ordExtensions.description ?? 
-                  srvDefinition['@description'] ?? srvDefinition['@Core.Description'] ??
-                  `This is an example event catalog that contains only a partial ODM ${global.appName} V1 event`,
-    version:  ordExtensions.version ?? "1.0.0",
-    releaseStatus:  ordExtensions.releaseStatus ?? "beta",
-    partOfPackage: _getPackageID(global.capNamespace,packageIds,'event'),
-    partOfGroups: [_getGroupID(srvName, defaults.groupTypeId, global, false)],
-    visibility: ordExtensions.visibility ?? "public",
-    resourceDefinitions: [
-      {
-        type: "asyncapi-v2",
-        mediaType: "application/json",
-        url: `/.well-known/open-resource-discovery/v1/api-metadata/${srvDefinition._service.name}.asyncapi2.json`,
-        accessStrategies: [
-          {
-            type: "open",
-          },
-        ],
-      },
-    ],
-    extensible: { supported: ordExtensions["extensible.supported"] ?? "no" },
-  };
+        ...ordExtensions
+    };
 };
 
-
-/**
- * This is a function to check whether entity is a function or action.
- * @param {object} srvDefinition The definition of the event.
- * @returns {Object} An object for the Event Resource.
- */
-function checkEntityFunctionAction(srvDefinition, global) {
-  if (srvDefinition.entities) {
-    return srvDefinition.entities.map((entity) => {
-      return {
-        type: "entity",
-        name: entity.name,
-        entityType: entity.name,
-        entitySet: entity.name,
-        entityTypeMapping: `${global.namespace}:entityType:${entity.name}:v1`,
-        entitySetMapping: `${global.namespace}:entitySet:${entity.name}:v1`,
-      };
-    });
-  } else if (srvDefinition.actions) {
-    return srvDefinition.actions.map((action) => {
-      return {
-        type: "action",
-        name: action.name,
-        actionType: action.name,
-        actionMapping: `${global.namespace}:action:${action.name}:v1`,
-      };
-    });
-  } else if (srvDefinition.functions) {
-    return srvDefinition.functions.map((func) => {
-      return {
-        type: "function",
-        name: func.name,
-        functionType: func.name,
-        functionMapping: `${global.namespace}:function:${func.name}:v1`,
-      };
-    });
-  }
-}
-
-/**
- * This is a function to get the corresponding package ordId mapped to the service.
- */
-
-function _getPackageID(capNamespace, packageIds, apiOrEvent) {
-  if (packageIds instanceof Set) {
-    const packageArray = Array.from(packageIds);
-    
-    if (apiOrEvent === "api") {
-      const apiPackage = packageArray.find(pkg => pkg.includes("-api"));
-      if (apiPackage) return apiPackage;
-    } else if (apiOrEvent === "event") {
-      const eventPackage = packageArray.find(pkg => pkg.includes("-event"));
-      if (eventPackage) return eventPackage;
-    }
-    
-    return packageArray.find(pkg => pkg.includes(capNamespace));
-  }
+function _getPackageID(namespace, packageIds, resourceType) {
+    //TODO: without this check, it will be failed in ordPackageJson.test.js, need to check why it is failing
+    if (!(packageIds instanceof Set)) return;
+    const packageIdsArray = Array.from(packageIds);
+    return packageIdsArray.find((pkg) => pkg.includes("-" + resourceType)) || packageIdsArray.find((pkg) => pkg.includes(namespace));
 }
 
 module.exports = {
-  fCreateEntityTypeTemplate,
-  fCreateGroupsTemplateForService,
-  fCreateGroupsTemplateForEvent,
-  fCreateAPIResourceTemplate,
-  fCreateEventResourceTemplate,
+    createEntityTypeTemplate,
+    createGroupsTemplateForService,
+    createAPIResourceTemplate,
+    createEventResourceTemplate,
 };

package/package.json

@@ -1,27 +1,34 @@
 {
-  "name": "@cap-js/ord",
-  "version": "1.0.3",
-  "description": "CAP Plugin for generating ORD document.",
-  "repository": "cap-js/ord",
-  "author": "SAP SE (https://www.sap.com)",
-  "homepage": "https://cap.cloud.sap/",
-  "license": "SEE LICENSE IN LICENSE",
-  "main": "cds-plugin.js",
-  "files": [
-    "lib",
-    "data",
-    "LICENSES"
-  ],
-  "scripts": {
-    "lint": "npx eslint ."
-  },
-  "devDependencies": {
-    "eslint": "^8"
-  },
-  "peerDependencies": {
-    "@sap/cds": "7.9.4",
-    "@sap/cds-compiler" : "5.0.6",
-    "@cap-js/asyncapi": "^1.0.0",
-    "@cap-js/openapi": "^1.0.2"
-  }
-}
+    "name": "@cap-js/ord",
+    "version": "1.1.0",
+    "description": "CAP Plugin for generating ORD document.",
+    "repository": "cap-js/ord",
+    "author": "SAP SE (https://www.sap.com)",
+    "homepage": "https://cap.cloud.sap/",
+    "license": "SEE LICENSE IN LICENSE",
+    "main": "cds-plugin.js",
+    "files": [
+        "lib",
+        "data",
+        "LICENSES"
+    ],
+    "scripts": {
+        "lint": "npx eslint .",
+        "test": "jest --ci --collectCoverage",
+        "update-snapshot": "jest --ci --updateSnapshot",
+        "cds:version": "cds v -i"
+    },
+    "devDependencies": {
+        "eslint": "^8",
+        "jest": "^29.7.0"
+    },
+    "peerDependencies": {
+        "@cap-js/asyncapi": "^1.0.0",
+        "@cap-js/openapi": "^1.0.2",
+        "@sap/cds": "^8.1.1",
+        "@sap/cds-compiler": "5.0.6"
+    },
+    "dependencies": {
+        "lodash": "^4.17.21"
+    }
+}