@open-resource-discovery/specification 1.9.11 → 1.10.1

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/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";
+    openResourceDiscovery: "1.0" | "1.1" | "1.2" | "1.3" | "1.4" | "1.5" | "1.6" | "1.7" | "1.8" | "1.9" | "1.10";
     /**
      * Optional description of the ORD document itself.
      * Please note that this information is NOT further processed or considered by an ORD aggregator.
@@ -26,6 +26,8 @@ export interface ORDDocument {
      */
     description?: string;
     describedSystemInstance?: SystemInstance;
+    describedSystemType?: SystemType;
+    describedSystemVersion?: SystemVersion;
     /**
      * The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with.
      * Depending on the chosen policy level, additional expectations and validations rules will be applied.
@@ -108,8 +110,9 @@ export interface ORDDocument {
     tombstones?: Tombstone[];
 }
 /**
- * A **system instance** is a concrete, running instance of a system type.
- * In a multi-tenant system, this corresponds to a tenant.
+ * A [system instance](../index.md#def-system-instance) is a concrete, running instance of a system type.
+ * In a multi-tenant system, it corresponds to a tenant.
+ * In a single-tenant system, it corresponds to the [system installation](../index.md#def-system-deployment) itself.
  */
 export interface SystemInstance {
     /**
@@ -138,6 +141,8 @@ export interface SystemInstance {
      * MUST be a valid [Correlation ID](../index.md#correlation-id).
      */
     correlationIds?: string[];
+    labels?: Labels;
+    documentationLabels?: DocumentationLabels;
     /**
      * List of free text style tags.
      * No special characters are allowed except `-`, `_`, `.`, `/` and ` `.
@@ -145,8 +150,6 @@ export interface SystemInstance {
      * Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains.
      */
     tags?: string[];
-    labels?: Labels;
-    documentationLabels?: DocumentationLabels;
 }
 /**
  * Generic labels that can be applied to most ORD information.
@@ -193,6 +196,70 @@ export interface DocumentationLabels {
      */
     [k: string]: string[];
 }
