@open-resource-discovery/specification 1.14.0 → 1.14.2

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

@@ -438,13 +438,25 @@ export interface ApiResource {
      */
     abstract?: boolean;
     /**
-     * The visibility states who is allowed to "see" the described resource or capability.
+     * Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.
+     *
+     * This controls who can see that the resource exists and retrieve its metadata level information.
+     * It does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.
+     *
+     * Use this to prevent exposing internal implementation details to inappropriate consumer audiences.
      */
     visibility: "public" | "internal" | "private";
     /**
-     * The `releaseStatus` specifies the stability of the resource and its external contract.
+     * Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).
+     *
+     * This indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk
+     * of depending on the resource and whether it's suitable for production use.
+     *
+     * Note: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.
+     *
+     * 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.
@@ -720,9 +732,16 @@ export interface ChangelogEntry {
      */
     version: string;
     /**
-     * The `releaseStatus` specifies the stability of the resource and its external contract.
+     * Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).
+     *
+     * This indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk
+     * of depending on the resource and whether it's suitable for production use.
+     *
+     * Note: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.
+     *
+     * 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.
      *
@@ -770,7 +789,7 @@ export interface ApiResourceDefinition {
      * `text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.
      *
      */
-    mediaType: "application/json" | "application/xml" | "text/yaml" | "text/plain" | "application/octet-stream";
+    mediaType: string;
     /**
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
      *
@@ -1018,7 +1037,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;
@@ -1195,13 +1214,25 @@ export interface EventResource {
      */
     abstract?: boolean;
     /**
-     * The visibility states who is allowed to "see" the described resource or capability.
+     * Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.
+     *
+     * This controls who can see that the resource exists and retrieve its metadata level information.
+     * It does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.
+     *
+     * Use this to prevent exposing internal implementation details to inappropriate consumer audiences.
      */
     visibility: "public" | "internal" | "private";
     /**
-     * The `releaseStatus` specifies the stability of the resource and its external contract.
+     * Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).
+     *
+     * This indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk
+     * of depending on the resource and whether it's suitable for production use.
+     *
+     * Note: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.
+     *
+     * 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.
@@ -1424,7 +1455,7 @@ export interface EventResourceDefinition {
      * `text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.
      *
      */
-    mediaType: "application/json" | "application/xml" | "text/yaml" | "text/plain" | "application/octet-stream";
+    mediaType: string;
     /**
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
      *
@@ -1592,13 +1623,25 @@ export interface EntityType {
      */
     lastUpdate?: string;
     /**
-     * The visibility states who is allowed to "see" the described resource or capability.
+     * Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.
+     *
+     * This controls who can see that the resource exists and retrieve its metadata level information.
+     * It does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.
+     *
+     * Use this to prevent exposing internal implementation details to inappropriate consumer audiences.
      */
     visibility: "public" | "internal" | "private";
     /**
-     * The `releaseStatus` specifies the stability of the resource and its external contract.
+     * Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).
+     *
+     * This indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk
+     * of depending on the resource and whether it's suitable for production use.
+     *
+     * Note: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.
+     *
+     * 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.
@@ -1714,8 +1757,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.
@@ -1835,13 +1880,25 @@ export interface Capability {
      */
     lastUpdate?: string;
     /**
-     * The visibility states who is allowed to "see" the described resource or capability.
+     * Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.
+     *
+     * This controls who can see that the resource exists and retrieve its metadata level information.
+     * It does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.
+     *
+     * Use this to prevent exposing internal implementation details to inappropriate consumer audiences.
      */
     visibility: "public" | "internal" | "private";
     /**
-     * The `releaseStatus` specifies the stability of the resource and its external contract.
+     * Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).
+     *
+     * This indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk
+     * of depending on the resource and whether it's suitable for production use.
+     *
+     * Note: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.
+     *
+     * 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.
@@ -1867,6 +1924,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 capability.
+     */
+    relatedApiResources?: RelatedAPIResource[];
+    /**
+     * Optional list of related Event Resources.
+     *
+     * Use this to indicate which events are emitted, consumed, or otherwise related to this capability.
+     */
+    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.
@@ -1907,6 +1982,60 @@ export interface Capability {
      */
     systemInstanceAware?: boolean;
 }
+/**
+ * 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;
+}
+/**
+ * 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.
  */
@@ -1932,7 +2061,7 @@ export interface CapabilityDefinition {
      * `text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.
      *
      */
-    mediaType: "application/json" | "application/xml" | "text/yaml" | "text/plain" | "application/octet-stream";
+    mediaType: string;
     /**
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
      *
@@ -2086,7 +2215,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.
@@ -2428,13 +2557,25 @@ export interface Agent {
      */
     lastUpdate?: string;
     /**
-     * The visibility states who is allowed to "see" the described resource or capability.
+     * Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.
+     *
+     * This controls who can see that the resource exists and retrieve its metadata level information.
+     * It does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.
+     *
+     * Use this to prevent exposing internal implementation details to inappropriate consumer audiences.
      */
     visibility: "public" | "internal" | "private";
     /**
-     * The `releaseStatus` specifies the stability of the resource and its external contract.
+     * Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).
+     *
+     * This indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk
+     * of depending on the resource and whether it's suitable for production use.
+     *
+     * Note: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.
+     *
+     * 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.
@@ -2694,13 +2835,25 @@ export interface IntegrationDependency {
      */
     lastUpdate?: string;
     /**
-     * The visibility states who is allowed to "see" the described resource or capability.
+     * Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.
+     *
+     * This controls who can see that the resource exists and retrieve its metadata level information.
+     * It does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.
+     *
+     * Use this to prevent exposing internal implementation details to inappropriate consumer audiences.
      */
     visibility: "public" | "internal" | "private";
     /**
-     * The `releaseStatus` specifies the stability of the resource and its external contract.
+     * Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).
+     *
+     * This indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk
+     * of depending on the resource and whether it's suitable for production use.
+     *
+     * Note: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.
+     *
+     * 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.
      *
@@ -2789,6 +2942,10 @@ export interface Aspect {
      * List of Event Resource Dependencies.
      */
     eventResources?: EventResourceIntegrationAspect[];
+    /**
+     * List of Capability Dependencies.
+     */
+    capabilities?: CapabilityIntegrationAspect[];
 }
 /**
  * API resource related integration aspect
@@ -2869,6 +3026,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.
  *
@@ -3092,6 +3265,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).
@@ -3188,6 +3365,42 @@ export interface PackageLink {
     url: string;
     [k: string]: unknown | undefined;
 }
+/**
+ * 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 credentials and auth mechanism.
  * Ideally it also includes instructions and details how to request access and credentials for resources.
@@ -3281,7 +3494,12 @@ export interface ConsumptionBundle {
      */
     lastUpdate?: string;
     /**
-     * The visibility states who is allowed to "see" the described resource or capability.
+     * Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.
+     *
+     * This controls who can see that the resource exists and retrieve its metadata level information.
+     * It does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.
+     *
+     * Use this to prevent exposing internal implementation details to inappropriate consumer audiences.
      */
     visibility?: "public" | "internal" | "private";
     /**

package/package.json

@@ -1,54 +1,60 @@
 {
-  "$schema": "http://json.schemastore.org/package",
-  "name": "@open-resource-discovery/specification",
-  "version": "1.14.0",
-  "description": "Open Resource Discovery (ORD) Specification",
-  "author": "SAP SE",
-  "license": "Apache-2.0",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "engines": {
-    "node": ">=22.0.0",
-    "npm": ">=10.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/open-resource-discovery/specification.git"
-  },
-  "files": [
-    "README.md",
-    "dist/index.js",
-    "dist/index.d.ts",
-    "dist/generated/spec/v1"
-  ],
-  "scripts": {
-    "docusaurus": "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",
-    "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"
-  },
-  "devDependencies": {
-    "@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.52.2",
-    "@mdx-js/react": "3.1.1",
-    "@open-resource-discovery/spec-toolkit": "0.7.0",
-    "@types/fs-extra": "11.0.4",
-    "clsx": "2.1.1",
-    "fs-extra": "11.3.3",
-    "lefthook": "2.0.15",
-    "prism-react-renderer": "2.4.1",
-    "react": "18.3.1",
-    "react-dom": "18.3.1",
-    "ts-node": "10.9.2"
-  }
+	"$schema": "http://json.schemastore.org/package",
+	"name": "@open-resource-discovery/specification",
+	"version": "1.14.2",
+	"description": "Open Resource Discovery (ORD) Specification",
+	"author": "SAP SE",
+	"license": "Apache-2.0",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"engines": {
+		"node": ">=22.0.0",
+		"npm": ">=10.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/open-resource-discovery/specification.git"
+	},
+	"files": [
+		"README.md",
+		"dist/index.js",
+		"dist/index.d.ts",
+		"dist/generated/spec/v1"
+	],
+	"scripts": {
+		"docusaurus": "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",
+		"format": "biome format --write .",
+		"lint": "biome lint .",
+		"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"
+	},
+	"devDependencies": {
+		"@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.8.0",
+		"@types/fs-extra": "11.0.4",
+		"ajv": "8.18.0",
+		"ajv-formats": "3.0.1",
+		"clsx": "2.1.1",
+		"fs-extra": "11.3.4",
+		"lefthook": "2.1.4",
+		"prism-react-renderer": "2.4.1",
+		"react": "18.3.1",
+		"react-dom": "18.3.1",
+		"ts-node": "10.9.2"
+	}
 }