@open-resource-discovery/specification 1.14.5 → 1.16.0

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

@@ -2,6 +2,10 @@
  * Define from where the API resource can be used and accessed
  */
 export type Usage = "external" | "local";
+/**
+ * Defines whether and how the resource can be extended with custom fields.
+ */
+export type ExtensibilitySupportLevel = "no" | "manual" | "automatic";
 /**
  * The [ORD Document](../index.md#ord-document) object serves as a wrapper for the **ORD resources** and **ORD taxonomy** and adds further top-level information
  * that is specific to the document/the service it describes.
@@ -19,7 +23,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" | "1.11" | "1.12" | "1.13" | "1.14";
+    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" | "1.12" | "1.13" | "1.14" | "1.15" | "1.16";
     /**
      * Optional description of the ORD document itself.
      * Please note that this information is NOT further processed or considered by an ORD aggregator.
@@ -27,6 +31,24 @@ export interface OrdDocument {
      * Notated in [CommonMark](https://spec.commonmark.org/) (Markdown).
      */
     description?: string;
+    /**
+     * Optional [base URL](../index.md#base-url) of the ORD provider system instance that serves this document.
+     *
+     * Used to resolve relative URLs to [resource definition](../index.md#resource-definition) files and resource definition metadata file
+     * references within this document (e.g., `resourceDefinitions[].url`, `overlayDefinitions[].url`, `File.url`).
+     * This differs from `describedSystemInstance.baseUrl`, which is used for entry point URLs.
+     *
+     * It may differ from `describedSystemInstance.baseUrl` when an ORD provider describes another system on its behalf.
+     * In the common case where the ORD provider and the described system are the same, both values are identical.
+     *
+     * The `baseUrl` MUST NOT contain a trailing slash.
+     *
+     * This property is particularly important in push, offline, and self-contained document scenarios,
+     * and REQUIRED when the provider and the described system differ.
+     *
+     * See [Relative URL Resolution](../index.md#relative-url-resolution) for the full resolution order including fallbacks and backward-compatibility rules.
+     */
+    baseUrl?: string;
     /**
      * With ORD it's possible to describe a system from a static or a dynamic [perspective](../index.md#perspectives) (for more details, follow the link).
      *
@@ -39,9 +61,9 @@ export interface OrdDocument {
      * Please read the [article on perspectives](../concepts/perspectives) for more explanations.
      */
     perspective?: ("system-type" | "system-version" | "system-instance" | "system-independent") & string;
-    describedSystemInstance?: SystemInstance;
     describedSystemType?: SystemType;
     describedSystemVersion?: SystemVersion;
+    describedSystemInstance?: SystemInstance;
     /**
      * 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.
@@ -91,6 +113,16 @@ export interface OrdDocument {
      * Array of all AI Agents that are described in this ORD document.
      */
     agents?: Agent[];
+    /**
+     * Array of all metadata overlays described in this ORD document.
+     *
+     * An ORD Overlay resource is a standalone, versioned resource that references an overlay document which patches
+     * resource definitions (e.g. OpenAPI, AsyncAPI, OData CSDL) without modifying the originals.
+     *
+     * For overlays that are tightly coupled to a single API or Event resource, consider attaching them directly
+     * as a `resourceDefinitions` entry with `type: ord:overlay:v1` instead.
+     */
+    overlays?: Overlay[];
     /**
      * Array of all integration dependencies that are described in this ORD document.
      */
@@ -128,27 +160,14 @@ export interface OrdDocument {
     tombstones?: Tombstone[];
 }
 /**
- * Information on the [system-instance](../index.md#system-instance) that this ORD document describes.
- *
- * Whether this information is required or recommended to add, depends on the requirements of the ORD aggregator.
+ * Information on the [system type](../index.md#system-type) that this ORD document describes.
  */