+/**
+ * A [system type](../index.md#def-system-type) is the abstract type of an application or service, from operational perspective.
+ */
+export interface SystemType {
+    /**
+     * The system namespace is a unique identifier for the system type.
+     * It is used to reference the system type in the ORD.
+     */
+    systemNamespace?: string;
+    /**
+     * Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).
+     *
+     * They express an "identity" / "equals" / "mappable" relationship to the target ID.
+     *
+     * If a "part of" relationship needs to be expressed, use the `partOfGroups` assignment instead.
+     *
+     * MUST be a valid [Correlation ID](../index.md#correlation-id).
+     */
+    correlationIds?: string[];
+    labels?: Labels;
+    documentationLabels?: DocumentationLabels;
+    /**
+     * List of free text style tags.
+     * No special characters are allowed except `-`, `_`, `.`, `/` and ` `.
+     *
+     * Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains.
+     */
+    tags?: string[];
+}
+/**
+ * A [system version](../index.md#def-system-version) states the design-time version / release of a [system instance](../index.md#def-system-instance).
+ * It provides versioning for operational purposes for the [system type](../index.md#def-system-type).
+ */
+export interface SystemVersion {
+    /**
+     * The version number of the system instance (run-time) or the version of the described static system type.
+     *
+     * It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.
+     */
+    version?: string;
+    /**
+     * Human-readable title of the system version.
+     */
+    title?: string;
+    /**
+     * Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).
+     *
+     * They express an "identity" / "equals" / "mappable" relationship to the target ID.
+     *
+     * If a "part of" relationship needs to be expressed, use the `partOfGroups` assignment instead.
+     *
+     * MUST be a valid [Correlation ID](../index.md#correlation-id).
+     */
+    correlationIds?: string[];
+    labels?: Labels;
+    documentationLabels?: DocumentationLabels;
+    /**
+     * List of free text style tags.
+     * No special characters are allowed except `-`, `_`, `.`, `/` and ` `.
+     *
+     * Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains.
+     */
+    tags?: string[];
+}
 /**
  * The API Resource provides a high-level description of an exposed API.
  * You can find more information, such as the API resource definitions, in the links in the table below.
@@ -210,15 +277,17 @@ export interface DocumentationLabels {
  */
 export interface APIResource {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -298,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.
      *
@@ -314,7 +383,7 @@ export interface APIResource {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.
@@ -360,6 +429,11 @@ export interface APIResource {
      *
      */
     disabled?: boolean;
+    /**
+     * The resource has been introduced in the given [system version](../index.md#def-system-version).
+     * This implies that the resource is only available if the system instance is of at least that system version.
+     */
+    minSystemVersion?: string;
     /**
      * The deprecation date defines when the resource has been set as deprecated.
      * This is not to be confused with the `sunsetDate` which defines when the resource will be actually decommissioned / removed.
@@ -441,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" | "custom";
+    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";
     /**
      * If the fixed `implementationStandard` values need to be extended, an arbitrary `customImplementationStandard` can be provided.
      *
@@ -458,6 +532,15 @@ export interface APIResource {
      * SHOULD contain documentation and links that describe the used standard.
      */
     customImplementationStandardDescription?: string;
+    /**
+     * Declares this API is a compatible implementation of the referenced API contract(s).
+     * This is also sometimes known as [Service Provider Interface](https://en.wikipedia.org/wiki/Service_provider_interface).
+     *
+     * MUST be a valid reference to an (usually external) [API Resource](#api-resource) ORD ID.
+     *
+     * All APIs that share the same `compatibleWith` value MAY be treated the same or similar by a consumer client.
+     */
+    compatibleWith?: string[];
     /**
      * Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components.
      */
@@ -697,7 +780,7 @@ export interface AccessStrategy {
  * As a consequence, there are different types of selectors that are specialized toward certain resource definition formats.
  *
  * The target of the mapping is a correlation to an entity type via a [Correlation ID](../../#/v1/README?id=correlation-id)
- * or to an [ORD ID] of an entity type.
+ * or to an [ORD ID](../../spec-v1/#ord-id) of an entity type.
  * It is assumed that the entity types are described in more detail or on a different abstraction level via metadata.
  * When the correlation ID is used, an ORD consumer may need to know how to access the entity type metadata through conventions.
  * This can be determined either by the namespace of the correlation ID,
@@ -707,7 +790,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 {
     /**
@@ -784,7 +867,7 @@ export interface APIModelSelectorJSONPointer {
  */
 export interface EntityTypeTargetORDID {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -879,15 +962,17 @@ export interface Extensible {
  */
 export interface EventResource {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -967,7 +1052,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.
      *
@@ -983,7 +1068,7 @@ export interface EventResource {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.
@@ -1029,6 +1114,11 @@ export interface EventResource {
      *
      */
     disabled?: boolean;
+    /**
+     * The resource has been introduced in the given [system version](../index.md#def-system-version).
+     * This implies that the resource is only available if the system instance is of at least that system version.
+     */
+    minSystemVersion?: string;
     /**
      * The deprecation date defines when the resource has been set as deprecated.
      * This is not to be confused with the `sunsetDate` which defines when the resource will be actually decommissioned / removed.
@@ -1097,6 +1187,15 @@ export interface EventResource {
      * SHOULD contain documentation and links that describe the used standard.
      */
     customImplementationStandardDescription?: string;
+    /**
+     * Declares this event resource is a compatible implementation of the referenced contract.
+     * This is also sometimes known as [Service Provider Interface](https://en.wikipedia.org/wiki/Service_provider_interface).
+     *
+     * MUST be a valid reference to an (usually external) [Event Resource](#event-resource) ORD ID.
+     *
+     * All event resources that share the same `compatibleWith` value MAY be treated the same or similar by a consumer client.
+     */
+    compatibleWith?: string[];
     /**
      * Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components.
      */
@@ -1237,15 +1336,17 @@ export interface EventResourceDefinition {
  */
 export interface EntityType {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -1300,7 +1401,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.
      *
@@ -1316,7 +1417,7 @@ export interface EntityType {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.
@@ -1454,7 +1555,7 @@ export interface EntityType {
  */
 export interface RelatedEntityType {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -1469,15 +1570,17 @@ export interface RelatedEntityType {
  */
 export interface Capability {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -1550,7 +1653,7 @@ export interface Capability {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.
@@ -1583,6 +1686,24 @@ export interface Capability {
      * The `releaseStatus` specifies the stability of the resource and its external contract.
      */
     releaseStatus: "active" | "beta" | "deprecated";
+    /**
+     * Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so.
+     * This can happen either because it has not been setup for use or disabled by an admin / user.
+     *
+     * If the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance aware perspective.
+     *
+     * This property can only reflect the knowledge of the described system instance itself.
+     * Outside factors for availability can't need to be considered (e.g. network connectivity, middlewares).
+     *
+     * A disabled resource MAY skip describing its resource definitions.
+     *
+     */
+    disabled?: boolean;
+    /**
+     * The resource has been introduced in the given [system version](../index.md#def-system-version).
+     * This implies that the resource is only available if the system instance is of at least that system version.
+     */
+    minSystemVersion?: string;
     /**
      * Optional list of related EntityType Resources.
      *
@@ -1676,15 +1797,17 @@ export interface CapabilityDefinition {
  */
 export interface DataProduct {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -1738,6 +1861,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.
      *
@@ -1745,7 +1878,7 @@ export interface DataProduct {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.
@@ -1793,6 +1926,11 @@ export interface DataProduct {
      *
      */
     disabled?: boolean;
+    /**
+     * The resource has been introduced in the given [system version](../index.md#def-system-version).
+     * This implies that the resource is only available if the system instance is of at least that system version.
+     */
+    minSystemVersion?: string;
     /**
      * Lifecycle status of the Data Product as a whole.
      *
@@ -1954,7 +2092,7 @@ export interface DataProduct {
  */
 export interface DataProductInputPort {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -1970,7 +2108,7 @@ export interface DataProductInputPort {
  */
 export interface DataProductOutputPort {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -2021,15 +2159,17 @@ export interface DataProductLink {
  */
 export interface IntegrationDependency {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -2090,7 +2230,7 @@ export interface IntegrationDependency {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.
@@ -2217,7 +2357,7 @@ export interface Aspect {
  */
 export interface APIResourceIntegrationAspect {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -2233,7 +2373,7 @@ export interface APIResourceIntegrationAspect {
  */
 export interface EventResourceIntegrationAspect {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -2288,7 +2428,7 @@ export interface EventResourceIntegrationAspectSubset {
  */
 export interface Vendor {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -2331,7 +2471,7 @@ export interface Vendor {
  */
 export interface Product {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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.
      */
@@ -2407,15 +2547,17 @@ export interface Product {
  */
 export interface Package {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -2446,7 +2588,7 @@ export interface Package {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.
@@ -2519,7 +2661,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.
      *
@@ -2605,15 +2747,17 @@ export interface PackageLink {
  */
 export interface ConsumptionBundle {
     /**
-     * The [ORD ID](../index.md#ord-id) is a stable, globally unique ID for ORD resources or taxonomy.
+     * 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;
     /**
-     * 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;
     /**
@@ -2654,7 +2798,7 @@ export interface ConsumptionBundle {
      * It SHOULD be changed if the ORD information or referenced resource definitions changed.
      * It SHOULD express minor and patch changes that don't lead to incompatible changes.
      *
-     * When the `version` major version changes, the [ORD ID](#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
+     * When the `version` major version changes, the [ORD ID](../index.md#ord-id) `<majorVersion>` fragment MUST be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://swagger.io/specification/#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.
      *
      * If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json.schemastore.org/package",
   "name": "@open-resource-discovery/specification",
-  "version": "1.9.11",
+  "version": "1.10.1",
   "description": "Open Resource Discovery (ORD) Specification",
   "author": "SAP SE",
   "license": "Apache-2.0",
@@ -29,7 +29,7 @@
     "@docusaurus/core": "3.7.0",
     "@docusaurus/preset-classic": "3.7.0",
     "@docusaurus/theme-mermaid": "3.7.0",
-    "@easyops-cn/docusaurus-search-local": "0.48.5",
+    "@easyops-cn/docusaurus-search-local": "0.49.2",
     "@mdx-js/react": "3.1.0",
     "clsx": "2.1.1",
     "prism-react-renderer": "2.4.1",

package/static/spec-v1/interfaces/Configuration.annotated.schema.json

@@ -2,6 +2,7 @@
   "description": "The ORD configuration response will indicate that ORD is available for the given host and how to proceed with the discovery.\n\nMost notably, the ORD configuration will tell an ORD consumer which ORD documents are available and where/how they can be accessed.\n\nThe configuration endpoint is a [Well-Known URI](https://tools.ietf.org/html/rfc8615#section-3) discovery mechanism.",
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://open-resource-discovery.github.io/specification/spec-v1/interfaces/Configuration.schema.json#",
+  "title": "ORD Configuration",
   "definitions": {
     "OpenResourceDiscoveryV1": {
       "type": "object",
@@ -124,7 +125,6 @@
       ]
     }
   },
-  "title": "ORD Configuration",
   "type": "object",
   "properties": {
     "$schema": {