@open-resource-discovery/specification 1.15.0 → 1.16.0

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

@@ -23,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" | "1.15";
+    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.
@@ -31,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).
      *
@@ -265,10 +283,16 @@ export interface SystemVersion {
  */
 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.
+     * Optional [base URL](../index.md#base-url) of the **described system instance**.
+     *
+     * 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).
+     *
+     * 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.
      *
-     * The `baseUrl` MUST not contain a leading slash.
+     * 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.
@@ -361,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.
      *
@@ -379,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[];
     /**
@@ -407,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
      */
@@ -423,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.
@@ -475,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";
     /**
@@ -552,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.
      *
@@ -580,7 +623,7 @@ 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.
-     * The combination of `type`, `purpose`, and `visibility` MUST be unique within the list.
+     * 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).
@@ -614,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.
@@ -810,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";
     /**
@@ -864,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;
     /**
@@ -900,6 +945,10 @@ export interface ApiResourceDefinition {
      * 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;
@@ -1098,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;
 }
@@ -1194,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.
      *
@@ -1212,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[];
     /**
@@ -1240,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
      */
@@ -1256,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.
@@ -1308,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";
     /**
@@ -1377,7 +1442,7 @@ 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.
-     * The combination of `type`, `purpose`, and `visibility` MUST be unique within the list.
+     * 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).
@@ -1551,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;
     /**
@@ -1587,6 +1653,10 @@ export interface EventResourceDefinition {
      * 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;
@@ -1664,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.
      *
@@ -1682,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
      */
@@ -1701,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.
@@ -1743,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";
     /**
@@ -1778,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.
@@ -1794,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.
      */
@@ -1866,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).
@@ -1931,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.
      *
@@ -1949,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[];
     /**
@@ -1958,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.
@@ -2000,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";
     /**
@@ -2051,7 +2215,7 @@ 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.
-     * The combination of `type`, `purpose`, and `visibility` MUST be unique within the list.
+     * 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).
@@ -2135,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;
     /**
@@ -2171,6 +2336,10 @@ export interface CapabilityDefinition {
      * 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;
@@ -2226,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.
      *
@@ -2244,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[];
     /**
@@ -2251,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
      */
@@ -2263,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.
@@ -2527,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;
 }
@@ -2586,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.
      *
@@ -2604,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[];
     /**
@@ -2613,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.
@@ -2655,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";
     /**
@@ -2679,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
      */
@@ -2832,13 +3033,13 @@ export interface Overlay {
      * 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.
@@ -2874,7 +3075,7 @@ export interface Overlay {
      *
      * 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";
     /**
@@ -2934,7 +3135,8 @@ export interface OverlayDefinition {
     /**
      * [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;
     /**
@@ -2970,6 +3172,10 @@ export interface OverlayDefinition {
      * 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;
@@ -3059,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[];
     /**
@@ -3068,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.
@@ -3110,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";
     /**
@@ -3222,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 {
     /**
@@ -3488,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.
@@ -3565,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
      */
@@ -3650,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;
@@ -3738,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.
@@ -3889,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;
 }
 /**
@@ -3934,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;
 }
 /**