@open-resource-discovery/specification 1.14.1 → 1.14.3

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

@@ -170,13 +170,15 @@ export interface SystemInstance {
     tags?: string[];
 }
 /**
- * Generic labels that can be applied to most ORD information.
+ * Generic key-value labels that can be applied to most ORD information.
  * They are defined as an object that may have arbitrary keys.
  * The value of a key is an array of strings.
  *
  * Labels can be used to attach technical information that cannot be expressed natively in ORD.
  * An ORD aggregator should allow to categorize and query information based on the labels provided.
  *
+ * To learn more about the concept, see [Labels](../concepts/grouping-and-bundling#labels).
+ *
  * If multiple parties rely on the existence of certain label information,
  * standardization through ORD SHOULD be preferred.
  *
@@ -456,7 +458,7 @@ export interface ApiResource {
      *
      * See [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * 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.
@@ -477,6 +479,18 @@ export interface ApiResource {
      * It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.
      */
     minSystemVersion?: string;
+    /**
+     * Optional list of related API Resources.
+     *
+     * Use this to indicate which APIs implement, expose, or are otherwise related to this entity.
+     */
+    relatedApiResources?: RelatedAPIResource[];
+    /**
+     * Optional list of related Event Resources.
+     *
+     * Use this to indicate which events are emitted, consumed, or otherwise related to this entity.
+     */
+    relatedEventResources?: RelatedEventResource[];
     /**
      * 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 sunset, aka. decommissioned / removed / archived.
@@ -719,6 +733,42 @@ export interface ConsumptionBundleReference {
      */
     defaultEntryPoint?: string;
 }
+/**
+ * Defines a relation to an API Resource (via its ORD ID).
+ */
+export interface RelatedAPIResource {
+    /**
+     * 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;
+    /**
+     * Optional type of the relationship as a [Concept ID](../index.md#concept-id).
+     *
+     * Defines the semantic meaning of the relationship.
+     * If not provided, the relationship has no specific semantics ("related somehow").
+     */
+    relationType?: string;
+}
+/**
+ * Defines a relation to an Event Resource (via its ORD ID).
+ */
+export interface RelatedEventResource {
+    /**
+     * 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;
+    /**
+     * Optional type of the relationship as a [Concept ID](../index.md#concept-id).
+     *
+     * Defines the semantic meaning of the relationship.
+     * If not provided, the relationship has no specific semantics ("related somehow").
+     */
+    relationType?: string;
+}
 /**
  * A changelog entry can be used to indicate changes.
  * Usually they lead to a change of the version number or the release status.
@@ -741,7 +791,7 @@ export interface ChangelogEntry {
      *
      * See [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * Date of change, without time or timezone information.
      *
@@ -1037,7 +1087,7 @@ export interface Link {
      */
     url: string;
     /**
-     * Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown)
+     * Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).
      */
     description?: string;
     [k: string]: unknown | undefined;
