@open-resource-discovery/specification 1.10.0 → 1.11.0

package/README.md

@@ -1,4 +1,5 @@
 [![REUSE status](https://api.reuse.software/badge/github.com/open-resource-discovery/specification)](https://api.reuse.software/info/github.com/open-resource-discovery/specification)
+<a href="https://www.npmjs.com/package/@open-resource-discovery/specification"><img src="https://img.shields.io/npm/v/@open-resource-discovery/specification" alt="NPM package"></a>
 
 # Open Resource Discovery Specification
 
@@ -47,7 +48,7 @@ For detailed and recent changes, please refer to the [CHANGELOG.md](CHANGELOG.md
 ## Acknowledgements
 
 - The original idea for ORD came from Harsh Jegadeesan and Divya Mary.
-- The currently active core-contributors to the spec are: [Simon Heimler](https://github.com/Fannon), [Sebastian Wennemers](https://github.com/swennemers), [Steffen Göbel](https://github.com/steffengoebel), [Ralf Hofmann](https://github.com/ormos), [Kiril Kabakchiev](https://github.com/KirilKabakchiev), [Nikolay Mateev](https://github.com/NickyMateev), [Bibin Thomas](https://github.com/Bibin-T) and others.
+- The currently active core-contributors to the spec are: [Simon Heimler](https://github.com/Fannon), [Sebastian Wennemers](https://github.com/swennemers), [Pavel Kornev](https://github.com/pavelkornev), [Steffen Göbel](https://github.com/steffengoebel), [Ralf Hofmann](https://github.com/ormos), [Kiril Kabakchiev](https://github.com/KirilKabakchiev), [Nikolay Mateev](https://github.com/NickyMateev), [Bibin Thomas](https://github.com/Bibin-T) and others.
 
 ## License
 

package/dist/types/v1/Configuration.d.ts

@@ -7,7 +7,7 @@
  */
 export interface ORDConfiguration {
     /**
-     * Optional URL to the ORD document schema (defined as JSON Schema).
+     * Optional URL to the ORD Configuration schema (defined as JSON Schema).
      * If given, this enables code intelligence and validation in supported editors (like VSCode) and tools.
      */
     $schema?: (string | "https://open-resource-discovery.github.io/specification/spec-v1/interfaces/Configuration.schema.json#") & string;
@@ -35,6 +35,7 @@ export interface ORDV1Support {
      * For more details how to implement this correctly, please refer to the [ORD configuration endpoint](../index.md#ord-configuration-endpoint) section and the [considerations on the granularity of ORD documents](../index.md#considerations-on-the-granularity-of-ord-documents).
      */
     documents?: ORDV1DocumentDescription[];
+    capabilities?: ORDV1Capabilities;
 }
 /**
  * Describes an [ORD Document](../index.md#ord-document) that is available for pull transport consumption.
@@ -102,3 +103,13 @@ export interface AccessStrategy {
      */
     customDescription?: string;
 }
+/**
+ * List of capabilities that are supported by the ORD provider.
+ */
+export interface ORDV1Capabilities {
+    /**
+     * Whether the ORD provider supports the optional [select parameter](../index.md#select-parameter) for retrieving the ORD config and ORD documents.
+     */
+    selector?: boolean;
+    [k: string]: any | undefined;
+}

package/dist/types/v1/Document.d.ts

@@ -17,7 +17,7 @@ export interface ORDDocument {
     /**
      * Version of the Open Resource Discovery specification that is used to describe this document.
      */
-    openResourceDiscovery: "1.0" | "1.1" | "1.2" | "1.3" | "1.4" | "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | "1.10";
+    openResourceDiscovery: "1.0" | "1.1" | "1.2" | "1.3" | "1.4" | "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | "1.10" | "1.11";
     /**
      * Optional description of the ORD document itself.
      * Please note that this information is NOT further processed or considered by an ORD aggregator.
@@ -35,7 +35,7 @@ export interface ORDDocument {
      * The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.
      *
      */
-    policyLevel?: "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom";
+    policyLevel?: (string | "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom") & string;
     /**
      * If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.
      * The policy level is inherited from packages to resources they contain, but can be overwritten at resource level.
@@ -283,9 +283,11 @@ export interface APIResource {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId?: string;
     /**
@@ -365,7 +367,7 @@ export interface APIResource {
      */
     defaultConsumptionBundle?: string;
     /**
-     * List of products this resource is a part of.
+     * List of products the resources of the package are a part of.
      *
      * MUST be a valid reference to a [Product](#product) ORD ID.
      *
@@ -496,7 +498,7 @@ export interface APIResource {
     /**
      * API Protocol including the protocol version if applicable
      */
-    apiProtocol: "odata-v2" | "odata-v4" | "rest" | "graphql" | "delta-sharing" | "soap-inbound" | "soap-outbound" | "websocket" | "sap-rfc" | "sap-sql-api-v1" | "sap-ina-api-v1";
+    apiProtocol: (string | "odata-v2" | "odata-v4" | "rest" | "graphql" | "delta-sharing" | "soap-inbound" | "soap-outbound" | "websocket" | "sap-rfc" | "sap-sql-api-v1" | "sap-ina-api-v1") & string;
     /**
      * List of available machine-readable definitions, which describe the resource or capability in detail.
      *
@@ -513,7 +515,7 @@ export interface APIResource {
      *
      * All APIs that share the same implementation standard MAY be treated the same or similar by a consumer client.
      */
-    implementationStandard?: "sap:ord-document-api:v1" | "cff:open-service-broker:v2" | "sap:csn-exposure:v1" | "sap:ape-api:v1" | "sap:cdi-api:v1" | "sap:delta-sharing:v1" | "sap:hana-cloud-sql:v1" | "sap.dp:data-subscription-api:v1" | "custom";
+    implementationStandard?: (string | "sap:ord-document-api:v1" | "cff:open-service-broker:v2" | "sap:csn-exposure:v1" | "sap:ape-api:v1" | "sap:cdi-api:v1" | "sap:delta-sharing:v1" | "sap:hana-cloud-sql:v1" | "sap.dp:data-subscription-api:v1" | "custom") & string;
     /**
      * If the fixed `implementationStandard` values need to be extended, an arbitrary `customImplementationStandard` can be provided.
      *
@@ -553,12 +555,20 @@ export interface APIResource {
      *
      * If no array is defined, it is assumed that this information is not provided.
      */
-    supportedUseCases?: ("data-federation" | "snapshot" | "incremental" | "streaming")[];
+    supportedUseCases?: ((string | "data-federation" | "snapshot" | "incremental" | "streaming") & string)[];
     usage?: Usage;
     /**
      * Describes mappings between the API Models of the described resource to the underlying, conceptual entity types.
      */
     entityTypeMappings?: EntityTypeMapping[];
+    /**
+     * Optional list of [entity types](#entity-type) that are exposed by the resource.
+     *
+     * This replaces `entityTypeMappings`. If both is given, the `exposedEntityTypes` wins.
+     *
+     * MUST be a valid reference to an [EntityType](#entity-type) ORD ID.
+     */
+    exposedEntityTypes?: ExposedEntityType[];
     /**
      * Links with semantic meaning that are specific to API Resources.
      */
@@ -608,7 +618,7 @@ export interface APIResource {
      * The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.
      *
      */
-    policyLevel?: "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom";
+    policyLevel?: (string | "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom") & string;
     /**
      * If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.
      * The policy level is inherited from packages to resources they contain, but can be overwritten at resource level.
@@ -701,7 +711,7 @@ export interface APIResourceDefinition {
      * Type of the API Resource Definition
      * If "custom" is chosen, a customType MUST be provided
      */
-    type: "openapi-v2" | "openapi-v3" | "raml-v1" | "edmx" | "csdl-json" | "graphql-sdl" | "wsdl-v1" | "wsdl-v2" | "sap-rfc-metadata-v1" | "sap-sql-api-definition-v1" | "sap-csn-interop-effective-v1" | "custom";
+    type: (string | "openapi-v2" | "openapi-v3" | "raml-v1" | "edmx" | "csdl-json" | "graphql-sdl" | "wsdl-v1" | "wsdl-v2" | "sap-rfc-metadata-v1" | "sap-sql-api-definition-v1" | "sap-csn-interop-effective-v1" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -747,7 +757,7 @@ export interface AccessStrategy {
     /**
      * Defines the authentication/authorization strategy through which the referenced `resourceDefinitions` are accessible.
      */
-    type: "open" | "sap:oauth-client-credentials:v1" | "sap:cmp-mtls:v1" | "sap.businesshub:basic-auth:v1" | "custom";
+    type: (string | "open" | "sap:oauth-client-credentials:v1" | "sap:cmp-mtls:v1" | "sap.businesshub:basic-auth:v1" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -788,7 +798,7 @@ export interface AccessStrategy {
  * To indicate this, the service needs to be implemented and described in ORD with `implementationStandard` set to `sap:csn-exposure:v1`).
  *
  * ODM 2.0 relies on the entity type mappings and uses the the mapping to express the relationship of an API to the
- * corresponding ODM entity. ORD consumers like SAP Business Accelerator Hub consume the mapping to make the relationships navigatable for customers.
+ * corresponding ODM entity. ORD consumers like SAP Business Accelerator Hub consume the mapping to make the relationships navigate-able for customers.
  */
 export interface EntityTypeMapping {
     /**
@@ -879,6 +889,17 @@ export interface EntityTypeTargetORDID {
 export interface EntityTypeTargetCorrelationID {
     correlationId: string;
 }
+/**
+ * Defines which Entity Type is exposed through  (via its ORD ID).
+ */
+export interface ExposedEntityType {
+    /**
+     * The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.
+     *
+     * It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type.
+     */
+    ordId: string;
+}
 /**
  * Links with specific semantic meaning that are related to API or event resources.
  *
@@ -888,7 +909,7 @@ export interface APIAndEventResourceLink {
     /**
      * See also: [WADG0001 WebAPI type extension](https://webapi-discovery.github.io/rfcs/rfc0001.html#webapiactions)
      */
-    type: "api-documentation" | "authentication" | "client-registration" | "console" | "payment" | "service-level-agreement" | "support" | "custom";
+    type: (string | "api-documentation" | "authentication" | "client-registration" | "console" | "payment" | "service-level-agreement" | "support" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -966,9 +987,11 @@ export interface EventResource {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId?: string;
     /**
@@ -1048,7 +1071,7 @@ export interface EventResource {
      */
     defaultConsumptionBundle?: string;
     /**
-     * List of products this resource is a part of.
+     * List of products the resources of the package are a part of.
      *
      * MUST be a valid reference to a [Product](#product) ORD ID.
      *
@@ -1166,7 +1189,7 @@ export interface EventResource {
      *
      * As of now, only custom implementation standards are supported.
      */
-    implementationStandard?: "custom";
+    implementationStandard?: (string | "custom") & string;
     /**
      * If the fixed `implementationStandard` values need to be extended, an arbitrary `customImplementationStandard` can be provided.
      *
@@ -1200,6 +1223,14 @@ export interface EventResource {
      * Describes mappings between the API Models of the described resource to the underlying, conceptual entity types.
      */
     entityTypeMappings?: EntityTypeMapping[];
+    /**
+     * Optional list of [entity types](#entity-type) that are exposed by the resource.
+     *
+     * This replaces `entityTypeMappings`. If both is given, the `exposedEntityTypes` wins.
+     *
+     * MUST be a valid reference to an [EntityType](#entity-type) ORD ID.
+     */
+    exposedEntityTypes?: ExposedEntityType[];
     /**
      * Links with semantic meaning that are specific to event resources.
      *
@@ -1249,7 +1280,7 @@ export interface EventResource {
      * The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.
      *
      */
-    policyLevel?: "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom";
+    policyLevel?: (string | "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom") & string;
     /**
      * If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.
      * The policy level is inherited from packages to resources they contain, but can be overwritten at resource level.
@@ -1285,7 +1316,7 @@ export interface EventResourceDefinition {
     /**
      * Type of the event resource definition
      */
-    type: "asyncapi-v2" | "sap-csn-interop-effective-v1" | "custom";
+    type: (string | "asyncapi-v2" | "sap-csn-interop-effective-v1" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -1325,10 +1356,10 @@ export interface EventResourceDefinition {
     accessStrategies?: [AccessStrategy, ...AccessStrategy[]];
 }
 /**
- * An [**Entity Type**](../../details/articles/grouping-and-bundling#entity-type) describes either a business concept / term or an underlying conceptual model.
+ * An [**Entity Type**](../concepts/grouping-and-bundling#entity-type) describes either a business concept / term or an underlying conceptual model.
  * The same entity type can be exposed through one or multiple API and events resources.
  *
- * To learn more about the concept, see [Entity Type](../../details/articles/grouping-and-bundling#entity-type).
+ * To learn more about the concept, see [Entity Type](../concepts/grouping-and-bundling#entity-type).
  */
 export interface EntityType {
     /**
@@ -1338,9 +1369,11 @@ export interface EntityType {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId: string;
     /**
@@ -1395,7 +1428,7 @@ export interface EntityType {
      */
     partOfGroups?: string[];
     /**
-     * List of products this resource is a part of.
+     * List of products the resources of the package are a part of.
      *
      * MUST be a valid reference to a [Product](#product) ORD ID.
      *
@@ -1480,7 +1513,7 @@ export interface EntityType {
      *
      * In Domain-Driven Design, there is a concept of entities and aggregates.
      * There are root entities which may contain further sub entities by composition.
-     * The complete “package” is then called an aggregate, which gets its name and identity from the root entity.
+     * The complete "package" is then called an aggregate, which gets its name and identity from the root entity.
      * An aggregate is a cluster of domain objects that can be treated as a single unit.
      * The root is the entity that is referenced from outside the aggregate. There must be only one root per aggregate.
      * The root ensures the integrity of the aggregate. A sub entity is any other non-root entity in the aggregate.
@@ -1515,7 +1548,7 @@ export interface EntityType {
      * The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.
      *
      */
-    policyLevel?: "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom";
+    policyLevel?: (string | "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom") & string;
     /**
      * If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.
      * The policy level is inherited from packages to resources they contain, but can be overwritten at resource level.
@@ -1570,9 +1603,11 @@ export interface Capability {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId?: string;
     /**
@@ -1588,7 +1623,7 @@ export interface Capability {
     /**
      * Type of the Capability
      */
-    type: "custom" | "sap.mdo:mdi-capability:v1";
+    type: (string | "sap.mdo:mdi-capability:v1" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -1698,7 +1733,6 @@ export interface Capability {
     minSystemVersion?: string;
     /**
      * Optional list of related EntityType Resources.
-     *
      * MUST be a valid reference to an [EntityType Resource](#entity-type) ORD ID.
      */
     relatedEntityTypes?: string[];
@@ -1743,7 +1777,7 @@ export interface CapabilityDefinition {
     /**
      * Type of the capability resource definition
      */
-    type: "custom" | "sap.mdo:mdi-capability-definition:v1";
+    type: (string | "sap.mdo:mdi-capability-definition:v1" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -1783,9 +1817,9 @@ export interface CapabilityDefinition {
     accessStrategies?: [AccessStrategy, ...AccessStrategy[]];
 }
 /**
- * A [Data Product](../../details/articles/data-product) is a data set exposed for consumption outside the boundaries of the producing application via APIs and described by high quality metadata that can be accessed through the [ORD Aggregator](../../spec-v1/#ord-aggregator).
+ * A [Data Product](../concepts/data-product) is a data set exposed for consumption outside the boundaries of the producing application via APIs and described by high quality metadata that can be accessed through the [ORD Aggregator](../../spec-v1/#ord-aggregator).
  *
- * Please note that this concept is in beta, see [Data Product - Beta Status](../../details/articles/data-product#beta-status).
+ * Please note that this concept is in beta, see [Data Product - Beta Status](../concepts/data-product#beta-status).
  */
 export interface DataProduct {
     /**
@@ -1795,9 +1829,11 @@ export interface DataProduct {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId?: string;
     /**
@@ -1851,6 +1887,16 @@ export interface DataProduct {
      * All resources that share the same group ID assignment are effectively grouped together.
      */
     partOfGroups?: string[];
+    /**
+     * List of products this Data Product is a part of or is related to, its e.g. data source systems.
+     *
+     * MUST be a valid reference to a [Product](#product) ORD ID.
+     *
+     * `partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains.
+     *
+     * @minItems 0
+     */
+    partOfProducts?: string[];
     /**
      * The complete [SemVer](https://semver.org/) version string.
      *
@@ -1954,11 +2000,11 @@ export interface DataProduct {
      */
     type: "primary" | "derived";
     /**
-     * Category of the data-set within data product. Based on its definition, a data product is a “data set” - which can include on the values below.
+     * Category of the data-set within data product. Based on its definition, a data product is a "data set" - which can include on the values below.
      * Based on the type some properties of a data product may become optional/mandatory.
      * Consumers might still do analytics on business object like data products.
      */
-    category: "business-object" | "analytical" | "other";
+    category: (string | "business-object" | "analytical" | "other") & string;
     /**
      * Aggregated list of entity types that are at least partially exposed by the data product. Detailed mapping can be found on the output port schema level.
      */
@@ -2037,7 +2083,7 @@ export interface DataProduct {
      * The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.
      *
      */
-    policyLevel?: "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom";
+    policyLevel?: (string | "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom") & string;
     /**
      * If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.
      * The policy level is inherited from packages to resources they contain, but can be overwritten at resource level.
@@ -2099,7 +2145,7 @@ export interface DataProductOutputPort {
  * If a generic [Link](#link) can also be expressed via Data Product Link, the latter MUST be chosen.
  */
 export interface DataProductLink {
-    type: "payment" | "terms-of-use" | "service-level-agreement" | "support" | "custom";
+    type: (string | "payment" | "terms-of-use" | "service-level-agreement" | "support" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -2117,7 +2163,7 @@ export interface DataProductLink {
     url: string;
 }
 /**
- * An [Integration Dependency](../../details/articles/integration-dependency) states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose.
+ * An [Integration Dependency](../concepts/integration-dependency) states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose.
  * The purpose could be to enable a certain feature or integration scenario, but it could also be a mandatory prerequisite for the described system to work.
  *
  * The integration dependency includes a list of individual **aspects** that the integration consists of.
@@ -2135,7 +2181,7 @@ export interface DataProductLink {
  * An integration dependency is also not meant to describe a bigger process.
  * Instead it focuses on the technical necessaries to create an integration for one particular purpose.
  *
- * To learn more about the concept, see [Integration Dependency](../../details/articles/integration-dependency).
+ * To learn more about the concept, see [Integration Dependency](../concepts/integration-dependency).
  */
 export interface IntegrationDependency {
     /**
@@ -2145,9 +2191,11 @@ export interface IntegrationDependency {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId?: string;
     /**
@@ -2508,7 +2556,7 @@ export interface Product {
     documentationLabels?: DocumentationLabels;
 }
 /**
- * A [**Package**](../../details/articles/grouping-and-bundling#package) organizes a set of related resources together, by publishing and catalog presentation concerns.
+ * A [**Package**](../concepts/grouping-and-bundling#package) organizes a set of related resources together, by publishing and catalog presentation concerns.
  *
  * The Package can also be used to indicate which products or vendors provided the packaged resources.
  * For partner or customer content, the package can indicate this via the `vendor` and `partOfProducts` assignments.
@@ -2521,7 +2569,7 @@ export interface Product {
  * A package does not have a `visibility` property.
  * Whether it is displayed is decided by the fact, whether it contains any visible resources according to the visibility role of the aggregator.
  *
- * To learn more about the concept and further guidance, see [Package](../../details/articles/grouping-and-bundling#package).
+ * To learn more about the concept and further guidance, see [Package](../concepts/grouping-and-bundling#package).
  */
 export interface Package {
     /**
@@ -2531,9 +2579,11 @@ export interface Package {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId?: string;
     /**
@@ -2583,7 +2633,7 @@ export interface Package {
      * The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.
      *
      */
-    policyLevel?: "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom";
+    policyLevel?: (string | "none" | "sap:base:v1" | "sap:core:v1" | "sap:dp:v1" | "custom") & string;
     /**
      * If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.
      * The policy level is inherited from packages to resources they contain, but can be overwritten at resource level.
@@ -2637,7 +2687,7 @@ export interface Package {
      */
     vendor: string;
     /**
-     * List of products this resource is a part of.
+     * List of products the resources of the package are a part of.
      *
      * MUST be a valid reference to a [Product](#product) ORD ID.
      *
@@ -2671,7 +2721,7 @@ export interface Package {
     /**
      * If provided, all resources that are part of this package can only run on the listed runtime.
      *
-     * MUST be a valid [System Namespace](../index.md#system-namespace).
+     * MUST be a valid [system namespace](../index.md#system-namespace).
      */
     runtimeRestriction?: string;
     /**
@@ -2690,7 +2740,7 @@ export interface Package {
  * If a generic [Link](#link) can also be expressed via a Package Link, the latter MUST be chosen.
  */
 export interface PackageLink {
-    type: "terms-of-service" | "license" | "client-registration" | "payment" | "sandbox" | "service-level-agreement" | "support" | "custom";
+    type: (string | "terms-of-service" | "license" | "client-registration" | "payment" | "sandbox" | "service-level-agreement" | "support" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -2708,10 +2758,10 @@ export interface PackageLink {
     [k: string]: any | undefined;
 }
 /**
- * A [**Consumption Bundle**](../../details/articles/grouping-and-bundling#consumption-bundle) groups APIs and Events together that can be consumed with the credentials and auth mechanism.
+ * A [**Consumption Bundle**](../concepts/grouping-and-bundling#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.
  *
- * For more documentation and guidance how to correctly this correctly, see [Consumption Bundle details](../../details/articles/grouping-and-bundling#consumption-bundle).
+ * For more documentation and guidance how to correctly this correctly, see [Consumption Bundle details](../concepts/grouping-and-bundling#consumption-bundle).
  *
  * A consumption bundle SHOULD have at least one association with a resource (0..n). Avoid empty consumption bundles.
  * A consumption bundle MUST NOT contain APIs and Events that are NOT defined in the ORD document(s) returned
@@ -2719,7 +2769,7 @@ export interface PackageLink {
  *
  * Please note that some ORD consumer use cases MAY depend on consumption bundle assignments to work with the resources.
  *
- * To learn more about the concept, see [Consumption Bundle](../../details/articles/grouping-and-bundling#consumption-bundle).
+ * To learn more about the concept, see [Consumption Bundle](../concepts/grouping-and-bundling#consumption-bundle).
  */
 export interface ConsumptionBundle {
     /**
@@ -2729,9 +2779,11 @@ export interface ConsumptionBundle {
      */
     ordId: string;
     /**
-     * Local ID, as known by the described system.
+     * The locally unique ID under which this resource can be looked up / resolved in the described system itself.
+     * Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.
      *
-     * This can be the `<resourceName>` fragment in the ORD ID. In this case, make sure it fits the length limits of the ORD ID. It might also be different if e.g. localIds have incompatible charset restrictions.
+     * It MAY also be used as the `<resourceName>` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.
+     * But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `<resourceName>` fragment in the ORD ID.
      */
     localId?: string;
     /**
@@ -2835,7 +2887,7 @@ export interface CredentialExchangeStrategy {
     /**
      * The type of credential exchange strategy.
      */
-    type: "custom";
+    type: (string | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -2871,7 +2923,7 @@ export interface CredentialExchangeStrategy {
  * They express a "part of" relationship to the chosen group concept.
  * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
  *
- * To learn more about the concept, see [Group Concept Documentation](../../details/articles/grouping-and-bundling#Groups).
+ * To learn more about the concept, see [Group Concept Documentation](../concepts/grouping-and-bundling#Groups).
  */
 export interface Group {
     /**
@@ -2908,7 +2960,7 @@ export interface Group {
  *
  * Group Types can be defined centrally (ownership by authority namespace) or decentrally (defined by application / service itself).
  *
- * To learn more about the concept, see [Group Concept Documentation](../../details/articles/grouping-and-bundling#Groups).
+ * To learn more about the concept, see [Group Concept Documentation](../concepts/grouping-and-bundling#Groups).
  */
 export interface GroupType {
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json.schemastore.org/package",
   "name": "@open-resource-discovery/specification",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Open Resource Discovery (ORD) Specification",
   "author": "SAP SE",
   "license": "Apache-2.0",
@@ -26,10 +26,10 @@
     "deploy": "npm run build && gh-pages -d ./build"
   },
   "devDependencies": {
-    "@docusaurus/core": "3.7.0",
-    "@docusaurus/preset-classic": "3.7.0",
-    "@docusaurus/theme-mermaid": "3.7.0",
-    "@easyops-cn/docusaurus-search-local": "0.49.1",
+    "@docusaurus/core": "3.8.0",
+    "@docusaurus/preset-classic": "3.8.0",
+    "@docusaurus/theme-mermaid": "3.8.0",
+    "@easyops-cn/docusaurus-search-local": "0.49.2",
     "@mdx-js/react": "3.1.0",
     "clsx": "2.1.1",
     "prism-react-renderer": "2.4.1",