-export interface SystemInstance {
-    /**
-     * Optional [base URL](../index.md#base-url) of the **system instance**.
-     * By providing the base URL, relative URLs in the document are resolved relative to it.
-     *
-     * The `baseUrl` MUST not contain a leading slash.
-     *
-     * MUST be provided if the base URL is not known to the ORD aggregators.
-     * MUST be provided when the document needs to be fully self contained, e.g. when used for manual imports.
-     */
-    baseUrl?: string;
+export interface SystemType {
     /**
-     * Optional local ID for the system instance, as known by the described system.
-     *
-     * In case of multi-tenant systems, it is equivalent to the local tenant id.
+     * The [system namespace](../index.md#system-namespace) is a unique identifier for the system type.
+     * It is used to reference the system type in the ORD.
      */
-    localId?: string;
+    systemNamespace?: string;
     /**
      * Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).
      *
@@ -220,14 +239,23 @@ export interface DocumentationLabels {
     [k: string]: string[];
 }
 /**
- * Information on the [system type](../index.md#system-type) that this ORD document describes.
+ * Information on the [system version](../index.md#system-version) that this ORD document describes.
  */
-export interface SystemType {
+export interface SystemVersion {
     /**
-     * The [system namespace](../index.md#system-namespace) is a unique identifier for the system type.
-     * It is used to reference the system type in the ORD.
+     * The version of the system instance (run-time) or the version of the described system-version perspective.
+     *
+     * It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.
+     *
+     * MUST be provided if the ORD document is `perspective`: `system-version`.
+     *
+     * For continuous-delivery systems, the version MAY be fixed to the same value, e.g. `1.0.0`, but be aware that phased rollouts may benefit from a more precise versioning like adding a build number.
      */
-    systemNamespace?: string;
+    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).
      *
@@ -249,23 +277,33 @@ export interface SystemType {
     tags?: string[];
 }
 /**
- * Information on the [system version](../index.md#system-version) that this ORD document describes.
+ * Information on the [system-instance](../index.md#system-instance) that this ORD document describes.
+ *
+ * Whether this information is required or recommended to add, depends on the requirements of the ORD aggregator.
  */
-export interface SystemVersion {
+export interface SystemInstance {
     /**
-     * The version of the system instance (run-time) or the version of the described system-version perspective.
+     * Optional [base URL](../index.md#base-url) of the **described system instance**.
      *
-     * It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.
+     * Used to resolve relative [entry point](../index.md#described-system-base-url-entry-points) URLs within this document.
+     * Relative URLs to metadata files (e.g., `resourceDefinitions[].url`) are resolved against
+     * the document root `baseUrl` instead — see [Relative URL Resolution](../index.md#relative-url-resolution).
      *
-     * MUST be provided if the ORD document is `perspective`: `system-version`.
+     * ORD aggregators that hold authoritative knowledge of the described system's base URL
+     * (e.g., from landscape configuration or service discovery) MAY prefer that over this value.
      *
-     * For continuous-delivery systems, the version MAY be fixed to the same value, e.g. `1.0.0`, but be aware that phased rollouts may benefit from a more precise versioning like adding a build number.
+     * The `baseUrl` MUST NOT contain a trailing slash.
+     *
+     * MUST be provided if the base URL is not known to the ORD aggregators.
+     * MUST be provided when the document needs to be fully self contained, e.g. when used for manual imports.
      */
-    version?: string;
+    baseUrl?: string;
     /**
-     * Human-readable title of the system version.
+     * Optional local ID for the system instance, as known by the described system.
+     *
+     * In case of multi-tenant systems, it is equivalent to the local tenant id.
      */
-    title?: string;
+    localId?: string;
     /**
      * Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).
      *
@@ -347,6 +385,14 @@ export interface ApiResource {
      * Detailed documentation SHOULD be attached as (typed) links.
      */
     description: string;
+    /**
+     * Hint for AI consumers (LLMs, agent orchestrators) on how to use or interpret this resource.
+     * Intentionally separate from human-facing `description` so both can evolve independently.
+     * SHOULD be written in [CommonMark](https://spec.commonmark.org/) (Markdown).
+     *
+     * For guidance and best practices, see [AI Agents and Protocols](../concepts/ai-agents-and-protocols#ai-hints-on-ord-resources).
+     */
+    aiHint?: string;
     /**
      * Defines which Package the resource is part of.
      *
@@ -365,6 +411,10 @@ export interface ApiResource {
      * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
      *
      * All resources that share the same group ID assignment are effectively grouped together.
+     *
+     * **Visibility:** Groups and Group Types may carry a `visibility`. Aggregators and consumers MUST NOT expose
+     * group assignments to audiences whose access level exceeds the referenced Group's (or Group Type's) visibility.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
      */
     partOfGroups?: string[];
     /**
@@ -393,11 +443,15 @@ export interface ApiResource {
      */
     defaultConsumptionBundle?: string;
     /**
-     * List of products the resources of the Package are a part of.
+     * List of products this package and its resources are a part of.
      *
      * 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.
+     * `partOfProducts` assigned to a `Package` are inherited by all ORD resources it contains.
+     * Resources that belong to a different product than their package can override this directly.
+     *
+     * Every ORD resource SHOULD be assigned to at least one product, either directly or inherited from its package.
+     * Setting `partOfProducts` on the package is the preferred approach, as it propagates automatically to all contained resources.
      *
      * @minItems 0
      */
@@ -409,13 +463,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -461,7 +515,7 @@ export interface ApiResource {
      *
      * 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.
+     * See [Lifecycle](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
     releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
@@ -538,12 +592,15 @@ export interface ApiResource {
      * If there is no match, the information in ORD takes precedence.
      *
      * **Provider View:**
-     * If the URL is relative to the system that describes the ORD information,
-     * it is RECOMMENDED to use relative references and (if known) to provide the `describedSystemInstance`.`baseUrl`.
+     * Relative entry point URLs are resolved against `describedSystemInstance`.`baseUrl` (the described system's base URL).
+     * It is RECOMMENDED to use relative references and (if known) to provide `describedSystemInstance`.`baseUrl`.
      * If the URL is not relative to the described system instance [base URL](../index.md#base-url), a full URL MUST be provided.
      * If the entry points are rewritten by middleware - incl. the special case of client/consumer specific entry points - it is RECOMMENDED to provide relative URLs, so only the `describedSystemInstance`.`baseUrl` has to be rewritten.
      * The provider should not have to describe all middleware or consumer specific entry points. If they are enriched later by the aggregator, it MAY omit the entry points.
      *
+     * Note: this is distinct from relative resource definition URLs, which resolve against the document root `baseUrl`.
+     * See [Relative URL Resolution](../index.md#relative-url-resolution) for full rules including the aggregator-override behavior.
+     *
      * **Consumer View**:
      * When fetching the information from an ORD Aggregator, the consumer MAY rely on receiving full URLs.
      *
@@ -566,8 +623,10 @@ export interface ApiResource {
      * See also [Resource Definitions](../index.md#resource-definitions) for more context.
      *
      * Each definition is to be understood as an alternative description format, describing the same resource / capability.
-     * As a consequence the same definition type MUST NOT be provided more than once.
-     * The exception is when the same definition type is provided more than once, but with a different `visibility`.
+     * The combination of `type` (or `customType` for `type: "custom"`), `purpose`, and `visibility` MUST be unique within the list.
+     *
+     * A definition without a `purpose` is considered the primary/default definition for its type.
+     * Additional definitions of the same type MAY be provided if they have a distinct `purpose` (e.g., `ord:ai-enrichment` for AI-optimized definitions).
      *
      * It is RECOMMENDED to provide the definitions as they enable machine-readable use cases.
      * If the definitions are added or changed, the `version` MUST be incremented.
@@ -598,6 +657,7 @@ export interface ApiResource {
     customImplementationStandardDescription?: string;
     /**
      * A reference to the interface (API contract) and its maximum version that this API implements. Even if the interface contract evolves compatible, this resource will not be compatible with versions beyond the specified one.
+     * It does not imply the same endpoints, security or tenant specific configuration is used.
      *
      * Serves as a declaration of compatible implementation of API contract, effectively functioning as an "implementationOf" relationship. The data that compatible APIs return follow the same schema, but itself can be different.
      * This means that if one API is returning 1 record for a dedicated request, a compatible API could return multiple and different records, as long as they adhere to the same schema.
@@ -754,7 +814,7 @@ export interface RelatedAPIResource {
      * Defines the semantic meaning of the relationship.
      * If not provided, the relationship has no specific semantics ("related somehow").
      */
-    relationType?: string;
+    relationType?: (string | "ord:patches") & string;
 }
 /**
  * Defines a relation to an Event Resource (via its ORD ID).
@@ -772,7 +832,7 @@ export interface RelatedEventResource {
      * Defines the semantic meaning of the relationship.
      * If not provided, the relationship has no specific semantics ("related somehow").
      */
-    relationType?: string;
+    relationType?: (string | "ord:patches") & string;
 }
 /**
  * A changelog entry can be used to indicate changes.
@@ -794,7 +854,7 @@ export interface ChangelogEntry {
      *
      * 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.
+     * See [Lifecycle](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
     releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
@@ -826,7 +886,7 @@ export interface ApiResourceDefinition {
      * Type of the API Resource Definition
      * If "custom" is chosen, a customType MUST be provided
      */
-    type: (string | "openapi-v2" | "openapi-v3" | "openapi-v3.1+" | "raml-v1" | "edmx" | "csdl-json" | "graphql-sdl" | "wsdl-v1" | "wsdl-v2" | "a2a-agent-card" | "sap-rfc-metadata-v1" | "sap-sql-api-definition-v1" | "sap-csn-interop-effective-v1" | "custom") & string;
+    type: (string | "openapi-v2" | "openapi-v3" | "openapi-v3.1+" | "raml-v1" | "edmx" | "csdl-json" | "graphql-sdl" | "wsdl-v1" | "wsdl-v2" | "a2a-agent-card" | "sap-rfc-metadata-v1" | "sap-sql-api-definition-v1" | "sap-csn-interop-effective-v1" | "ord:overlay:v1" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -848,7 +908,8 @@ export interface ApiResourceDefinition {
     /**
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
      *
-     * It is RECOMMENDED to provide a relative URL (to base URL).
+     * It is RECOMMENDED to provide a relative URL.
+     * If relative, it is resolved against the ORD Document's root [`baseUrl`](#ord-document_baseurl) (the ORD provider base URL).
      */
     url: string;
     /**
@@ -875,6 +936,22 @@ export interface ApiResourceDefinition {
      * @minItems 1
      */
     accessStrategies?: [MetadataDefinitionAccessStrategy, ...MetadataDefinitionAccessStrategy[]];
+    /**
+     * Describes the intended purpose or role of this resource definition.
+     *
+     * While `type` specifies the format (e.g., OpenAPI, AsyncAPI), `purpose` indicates what the definition is used for.
+     * This allows multiple definitions of the same type to coexist when they serve different purposes.
+     *
+     * For example, an API Resource might have multiple OpenAPI definitions:
+     * one for standard API documentation and another specifically enriched for AI/agent consumption.
+     *
+     * Together with `type` (or `customType`) and `visibility`, `purpose` forms the uniqueness
+     * key for entries in the `resourceDefinitions` list — no two entries on the same resource
+     * may share the same combination.
+     *
+     * MUST be a valid [Concept ID](../index.md#concept-id).
+     */
+    purpose?: (string | "ord:ai-enrichment") & string;
 }
 /**
  * Defines the [access strategy](../../spec-extensions/access-strategies/) for accessing the resource definitions.
@@ -1070,7 +1147,7 @@ export interface ApiAndEventResourceLink {
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the API or Event Resource Link.
      *
      * The link target SHOULD be absolute and SHOULD be openly accessible.
-     * If a relative link is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl).
+     * If a relative link is given, it is resolved against the ORD Document's root [`baseUrl`](#ord-document_baseurl) (the ORD provider base URL).
      */
     url: string;
 }
@@ -1103,14 +1180,7 @@ export interface Link {
  * If applicable, a description and further resources about extending this resource are provided.
  */
 export interface Extensible {
-    /**
-     * This property defines whether the resource is extensible.
-     *
-     * **Not extensible** means that the data model of the resource (i.e. API or event) cannot be extended with custom fields.
-     * **Manually extensible** means that in addition to defining a custom field, manual activities to include the field in the data model of the resource (i.e. API or event) are required. E.g. using a specific mapping tool or by selecting the resource in the data model extension tool.
-     * **Automatically extensible** means that after defining a custom field in the local domain model, the resource (i.e. API or event) is automatically extended as part of the default extension field definition.
-     */
-    supported: "no" | "manual" | "automatic";
+    supported: ExtensibilitySupportLevel;
     /**
      * A description about the extensibility capabilities of this API, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).
      *
@@ -1173,6 +1243,14 @@ export interface EventResource {
      * Detailed documentation SHOULD be attached as (typed) links.
      */
     description: string;
+    /**
+     * Hint for AI consumers (LLMs, agent orchestrators) on how to use or interpret this resource.
+     * Intentionally separate from human-facing `description` so both can evolve independently.
+     * SHOULD be written in [CommonMark](https://spec.commonmark.org/) (Markdown).
+     *
+     * For guidance and best practices, see [AI Agents and Protocols](../concepts/ai-agents-and-protocols#ai-hints-on-ord-resources).
+     */
+    aiHint?: string;
     /**
      * Defines which Package the resource is part of.
      *
@@ -1191,6 +1269,10 @@ export interface EventResource {
      * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
      *
      * All resources that share the same group ID assignment are effectively grouped together.
+     *
+     * **Visibility:** Groups and Group Types may carry a `visibility`. Aggregators and consumers MUST NOT expose
+     * group assignments to audiences whose access level exceeds the referenced Group's (or Group Type's) visibility.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
      */
     partOfGroups?: string[];
     /**
@@ -1219,11 +1301,15 @@ export interface EventResource {
      */
     defaultConsumptionBundle?: string;
     /**
-     * List of products the resources of the Package are a part of.
+     * List of products this package and its resources are a part of.
      *
      * 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.
+     * `partOfProducts` assigned to a `Package` are inherited by all ORD resources it contains.
+     * Resources that belong to a different product than their package can override this directly.
+     *
+     * Every ORD resource SHOULD be assigned to at least one product, either directly or inherited from its package.
+     * Setting `partOfProducts` on the package is the preferred approach, as it propagates automatically to all contained resources.
      *
      * @minItems 0
      */
@@ -1235,13 +1321,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -1287,7 +1373,7 @@ export interface EventResource {
      *
      * 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.
+     * See [Lifecycle](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
     releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
@@ -1356,8 +1442,10 @@ export interface EventResource {
      * See also [Resource Definitions](../index.md#resource-definitions) for more context.
      *
      * Each definition is to be understood as an alternative description format, describing the same resource / capability.
-     * As a consequence the same definition type MUST NOT be provided more than once.
-     * The exception is when the same definition type is provided more than once, but with a different `visibility`.
+     * The combination of `type` (or `customType` for `type: "custom"`), `purpose`, and `visibility` MUST be unique within the list.
+     *
+     * A definition without a `purpose` is considered the primary/default definition for its type.
+     * Additional definitions of the same type MAY be provided if they have a distinct `purpose` (e.g., `ord:ai-enrichment` for AI-optimized definitions).
      *
      * It is RECOMMENDED to provide the definitions as they enable machine-readable use cases.
      * If the definitions are added or changed, the `version` MUST be incremented.
@@ -1506,7 +1594,7 @@ export interface EventResourceDefinition {
     /**
      * Type of the event resource definition
      */
-    type: (string | "asyncapi-v2" | "sap-csn-interop-effective-v1" | "custom") & string;
+    type: (string | "asyncapi-v2" | "sap-csn-interop-effective-v1" | "ord:overlay:v1" | "custom") & string;
     /**
      * If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.
      *
@@ -1528,7 +1616,8 @@ export interface EventResourceDefinition {
     /**
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
      *
-     * It is RECOMMENDED to provide a relative URL (to base URL).
+     * It is RECOMMENDED to provide a relative URL.
+     * If relative, it is resolved against the ORD Document's root [`baseUrl`](#ord-document_baseurl) (the ORD provider base URL).
      */
     url: string;
     /**
@@ -1555,6 +1644,22 @@ export interface EventResourceDefinition {
      * in case that some metadata must only be made accessible to internal consumers.
      */
     visibility?: "public" | "internal" | "private";
+    /**
+     * Describes the intended purpose or role of this resource definition.
+     *
+     * While `type` specifies the format (e.g., OpenAPI, AsyncAPI), `purpose` indicates what the definition is used for.
+     * This allows multiple definitions of the same type to coexist when they serve different purposes.
+     *
+     * For example, an API Resource might have multiple OpenAPI definitions:
+     * one for standard API documentation and another specifically enriched for AI/agent consumption.
+     *
+     * Together with `type` (or `customType`) and `visibility`, `purpose` forms the uniqueness
+     * key for entries in the `resourceDefinitions` list — no two entries on the same resource
+     * may share the same combination.
+     *
+     * MUST be a valid [Concept ID](../index.md#concept-id).
+     */
+    purpose?: (string | "ord:ai-enrichment") & string;
 }
 /**
  * Describes the compatibility of the Event with other Events. This can be used to express that an Event is compatible with another Event version.
@@ -1629,6 +1734,14 @@ export interface EntityType {
      * Detailed documentation SHOULD be attached as (typed) links.
      */
     description?: string;
+    /**
+     * Hint for AI consumers (LLMs, agent orchestrators) on how to use or interpret this resource.
+     * Intentionally separate from human-facing `description` so both can evolve independently.
+     * SHOULD be written in [CommonMark](https://spec.commonmark.org/) (Markdown).
+     *
+     * For guidance and best practices, see [AI Agents and Protocols](../concepts/ai-agents-and-protocols#ai-hints-on-ord-resources).
+     */
+    aiHint?: string;
     /**
      * Defines which Package the resource is part of.
      *
@@ -1647,14 +1760,22 @@ export interface EntityType {
      * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
      *
      * All resources that share the same group ID assignment are effectively grouped together.
+     *
+     * **Visibility:** Groups and Group Types may carry a `visibility`. Aggregators and consumers MUST NOT expose
+     * group assignments to audiences whose access level exceeds the referenced Group's (or Group Type's) visibility.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
      */
     partOfGroups?: string[];
     /**
-     * List of products the resources of the Package are a part of.
+     * List of products this package and its resources are a part of.
      *
      * 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.
+     * `partOfProducts` assigned to a `Package` are inherited by all ORD resources it contains.
+     * Resources that belong to a different product than their package can override this directly.
+     *
+     * Every ORD resource SHOULD be assigned to at least one product, either directly or inherited from its package.
+     * Setting `partOfProducts` on the package is the preferred approach, as it propagates automatically to all contained resources.
      *
      * @minItems 0
      */
@@ -1666,13 +1787,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -1708,7 +1829,7 @@ export interface EntityType {
      *
      * 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.
+     * See [Lifecycle](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
     releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
@@ -1743,7 +1864,7 @@ export interface EntityType {
     /**
      * Defining the abstraction level of the entity type using the DDD terminology.
      *
-     * In Domain-Driven Design, there is a concept of entities and aggregates.
+     * In Domain-Driven Design, there is a concept of domain 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.
      * An aggregate is a cluster of domain objects that can be treated as a single unit.
@@ -1759,6 +1880,10 @@ export interface EntityType {
      * Usually this happens if there are similar conceptual entity types across different namespaces.
      */
     relatedEntityTypes?: RelatedEntityType[];
+    /**
+     * List of available machine-readable definitions that describe the entity type's internal model in detail.
+     */
+    definitions?: EntityTypeDefinition[];
     /**
      * Generic Links with arbitrary meaning and content.
      */
@@ -1831,6 +1956,68 @@ export interface RelatedEntityType {
      */
     relationType?: (string | "part-of" | "can-share-identity") & string;
 }
+/**
+ * Machine-readable definition that describes the entity type's internal model structure.
+ *
+ * Entity Type definitions represent an internal implementation detail - the underlying domain model of your application.
+ * This can be used to describe a shared internal model multiple APIs and Events are based on.
+ * However, interaction with the actual data happens through API Resources or Event Resources that expose these entity types with a defined interface and contract.
+ *
+ * Each definition is an alternative description format for the same entity type.
+ * The same definition type MUST NOT be provided more than once, except with different `visibility` or `mediaType`.
+ *
+ * **Why Entity Types are private by default**: Since entity type definitions are internal implementation details, they SHOULD be marked as `private` visibility by default.
+ *
+ * **Finding related APIs**: To discover which APIs expose a particular Entity Type, check the API Resource's `relatedEntityTypes` property.
+ */
+export interface EntityTypeDefinition {
+    /**
+     * Type of the entity type resource definition.
+     *
+     * MUST be either:
+     * - any valid [Specification ID](../index.md#specification-id), or
+     * - one of the pre-defined values listed below.
+     */
+    type: (string | "sap-csn-interop-effective-v1") & string;
+    /**
+     * [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) that describes the format of the definition.
+     *
+     * Media Types under `application/*` and `text/*` are allowed.
+     * 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;
+    /**
+     * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
+     *
+     * It is RECOMMENDED to provide a relative URL (to base URL).
+     */
+    url: string;
+    /**
+     * List of supported access strategies for retrieving metadata from the ORD provider.
+     * An ORD Consumer/ORD Aggregator MAY choose any of the strategies.
+     *
+     * The access strategies only apply to the metadata access and not the actual API access.
+     * The actual access to the APIs for clients is described via Consumption Bundles.
+     *
+     * If this property is not provided, the definition URL will be available through the same access strategy as this ORD document.
+     * It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process.
+     *
+     * @minItems 1
+     */
+    accessStrategies?: [MetadataDefinitionAccessStrategy, ...MetadataDefinitionAccessStrategy[]];
+    /**
+     * Who is allowed to access the entity type definition. Defaults to `private`.
+     *
+     * Entity Type definitions are internal implementation details and SHOULD remain `private` by default.
+     * Consumers interact with the data through related API Resources, not the internal model directly.
+     *
+     * The visibility MUST be equal to or more restrictive than the Entity Type resource's visibility.
+     *
+     * Only use `public` visibility when the internal model definition itself needs open access for standardization or documentation purposes.
+     */
+    visibility: "public" | "internal" | "private";
+}
 /**
  * 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.
  * This is a generic ORD concept that aims to cover many different capability discovery use cases that would otherwise need be implemented as individual service provider interfaces (SPIs).
@@ -1896,6 +2083,14 @@ export interface Capability {
      * Detailed documentation SHOULD be attached as (typed) links.
      */
     description?: string;
+    /**
+     * Hint for AI consumers (LLMs, agent orchestrators) on how to use or interpret this resource.
+     * Intentionally separate from human-facing `description` so both can evolve independently.
+     * SHOULD be written in [CommonMark](https://spec.commonmark.org/) (Markdown).
+     *
+     * For guidance and best practices, see [AI Agents and Protocols](../concepts/ai-agents-and-protocols#ai-hints-on-ord-resources).
+     */
+    aiHint?: string;
     /**
      * Defines which Package the resource is part of.
      *
@@ -1914,6 +2109,10 @@ export interface Capability {
      * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
      *
      * All resources that share the same group ID assignment are effectively grouped together.
+     *
+     * **Visibility:** Groups and Group Types may carry a `visibility`. Aggregators and consumers MUST NOT expose
+     * group assignments to audiences whose access level exceeds the referenced Group's (or Group Type's) visibility.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
      */
     partOfGroups?: string[];
     /**
@@ -1923,13 +2122,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -1965,7 +2164,7 @@ export interface Capability {
      *
      * 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.
+     * See [Lifecycle](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
     releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
@@ -2016,8 +2215,10 @@ export interface Capability {
      * See also [Resource Definitions](../index.md#resource-definitions) for more context.
      *
      * Each definition is to be understood as an alternative description format, describing the same resource / capability.
-     * As a consequence the same definition type MUST NOT be provided more than once.
-     * The exception is when the same definition type is provided more than once, but with a different `visibility`.
+     * The combination of `type` (or `customType` for `type: "custom"`), `purpose`, and `visibility` MUST be unique within the list.
+     *
+     * A definition without a `purpose` is considered the primary/default definition for its type.
+     * Additional definitions of the same type MAY be provided if they have a distinct `purpose` (e.g., `ord:ai-enrichment` for AI-optimized definitions).
      *
      * It is RECOMMENDED to provide the definitions as they enable machine-readable use cases.
      * If the definitions are added or changed, the `version` MUST be incremented.
@@ -2098,7 +2299,8 @@ export interface CapabilityDefinition {
     /**
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
      *
-     * It is RECOMMENDED to provide a relative URL (to base URL).
+     * It is RECOMMENDED to provide a relative URL.
+     * If relative, it is resolved against the ORD Document's root [`baseUrl`](#ord-document_baseurl) (the ORD provider base URL).
      */
     url: string;
     /**
@@ -2125,6 +2327,22 @@ export interface CapabilityDefinition {
      * in case that some metadata must only be made accessible to internal consumers.
      */
     visibility?: "public" | "internal" | "private";
+    /**
+     * Describes the intended purpose or role of this resource definition.
+     *
+     * While `type` specifies the format (e.g., OpenAPI, AsyncAPI), `purpose` indicates what the definition is used for.
+     * This allows multiple definitions of the same type to coexist when they serve different purposes.
+     *
+     * For example, an API Resource might have multiple OpenAPI definitions:
+     * one for standard API documentation and another specifically enriched for AI/agent consumption.
+     *
+     * Together with `type` (or `customType`) and `visibility`, `purpose` forms the uniqueness
+     * key for entries in the `resourceDefinitions` list — no two entries on the same resource
+     * may share the same combination.
+     *
+     * MUST be a valid [Concept ID](../index.md#concept-id).
+     */
+    purpose?: (string | "ord:ai-enrichment") & string;
 }
 /**
  * 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).
@@ -2177,6 +2395,14 @@ export interface DataProduct {
      * Detailed documentation SHOULD be attached as (typed) links.
      */
     description: string;
+    /**
+     * Hint for AI consumers (LLMs, agent orchestrators) on how to use or interpret this resource.
+     * Intentionally separate from human-facing `description` so both can evolve independently.
+     * SHOULD be written in [CommonMark](https://spec.commonmark.org/) (Markdown).
+     *
+     * For guidance and best practices, see [AI Agents and Protocols](../concepts/ai-agents-and-protocols#ai-hints-on-ord-resources).
+     */
+    aiHint?: string;
     /**
      * Defines which Package the resource is part of.
      *
@@ -2195,6 +2421,10 @@ export interface DataProduct {
      * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
      *
      * All resources that share the same group ID assignment are effectively grouped together.
+     *
+     * **Visibility:** Groups and Group Types may carry a `visibility`. Aggregators and consumers MUST NOT expose
+     * group assignments to audiences whose access level exceeds the referenced Group's (or Group Type's) visibility.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
      */
     partOfGroups?: string[];
     /**
@@ -2202,7 +2432,11 @@ export interface DataProduct {
      *
      * 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.
+     * `partOfProducts` assigned to a `Package` are inherited by all ORD resources it contains.
+     * Resources that belong to a different product than their package can override this directly.
+     *
+     * Every ORD resource SHOULD be assigned to at least one product, either directly or inherited from its package.
+     * Setting `partOfProducts` on the package is the preferred approach, as it propagates automatically to all contained resources.
      *
      * @minItems 0
      */
@@ -2214,13 +2448,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -2478,7 +2712,7 @@ export interface DataProductLink {
      * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the Data Product Link.
      *
      * The link target SHOULD be absolute and SHOULD be openly accessible.
-     * If a relative link is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl).
+     * If a relative link is given, it is resolved against the ORD Document's root [`baseUrl`](#ord-document_baseurl) (the ORD provider base URL).
      */
     url: string;
 }
@@ -2537,6 +2771,14 @@ export interface Agent {
      * Detailed documentation SHOULD be attached as (typed) links.
      */
     description?: string;
+    /**
+     * Hint for AI consumers (LLMs, agent orchestrators) on how to use or interpret this resource.
+     * Intentionally separate from human-facing `description` so both can evolve independently.
+     * SHOULD be written in [CommonMark](https://spec.commonmark.org/) (Markdown).
+     *
+     * For guidance and best practices, see [AI Agents and Protocols](../concepts/ai-agents-and-protocols#ai-hints-on-ord-resources).
+     */
+    aiHint?: string;
     /**
      * Defines which Package the resource is part of.
      *
@@ -2555,6 +2797,10 @@ export interface Agent {
      * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
      *
      * All resources that share the same group ID assignment are effectively grouped together.
+     *
+     * **Visibility:** Groups and Group Types may carry a `visibility`. Aggregators and consumers MUST NOT expose
+     * group assignments to audiences whose access level exceeds the referenced Group's (or Group Type's) visibility.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
      */
     partOfGroups?: string[];
     /**
@@ -2564,13 +2810,13 @@ export interface Agent {
      * 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -2606,7 +2852,7 @@ export interface Agent {
      *
      * 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.
+     * See [Lifecycle](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
     releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
@@ -2630,11 +2876,15 @@ export interface Agent {
      */
     minSystemVersion?: string;
     /**
-     * List of products the resources of the Package are a part of.
+     * List of products this package and its resources are a part of.
      *
      * 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.
+     * `partOfProducts` assigned to a `Package` are inherited by all ORD resources it contains.
+     * Resources that belong to a different product than their package can override this directly.
+     *
+     * Every ORD resource SHOULD be assigned to at least one product, either directly or inherited from its package.
+     * Setting `partOfProducts` on the package is the preferred approach, as it propagates automatically to all contained resources.
      *
      * @minItems 0
      */
@@ -2748,6 +2998,188 @@ export interface ExposedAPIResource {
      */
     ordId: string;
 }
+/**
+ * An Overlay Resource is a standalone, versioned resource that references a metadata patch file.
+ * Overlays enrich / patch resource definition files (e.g. OpenAPI) without modifying the originals, e.g. to add AI-optimized descriptions, apply governance annotations, or adapt definitions for a specific audience / purpose.
+ *
+ * Use an Overlay Resource for overlays that serve a different concern or audience than the original metadata — such as AI enrichment, governance annotations, or audience-specific adaptations — and are managed independently or applied across multiple resources.
+ * For producer-owned overlays that belong to a single resource, they SHOULD instead be attached directly as a `resourceDefinitions` entry with `type: ord:overlay:v1`.
+ */
+export interface Overlay {
+    /**
+     * 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;
+    /**
+     * Human-readable title.
+     *
+     * MUST NOT exceed 255 chars.
+     * MUST NOT contain line breaks.
+     */
+    title?: 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 complete [SemVer](https://semver.org/) version string.
+     *
+     * It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.
+     * 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](../index.md#ord-id) `<majorVersion>` fragment SHOULD be updated to be identical.
+     * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
+     * The `version` MUST not be bumped for changes in extensions.
+     *
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
+     *
+     * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
+     * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
+     */
+    version: string;
+    /**
+     * Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.
+     *
+     * The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
+     *
+     * When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.
+     * Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.
+     *
+     * If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.
+     *
+     * Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.
+     */
+    lastUpdate?: string;
+    /**
+     * 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";
+    /**
+     * 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](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
+     */
+    releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
+    /**
+     * Optional list of API Resources whose definition files this overlay patches.
+     *
+     * SHOULD be provided when the target resource is described in an ORD document accessible to the same aggregator,
+     * as it enables efficient indexing without requiring the aggregator to parse each overlay file.
+     * Use `relationType: ord:patches` to express the patching relationship.
+     *
+     * May be omitted when the target resource is not described in an accessible ORD document,
+     * or when the overlay is cross-cutting and patches resources from multiple providers.
+     */
+    relatedApiResources?: RelatedAPIResource[];
+    /**
+     * Optional list of Event Resources whose definition files this overlay patches.
+     *
+     * SHOULD be provided when the target resource is described in an ORD document accessible to the same aggregator,
+     * as it enables efficient indexing without requiring the aggregator to parse each overlay file.
+     * Use `relationType: ord:patches` to express the patching relationship.
+     *
+     * May be omitted when the target resource is not described in an accessible ORD document,
+     * or when the overlay is cross-cutting and patches resources from multiple providers.
+     */
+    relatedEventResources?: RelatedEventResource[];
+    /**
+     * List of overlay definition files referenced by this ORD Overlay Resource.
+     * Each entry points to an ORD Overlay document (`type: ord:overlay:v1`) that contains the actual patches.
+     */
+    definitions?: OverlayDefinition[];
+    /**
+     * 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[];
+    labels?: Labels;
+}
+/**
+ * Link to a machine-readable [ORD Overlay](../../spec-v1/interfaces/OrdOverlay) document.
+ */
+export interface OverlayDefinition {
+    /**
+     * Type of the overlay definition
+     */
+    type: ("ord:overlay:v1" | string) & 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.
+     * For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON.
+     *
+     * 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;
+    /**
+     * [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.
+     *
+     * It is RECOMMENDED to provide a relative URL.
+     * If relative, it is resolved against the ORD Document's root [`baseUrl`](#ord-document_baseurl) (the ORD provider base URL).
+     */
+    url: string;
+    /**
+     * List of supported access strategies for retrieving metadata from the ORD provider.
+     * An ORD Consumer/ORD Aggregator MAY choose any of the strategies.
+     *
+     * The access strategies only apply to the metadata access and not the actual API access.
+     * The actual access to the APIs for clients is described via Consumption Bundles.
+     *
+     * If this property is not provided, the definition URL will be available through the same access strategy as this ORD document.
+     * It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process.
+     *
+     * @minItems 1
+     */
+    accessStrategies?: [MetadataDefinitionAccessStrategy, ...MetadataDefinitionAccessStrategy[]];
+    /**
+     * The visibility states who is allowed to "see" and access the resource definition, in case it differs from the resource visibility.
+     *
+     * If not given, the resource definition has the same visibility as the resource it describes.
+     * The visibility of a resource definition MUST be lower (more restrictive) than the visibility of the resource it describes.
+     * E.g. a public resource can have metadata definitions that are internal only. An internal resource can't declare to have a public metadata definition.
+     *
+     * This makes it also possible to provide both a public and an internal metadata description of the resource,
+     * in case that some metadata must only be made accessible to internal consumers.
+     */
+    visibility?: "public" | "internal" | "private";
+    /**
+     * Describes the intended purpose or role of this resource definition.
+     *
+     * While `type` specifies the format (e.g., OpenAPI, AsyncAPI), `purpose` indicates what the definition is used for.
+     * This allows multiple definitions of the same type to coexist when they serve different purposes.
+     *
+     * For example, an API Resource might have multiple OpenAPI definitions:
+     * one for standard API documentation and another specifically enriched for AI/agent consumption.
+     *
+     * Together with `type` (or `customType`) and `visibility`, `purpose` forms the uniqueness
+     * key for entries in the `resourceDefinitions` list — no two entries on the same resource
+     * may share the same combination.
+     *
+     * MUST be a valid [Concept ID](../index.md#concept-id).
+     */
+    purpose?: (string | "ord:ai-enrichment") & string;
+}
 /**
  * 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.
@@ -2833,6 +3265,10 @@ export interface IntegrationDependency {
      * If an "identity / equals" relationship needs to be expressed, use the `correlationIds` instead.
      *
      * All resources that share the same group ID assignment are effectively grouped together.
+     *
+     * **Visibility:** Groups and Group Types may carry a `visibility`. Aggregators and consumers MUST NOT expose
+     * group assignments to audiences whose access level exceeds the referenced Group's (or Group Type's) visibility.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
      */
     partOfGroups?: string[];
     /**
@@ -2842,13 +3278,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -2884,7 +3320,7 @@ export interface IntegrationDependency {
      *
      * 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.
+     * See [Lifecycle](../concepts/versioning-and-lifecycle.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.
      */
     releaseStatus: "development" | "beta" | "active" | "deprecated" | "sunset";
     /**
@@ -2996,15 +3432,23 @@ export interface ApiResourceIntegrationAspect {
      */
     minVersion?: string;
     /**
-     * List of individual API operations that are sufficient to achieve the aspect.
+     * Narrows the dependency to only the listed API operations (or MCP tools) that are required to achieve the aspect.
+     *
+     * If `subset` is not provided, the dependency implies that all operations of the referenced resource may be used.
+     * If `subset` is provided, only the listed operations are required — consumers MUST NOT assume that other operations are available or permitted.
+     *
+     * For more details and examples, see [Integration Dependency](../concepts/integration-dependency).
      */
     subset?: APIResourceIntegrationAspectSubset[];
 }
 /**
- * Defines that API Resource Integration Aspect only requires a subset of the referenced contract.
+ * Defines that the API Resource Integration Aspect only requires a subset of the referenced contract.
  *
  * For APIs, this is a list of the operations or tools that need to be available in order to make the integration work.
- * This information helps to narrow down what is really necessary and can help optimize the integration.
+ * Without a `subset`, the dependency implies access to the full resource.
+ * With a `subset`, only the listed operations are required, allowing consumers to understand /load only the minimal surface area needed.
+ *
+ * For more details and examples, see [Integration Dependency](../concepts/integration-dependency).
  */
 export interface APIResourceIntegrationAspectSubset {
     /**
@@ -3262,13 +3706,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -3339,11 +3783,15 @@ export interface Package {
      */
     vendor: string;
     /**
-     * List of products the resources of the Package are a part of.
+     * List of products this package and its resources are a part of.
      *
      * 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.
+     * `partOfProducts` assigned to a `Package` are inherited by all ORD resources it contains.
+     * Resources that belong to a different product than their package can override this directly.
+     *
+     * Every ORD resource SHOULD be assigned to at least one product, either directly or inherited from its package.
+     * Setting `partOfProducts` on the package is the preferred approach, as it propagates automatically to all contained resources.
      *
      * @minItems 0
      */
@@ -3424,7 +3872,7 @@ export interface File {
      * [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 a relative URL is given, it is resolved against the ORD Document's root [`baseUrl`](#ord-document_baseurl) (the ORD provider base URL).
      * If an absolute URL is given, then it MUST be openly accessible.
      */
     url: string;
@@ -3512,13 +3960,13 @@ 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](../index.md#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 SHOULD be updated to be identical.
      * In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#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`.
      * The `version` MUST not be bumped for changes in extensions.
      *
-     * The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.
+     * The general [Version and Lifecycle](../concepts/versioning-and-lifecycle.md) flow MUST be followed.
      *
      * Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.
      * For example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.
@@ -3663,6 +4111,12 @@ export interface Group {
      * This relationship does not imply inheritance, but can be interpreted as such for specific group types and scenarios.
      */
     partOfGroups?: string[];
+    /**
+     * Defines who is allowed to discover and access this Group and its metadata.
+     * Defaults to `public` if not set.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
+     */
+    visibility?: "public" | "internal" | "private";
     [k: string]: unknown | undefined;
 }
 /**
@@ -3708,6 +4162,12 @@ export interface GroupType {
      * This relationship does not imply inheritance, but can be interpreted as such for specific group types and scenarios.
      */
     partOfGroupTypes?: string[];
+    /**
+     * Defines who is allowed to discover and access this Group Type and its metadata.
+     * Defaults to `public` if not set.
+     * See [Visibility of Groups and Group Types](../concepts/grouping-and-bundling#visibility-of-groups-and-group-types).
+     */
+    visibility?: "public" | "internal" | "private";
     [k: string]: unknown | undefined;
 }
 /**