@@ -1232,7 +1282,7 @@ export interface EventResource {
      *
      * See [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * 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.
@@ -1253,6 +1303,18 @@ export interface EventResource {
      * It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.
      */
     minSystemVersion?: string;
+    /**
+     * Optional list of related API Resources.
+     *
+     * Use this to indicate which APIs implement, expose, or are otherwise related to this entity.
+     */
+    relatedApiResources?: RelatedAPIResource[];
+    /**
+     * Optional list of related Event Resources.
+     *
+     * Use this to indicate which events are emitted, consumed, or otherwise related to this entity.
+     */
+    relatedEventResources?: RelatedEventResource[];
     /**
      * 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 sunset, aka. decommissioned / removed / archived.
@@ -1509,8 +1571,8 @@ export interface EventCompatibility {
     maxVersion: string;
 }
 /**
- * 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.
+ * An [**Entity Type**](../concepts/grouping-and-bundling#entity-type) describes either a business concept / term or an underlying conceptual model (e.g. a business object / domain model).
+ * Entity Types can be related to API & Event resources, Data Products and other Entity Types, connecting exposed resources to business semantics.
  *
  * To learn more about the concept, see [Entity Type](../concepts/grouping-and-bundling#entity-type).
  */
@@ -1641,7 +1703,7 @@ export interface EntityType {
      *
      * See [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * 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 sunset, aka. decommissioned / removed / archived.
@@ -1757,8 +1819,10 @@ export interface RelatedEntityType {
      * Optional type of the relationship, which defines a stricter semantic what the relationship implies.
      *
      * If not provided, the relationship type has no semantics, it's "related somehow".
+     *
+     * MUST be a valid [Concept ID](../index.md#concept-id).
      */
-    relationType?: "part-of" | "can-share-identity";
+    relationType?: (string | "part-of" | "can-share-identity") & string;
 }
 /**
  * Capabilities can be used to describe use case specific capabilities, most notably supported features or additional information (like configuration) that needs to be understood from outside.
@@ -1896,7 +1960,7 @@ export interface Capability {
      *
      * See [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * 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.
@@ -1922,6 +1986,24 @@ export interface Capability {
      * MUST be a valid reference to an [EntityType Resource](#entity-type) ORD ID.
      */
     relatedEntityTypes?: string[];
+    /**
+     * Optional list of related API Resources.
+     *
+     * Use this to indicate which APIs implement, expose, or are otherwise related to this entity.
+     */
+    relatedApiResources?: RelatedAPIResource[];
+    /**
+     * Optional list of related Event Resources.
+     *
+     * Use this to indicate which events are emitted, consumed, or otherwise related to this entity.
+     */
+    relatedEventResources?: RelatedEventResource[];
+    /**
+     * Optional list of related Capabilities.
+     *
+     * Use this to indicate dependencies, extensions, or other relationships between capabilities.
+     */
+    relatedCapabilities?: RelatedCapability[];
     /**
      * List of available machine-readable definitions, which describe the resource or capability in detail.
      * See also [Resource Definitions](../index.md#resource-definitions) for more context.
@@ -1962,6 +2044,24 @@ export interface Capability {
      */
     systemInstanceAware?: boolean;
 }
+/**
+ * Defines a relation to another Capability (via its ORD ID).
+ */
+export interface RelatedCapability {
+    /**
+     * 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;
+    /**
+     * Optional type of the relationship as a [Concept ID](../index.md#concept-id).
+     *
+     * Defines the semantic meaning of the relationship.
+     * If not provided, the relationship has no specific semantics ("related somehow").
+     */
+    relationType?: string;
+}
 /**
  * Link and categorization of a machine-readable capability definition.
  */
@@ -2141,7 +2241,7 @@ export interface DataProduct {
      * In the context of data products, it it covers only properties on the data product level.
      * APIs that are part of the input and output ports have their own independent `releaseStatus` and `version`.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * 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.
@@ -2501,7 +2601,7 @@ export interface Agent {
      *
      * See [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * 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.
@@ -2779,7 +2879,7 @@ export interface IntegrationDependency {
      *
      * See [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
-    releaseStatus: "beta" | "active" | "deprecated" | "sunset";
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
      * The sunset date defines when the resource is scheduled to be decommissioned / removed / archived.
      *
@@ -2868,6 +2968,10 @@ export interface Aspect {
      * List of Event Resource Dependencies.
      */
     eventResources?: EventResourceIntegrationAspect[];
+    /**
+     * List of Capability Dependencies.
+     */
+    capabilities?: CapabilityIntegrationAspect[];
 }
 /**
  * API resource related integration aspect
@@ -2948,6 +3052,22 @@ export interface EventResourceIntegrationAspectSubset {
      */
     eventType: string;
 }
+/**
+ * Capability related integration aspect
+ */
+export interface CapabilityIntegrationAspect {
+    /**
+     * 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;
+    /**
+     * Minimum version of the references resource that the integration requires.
+     *
+     */
+    minVersion?: string;
+}
 /**
  * The vendor of a product or a package, usually a corporation or a customer / user.
  *
@@ -2995,15 +3115,17 @@ export interface Vendor {
     documentationLabels?: DocumentationLabels;
 }
 /**
- * A **product** in ORD is understood as a commercial product or service.
+ * A [**Product**](../concepts/grouping-and-bundling#product) in ORD is understood as a software product or service offering (whether commercial or free).
  *
- * It is a high-level entity for structuring the software portfolio from a sales / software logistics perspective.
- * While **system type** is a technical concept, **product** covers the commercial and marketing view.
+ * It is a high-level entity for structuring the software portfolio from a portfolio / software logistics perspective.
+ * While **system type** is a technical concept, **product** covers the portfolio and marketing view.
  *
  * Please note that the ORD concept of a product is very simple on purpose.
  * There is no distinction between products and services and concepts like product versions, variants, etc.
  *
  * ORD assumes that this is handled by specialized systems and that ORD only provides the means to correlate to them.
+ *
+ * To learn more about the concept, see [Product](../concepts/grouping-and-bundling#product).
  */
 export interface Product {
     /**
@@ -3171,6 +3293,10 @@ export interface Package {
      * `packageLinks` MUST be preferred if applicable.
      */
     links?: Link[];
+    /**
+     * Generic list of files with arbitrary meaning and content. Meant to be used for linking PDFs, Word or similar content. This option MUST NOT be used for linking the actual metadata files like OpenAPI, AsyncAPI, CSN, etc.
+     */
+    files?: File[];
     /**
      * Standardized identifier for the license.
      * It MUST conform to the [SPDX License List](https://spdx.org/licenses).
@@ -3268,10 +3394,46 @@ export interface PackageLink {
     [k: string]: unknown | undefined;
 }
 /**
- * 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.
+ * File that can be attached on ORD package level.
+ *
+ */
+export interface File {
+    /**
+     * Human readable title of the file.
+     *
+     * MUST be unique within the collection of files provided.
+     */
+    title: string;
+    /**
+     * [URL](https://tools.ietf.org/html/rfc3986) of the link.
+     *
+     * The file target MAY be relative or absolute.
+     * If a relative URL is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl).
+     * If an absolute URL is given, then it MUST be openly accessible.
+     */
+    url: string;
+    /**
+     * Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).
+     *
+     * The description SHOULD not be excessive in length and is not meant to provide full documentation.
+     * Detailed documentation SHOULD be attached as (typed) links.
+     */
+    description?: string;
+    /**
+     * The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format.
+     * A consuming application can use this information to know which file format parser it needs to use.
+     *
+     * If no Media Type is registered for the referenced file, `text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.
+     *
+     */
+    mediaType: string;
+    [k: string]: unknown | undefined;
+}
+/**
+ * A [**Consumption Bundle**](../concepts/grouping-and-bundling#consumption-bundle) groups APIs and Events together that can be consumed with the same credentials and auth mechanism.
+ * Ideally it also includes instructions and details on how to request access and credentials for resources.
  *
- * For more documentation and guidance how to correctly this correctly, see [Consumption Bundle details](../concepts/grouping-and-bundling#consumption-bundle).
+ * For more documentation and guidance on how to use this correctly, see [Consumption Bundle](../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

package/package.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "http://json.schemastore.org/package",
 	"name": "@open-resource-discovery/specification",
-	"version": "1.14.1",
+	"version": "1.14.3",
 	"description": "Open Resource Discovery (ORD) Specification",
 	"author": "SAP SE",
 	"license": "Apache-2.0",
@@ -23,29 +23,30 @@
 	],
 	"scripts": {
 		"docusaurus": "docusaurus",
-		"build": "npm run generate && npm run build-ts && npm run build-docusaurus",
+		"build": "npm run generate && npm run build:ts && npm run build:docusaurus",
 		"clean": "node src/helper/clean.mjs",
-		"build-ts": "tsc -p ./tsconfig.json",
-		"build-docusaurus": "docusaurus build",
+		"build:ts": "tsc -p ./tsconfig.json",
+		"build:docusaurus": "docusaurus build",
 		"format": "biome format --write .",
 		"lint": "biome lint .",
-		"test": "npm run build-ts && node --test dist/**/*.test.js",
+		"test": "npm run build:ts && node --test dist/**/*.test.js",
 		"serve": "docusaurus serve",
 		"start": "docusaurus start",
 		"deploy": "npm run build && gh-pages -d ./build",
 		"pregenerate": "npm run clean",
 		"generate": "npx @open-resource-discovery/spec-toolkit -c ./spec-toolkit.config.json",
-		"postgenerate": "ts-node ./src/helper/copyGeneratedToDestination.ts"
+		"postgenerate": "ts-node ./src/helper/copyGeneratedToDestination.ts",
+		"generate:llm-notebook": "npm run generate && ts-node ./src/helper/exportForNotebookLM.ts"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.4.6",
+		"@biomejs/biome": "2.4.9",
 		"@docusaurus/core": "3.9.2",
 		"@docusaurus/plugin-client-redirects": "3.9.2",
 		"@docusaurus/preset-classic": "3.9.2",
 		"@docusaurus/theme-mermaid": "3.9.2",
 		"@easyops-cn/docusaurus-search-local": "0.55.1",
 		"@mdx-js/react": "3.1.1",
-		"@open-resource-discovery/spec-toolkit": "0.7.1",
+		"@open-resource-discovery/spec-toolkit": "0.8.0",
 		"@types/fs-extra": "11.0.4",
 		"ajv": "8.18.0",
 		"ajv-formats": "3.0.1",