@open-resource-discovery/specification 1.14.0 → 1.14.2

package/dist/generated/spec/v1/schemas/Document.schema.json

@@ -114,6 +114,8 @@
             ],
             "default": "none",
             "x-introduced-in-version": "1.3.0",
+            "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+            "x-deprecated-in-version": "1.9.9",
             "examples": [
                 "sap:core:v1"
             ]
@@ -124,6 +126,8 @@
             "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
             "maxLength": 255,
             "x-introduced-in-version": "1.3.0",
+            "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+            "x-deprecated-in-version": "1.9.9",
             "examples": [
                 "sap.xref:customPolicy:v1"
             ]
@@ -336,6 +340,8 @@
                     ],
                     "default": "none",
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap:core:v1"
                     ]
@@ -346,6 +352,8 @@
                     "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
                     "maxLength": 255,
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap.xref:customPolicy:v1"
                     ]
@@ -377,6 +385,14 @@
                         "$ref": "#/definitions/Link"
                     }
                 },
+                "files": {
+                    "type": "array",
+                    "x-introduced-in-version": "1.14.2",
+                    "description": "Generic list of files with arbitrary meaning and content. Meant to be used for linking PDFs, Word or similar content. This option MUST NOT be used for linking the actual metadata files like OpenAPI, AsyncAPI, CSN, etc.",
+                    "items": {
+                        "$ref": "#/definitions/File"
+                    }
+                },
                 "licenseType": {
                     "type": "string",
                     "minLength": 1,
@@ -755,19 +771,19 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
@@ -1005,41 +1021,46 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -1145,32 +1166,32 @@
                         },
                         {
                             "const": "odata-v2",
-                            "description": "[OData Version 2.0](https://www.odata.org/documentation/odata-version-2-0/) API.\nAn API Resource definition of type `edmx` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `edmx`, `csdl-json`, `openapi-v2`, `openapi-v3`, `openapi-v3.1+`, `sap-csn-interop-effective-v1` or `custom`."
+                            "description": "[OData Version 2.0](https://www.odata.org/documentation/odata-version-2-0/) API.\nAn API Resource definition of type `edmx` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `edmx`, `csdl-json`, `openapi-v2`, `openapi-v3`, `openapi-v3.1+`, `sap-csn-interop-effective-v1`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "odata-v4",
-                            "description": "[OData Version 4](https://www.odata.org/documentation/) API.\nAn OData V4 API MUST be described via a Common Schema Definition Language (CSDL).\nAn API Resource definition of type `edmx` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `edmx`, `csdl-json`, `openapi-v2`, `openapi-v3`, `openapi-v3.1+`, `sap-csn-interop-effective-v1` or `custom`."
+                            "description": "[OData Version 4](https://www.odata.org/documentation/) API.\nAn OData V4 API MUST be described via a Common Schema Definition Language (CSDL).\nAn API Resource definition of type `edmx` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `edmx`, `csdl-json`, `openapi-v2`, `openapi-v3`, `openapi-v3.1+`, `sap-csn-interop-effective-v1`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "rest",
-                            "description": "Generic [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API.\nPlease not that while OData is also a REST API, the most precise/opinionated `apiProtocol` MUST be chosen.\nAn API Resource definition of type `openapi-v3` (RECOMMENDED) or another appropriate option SHOULD be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `openapi-v2`, `openapi-v3`, `openapi-v3.1+`, `raml-v1`, `sap-csn-interop-effective-v1` or `custom`."
+                            "description": "Generic [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API.\nPlease not that while OData is also a REST API, the most precise/opinionated `apiProtocol` MUST be chosen.\nAn API Resource definition of type `openapi-v3` (RECOMMENDED) or another appropriate option SHOULD be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `openapi-v2`, `openapi-v3`, `openapi-v3.1+`, `raml-v1`, `sap-csn-interop-effective-v1`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "graphql",
-                            "description": "[GraphQL](https://graphql.org/) API.\nAn API Resource definition of type `graphql-sdl` SHOULD be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `graphql-sdl`, `sap-csn-interop-effective-v1` or `custom`."
+                            "description": "[GraphQL](https://graphql.org/) API.\nAn API Resource definition of type `graphql-sdl` SHOULD be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `graphql-sdl`, `sap-csn-interop-effective-v1`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "delta-sharing",
                             "x-introduced-in-version": "1.8.0",
-                            "description": "[Delta Sharing](https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md) Protocol, where one API Resource corresponds to a share.\nFor each API Resource definition: `type` MUST ONLY be set to `sap-csn-interop-effective-v1` or to `custom`.\nFor delta-sharing APIs the resource definition MAY be omitted, as the protocol itself allows for metadata discovery at runtime."
+                            "description": "[Delta Sharing](https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md) Protocol, where one API Resource corresponds to a share.\nFor each API Resource definition: `type` MUST ONLY be set to `sap-csn-interop-effective-v1`, `custom` or any valid [Specification ID](../index.md#specification-id).\nFor delta-sharing APIs the resource definition MAY be omitted, as the protocol itself allows for metadata discovery at runtime."
                         },
                         {
                             "const": "soap-inbound",
-                            "description": "[SOAP](https://en.wikipedia.org/wiki/SOAP) API that provides inbound interfaces.\nAn API Resource definition of type `wsdl-v2` (RECOMMENDED) or `wsdl-v1` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `wsdl-v1`, `wsdl-v2` or `custom`."
+                            "description": "[SOAP](https://en.wikipedia.org/wiki/SOAP) API that provides inbound interfaces.\nAn API Resource definition of type `wsdl-v2` (RECOMMENDED) or `wsdl-v1` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `wsdl-v1`, `wsdl-v2`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "soap-outbound",
-                            "description": "[SOAP](https://en.wikipedia.org/wiki/SOAP) API that provides/describes outbound interfaces for async communication.\nAn API Resource definition of type `wsdl-v2` (RECOMMENDED) or `wsdl-v1` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `wsdl-v1`, `wsdl-v2` or `custom`."
+                            "description": "[SOAP](https://en.wikipedia.org/wiki/SOAP) API that provides/describes outbound interfaces for async communication.\nAn API Resource definition of type `wsdl-v2` (RECOMMENDED) or `wsdl-v1` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `wsdl-v1`, `wsdl-v2`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "mcp",
@@ -1178,7 +1199,7 @@
                         },
                         {
                             "const": "websocket",
-                            "description": "Generic [WebSocket](https://datatracker.ietf.org/doc/html/rfc6455) Protocol.\nSince WebSocket is very generic, it is important to also define or least describe which semantics are concretely used, e.g. via an `implementationStandard`.\nThe API Resource definitions `type` MUST ONLY be set to `custom`."
+                            "description": "Generic [WebSocket](https://datatracker.ietf.org/doc/html/rfc6455) Protocol.\nSince WebSocket is very generic, it is important to also define or least describe which semantics are concretely used, e.g. via an `implementationStandard`.\nThe API Resource definitions `type` MUST ONLY be set to `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "a2a",
@@ -1187,11 +1208,13 @@
                         },
                         {
                             "const": "sap-rfc",
-                            "description": "[SAP RFC](https://help.sap.com/viewer/753088fc00704d0a80e7fbd6803c8adb/202009.000/en-US/4888068ad9134076e10000000a42189d.html) (Remote Function Call)  is the standard SAP interface for communication between SAP systems.\nRFC calls a function to be executed in a remote system.\nAn API Resource definition of type `sap-rfc-metadata-v1` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `sap-rfc-metadata-v1` or `custom`."
+                            "x-introduced-in-version": "1.5.0",
+                            "description": "[SAP RFC](https://help.sap.com/viewer/753088fc00704d0a80e7fbd6803c8adb/202009.000/en-US/4888068ad9134076e10000000a42189d.html) (Remote Function Call)  is the standard SAP interface for communication between SAP systems.\nRFC calls a function to be executed in a remote system.\nAn API Resource definition of type `sap-rfc-metadata-v1` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `sap-rfc-metadata-v1`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "sap-sql-api-v1",
-                            "description": "SAP SQL API that follows the [SQL interface specification for SAP ecosystem](https://github.com/SAP/sql-interface-specification).\nAn API Resource definition of type `sap-sql-api-definition-v1` MUST be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `sap-sql-api-definition-v1`, `sap-csn-interop-effective-v1` or `custom`."
+                            "x-introduced-in-version": "1.9.2",
+                            "description": "SAP SQL API that follows the [SQL interface specification for SAP ecosystem](https://github.com/SAP/sql-interface-specification).\nAn API Resource definition of type `sap-sql-api-definition-v1` SHOULD be provided.\nFor each API Resource definition: `type` MUST ONLY be set to `sap-sql-api-definition-v1`, `sap-csn-interop-effective-v1`, `custom` or any valid [Specification ID](../index.md#specification-id)."
                         },
                         {
                             "const": "sap-ina-api-v1",
@@ -1333,6 +1356,8 @@
                 "entityTypeMappings": {
                     "type": "array",
                     "x-introduced-in-version": "1.6.0",
+                    "x-deprecated-in-version": "1.11.0",
+                    "x-deprecation-text": "Use the simplified `exposedEntityTypes` instead.",
                     "description": "Describes mappings between the API Models of the described resource to the underlying, conceptual entity types.",
                     "items": {
                         "$ref": "#/definitions/EntityTypeMapping"
@@ -1626,6 +1651,8 @@
                     ],
                     "default": "none",
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap:core:v1"
                     ]
@@ -1636,6 +1663,8 @@
                     "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
                     "maxLength": 255,
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap.xref:customPolicy:v1"
                     ]
@@ -1657,6 +1686,8 @@
                     "type": "boolean",
                     "description": "Defines whether this ORD resource is **system-instance-aware**.\nThis is the case when the referenced resource definitions are potentially different between **system instances**.\n\nIf this behavior applies, `systemInstanceAware` MUST be set to true.\nAn ORD aggregator MUST then fetch the referenced resource definitions for _each_ **system instance** individually.\n\nThis concept is now **deprecated** in favor of the more explicit `perspective` attribute.\nAll resources that are system-instance-aware should ideally be put into a dedicated ORD document with `perspective`: `system-instance`.\n\nFor more details, see [perspectives concept page](../concepts/perspectives.md) or the [specification section](../index.md#perspectives).",
                     "default": false,
+                    "x-deprecated-in-version": "1.12.0",
+                    "x-deprecation-text": "Use `perspectives` instead (see [perspectives](../concepts/perspectives) article).",
                     "examples": [
                         true
                     ]
@@ -1835,41 +1866,46 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -2010,6 +2046,8 @@
                 "entityTypeMappings": {
                     "type": "array",
                     "x-introduced-in-version": "1.6.0",
+                    "x-deprecated-in-version": "1.11.0",
+                    "x-deprecation-text": "Use the simplified `exposedEntityTypes` instead.",
                     "description": "Describes mappings between the API Models of the described resource to the underlying, conceptual entity types.",
                     "items": {
                         "$ref": "#/definitions/EntityTypeMapping"
@@ -2304,6 +2342,8 @@
                     ],
                     "default": "none",
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap:core:v1"
                     ]
@@ -2314,6 +2354,8 @@
                     "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
                     "maxLength": 255,
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap.xref:customPolicy:v1"
                     ]
@@ -2335,6 +2377,8 @@
                     "type": "boolean",
                     "description": "Defines whether this ORD resource is **system-instance-aware**.\nThis is the case when the referenced resource definitions are potentially different between **system instances**.\n\nIf this behavior applies, `systemInstanceAware` MUST be set to true.\nAn ORD aggregator MUST then fetch the referenced resource definitions for _each_ **system instance** individually.\n\nThis concept is now **deprecated** in favor of the more explicit `perspective` attribute.\nAll resources that are system-instance-aware should ideally be put into a dedicated ORD document with `perspective`: `system-instance`.\n\nFor more details, see [perspectives concept page](../concepts/perspectives.md) or the [specification section](../index.md#perspectives).",
                     "default": false,
+                    "x-deprecated-in-version": "1.12.0",
+                    "x-deprecation-text": "Use `perspectives` instead (see [perspectives](../concepts/perspectives) article).",
                     "examples": [
                         true
                     ]
@@ -2497,41 +2541,46 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -2671,6 +2720,8 @@
                     ],
                     "default": "none",
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap:core:v1"
                     ]
@@ -2681,6 +2732,8 @@
                     "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
                     "maxLength": 255,
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap.xref:customPolicy:v1"
                     ]
@@ -2702,6 +2755,8 @@
                     "type": "boolean",
                     "description": "Defines whether this ORD resource is **system-instance-aware**.\nThis is the case when the referenced resource definitions are potentially different between **system instances**.\n\nIf this behavior applies, `systemInstanceAware` MUST be set to true.\nAn ORD aggregator MUST then fetch the referenced resource definitions for _each_ **system instance** individually.\n\nThis concept is now **deprecated** in favor of the more explicit `perspective` attribute.\nAll resources that are system-instance-aware should ideally be put into a dedicated ORD document with `perspective`: `system-instance`.\n\nFor more details, see [perspectives concept page](../concepts/perspectives.md) or the [specification section](../index.md#perspectives).",
                     "default": false,
+                    "x-deprecated-in-version": "1.12.0",
+                    "x-deprecation-text": "Use `perspectives` instead (see [perspectives](../concepts/perspectives) article).",
                     "examples": [
                         true
                     ]
@@ -2854,15 +2909,15 @@
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
@@ -2870,21 +2925,26 @@
                     "type": "string",
                     "description": "The `releaseStatus` specifies the stability towards incompatible changes in the future.\nIn the context of data products, it it covers only properties on the data product level.\nAPIs that are part of the input and output ports have their own independent `releaseStatus` and `version`.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -3382,6 +3442,8 @@
                     ],
                     "default": "none",
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap:core:v1"
                     ]
@@ -3393,6 +3455,8 @@
                     "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
                     "maxLength": 255,
                     "x-introduced-in-version": "1.3.0",
+                    "x-deprecation-text": "ORD now support multiple policy levels. Use `policyLevels` (plural) instead.",
+                    "x-deprecated-in-version": "1.9.9",
                     "examples": [
                         "sap.xref:customPolicy:v1"
                     ]
@@ -3415,6 +3479,8 @@
                     "type": "boolean",
                     "description": "Defines whether this ORD resource is **system-instance-aware**.\nThis is the case when the referenced resource definitions are potentially different between **system instances**.\n\nIf this behavior applies, `systemInstanceAware` MUST be set to true.\nAn ORD aggregator MUST then fetch the referenced resource definitions for _each_ **system instance** individually.\n\nThis concept is now **deprecated** in favor of the more explicit `perspective` attribute.\nAll resources that are system-instance-aware should ideally be put into a dedicated ORD document with `perspective`: `system-instance`.\n\nFor more details, see [perspectives concept page](../concepts/perspectives.md) or the [specification section](../index.md#perspectives).",
                     "default": false,
+                    "x-deprecated-in-version": "1.12.0",
+                    "x-deprecation-text": "Use `perspectives` instead (see [perspectives](../concepts/perspectives) article).",
                     "examples": [
                         true
                     ]
@@ -3580,27 +3646,11 @@
                 "mediaType": {
                     "description": "The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format.\nA consuming application can use this information to know which file format parser it needs to use.\nFor example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON.\n\nIf no Media Type is registered for the referenced file,\n`text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.\n",
                     "type": "string",
-                    "oneOf": [
-                        {
-                            "const": "application/json"
-                        },
-                        {
-                            "const": "application/xml"
-                        },
-                        {
-                            "const": "text/yaml"
-                        },
-                        {
-                            "const": "text/plain",
-                            "description": "For a plain-text format where no other serialization Media Type fits"
-                        },
-                        {
-                            "const": "application/octet-stream",
-                            "description": "For a binary format where no other serialization Media Type fits"
-                        }
-                    ],
+                    "pattern": "^(application|text)\\/[a-zA-Z0-9][a-zA-Z0-9.+\\-]*$",
                     "examples": [
-                        "application/json"
+                        "application/json",
+                        "text/plain",
+                        "application/xml"
                     ]
                 },
                 "url": {
@@ -3618,15 +3668,15 @@
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
@@ -3697,27 +3747,11 @@
                 "mediaType": {
                     "description": "The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format.\nA consuming application can use this information to know which file format parser it needs to use.\nFor example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON.\n\nIf no Media Type is registered for the referenced file,\n`text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.\n",
                     "type": "string",
-                    "oneOf": [
-                        {
-                            "const": "application/json"
-                        },
-                        {
-                            "const": "application/xml"
-                        },
-                        {
-                            "const": "text/yaml"
-                        },
-                        {
-                            "const": "text/plain",
-                            "description": "For a plain-text format where no other serialization Media Type fits"
-                        },
-                        {
-                            "const": "application/octet-stream",
-                            "description": "For a binary format where no other serialization Media Type fits"
-                        }
-                    ],
+                    "pattern": "^(application|text)\\/[a-zA-Z0-9][a-zA-Z0-9.+\\-]*$",
                     "examples": [
-                        "application/json"
+                        "application/json",
+                        "text/plain",
+                        "application/xml"
                     ]
                 },
                 "url": {
@@ -3749,15 +3783,15 @@
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 }
@@ -3831,10 +3865,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links.",
-                    "examples": [
-                        "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for\nin-memory computing, acts as a digital core, connecting your\nenterprise with people, business networks, the Internet of Things,\nBig Data, and more.\n"
-                    ]
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links."
                 },
                 "partOfPackage": {
                     "type": "string",
@@ -3879,41 +3910,46 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -4507,10 +4543,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links.",
-                    "examples": [
-                        "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for\nin-memory computing, acts as a digital core, connecting your\nenterprise with people, business networks, the Internet of Things,\nBig Data, and more.\n"
-                    ]
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links."
                 },
                 "partOfPackage": {
                     "type": "string",
@@ -4555,41 +4588,46 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -4627,6 +4665,54 @@
                         ]
                     ]
                 },
+                "relatedApiResources": {
+                    "type": "array",
+                    "x-introduced-in-version": "1.14.2",
+                    "description": "Optional list of related API Resources.\n\nUse this to indicate which APIs implement, expose, or are otherwise related to this capability.",
+                    "items": {
+                        "$ref": "#/definitions/RelatedApiResource"
+                    },
+                    "examples": [
+                        [
+                            {
+                                "ordId": "sap.s4:apiResource:API_BUSINESS_PARTNER:v1",
+                                "relationType": "foo.bar:relationName"
+                            }
+                        ]
+                    ]
+                },
+                "relatedEventResources": {
+                    "type": "array",
+                    "x-introduced-in-version": "1.14.2",
+                    "description": "Optional list of related Event Resources.\n\nUse this to indicate which events are emitted, consumed, or otherwise related to this capability.",
+                    "items": {
+                        "$ref": "#/definitions/RelatedEventResource"
+                    },
+                    "examples": [
+                        [
+                            {
+                                "ordId": "sap.s4:eventResource:BusinessPartnerEvents:v1",
+                                "relationType": "foo.bar:relationName"
+                            }
+                        ]
+                    ]
+                },
+                "relatedCapabilities": {
+                    "type": "array",
+                    "x-introduced-in-version": "1.14.2",
+                    "description": "Optional list of related Capabilities.\n\nUse this to indicate dependencies, extensions, or other relationships between capabilities.",
+                    "items": {
+                        "$ref": "#/definitions/RelatedCapability"
+                    },
+                    "examples": [
+                        [
+                            {
+                                "ordId": "sap.foo:capability:baseExtensibility:v1",
+                                "relationType": "foo.bar:relationName"
+                            }
+                        ]
+                    ]
+                },
                 "definitions": {
                     "type": "array",
                     "description": "List of available machine-readable definitions, which describe the resource or capability in detail.\nSee also [Resource Definitions](../index.md#resource-definitions) for more context.\n\nEach definition is to be understood as an alternative description format, describing the same resource / capability.\nAs a consequence the same definition type MUST NOT be provided more than once.\nThe exception is when the same definition type is provided more than once, but with a different `visibility`.\n\nIt is RECOMMENDED to provide the definitions as they enable machine-readable use cases.\nIf the definitions are added or changed, the `version` MUST be incremented.\nAn ORD aggregator MAY only (re)fetch the definitions again when the `version` was incremented.",
@@ -4666,6 +4752,8 @@
                     "type": "boolean",
                     "description": "Defines whether this ORD resource is **system-instance-aware**.\nThis is the case when the referenced resource definitions are potentially different between **system instances**.\n\nIf this behavior applies, `systemInstanceAware` MUST be set to true.\nAn ORD aggregator MUST then fetch the referenced resource definitions for _each_ **system instance** individually.\n\nThis concept is now **deprecated** in favor of the more explicit `perspective` attribute.\nAll resources that are system-instance-aware should ideally be put into a dedicated ORD document with `perspective`: `system-instance`.\n\nFor more details, see [perspectives concept page](../concepts/perspectives.md) or the [specification section](../index.md#perspectives).",
                     "default": false,
+                    "x-deprecated-in-version": "1.12.0",
+                    "x-deprecation-text": "Use `perspectives` instead (see [perspectives](../concepts/perspectives) article).",
                     "examples": [
                         true
                     ]
@@ -4726,27 +4814,11 @@
                 "mediaType": {
                     "description": "The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format.\nA consuming application can use this information to know which file format parser it needs to use.\nFor example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON.\n\nIf no Media Type is registered for the referenced file,\n`text/plain` MAY be used for arbitrary plain-text and `application/octet-stream` for arbitrary binary data.\n",
                     "type": "string",
-                    "oneOf": [
-                        {
-                            "const": "application/json"
-                        },
-                        {
-                            "const": "application/xml"
-                        },
-                        {
-                            "const": "text/yaml"
-                        },
-                        {
-                            "const": "text/plain",
-                            "description": "For a plain-text format where no other serialization Media Type fits"
-                        },
-                        {
-                            "const": "application/octet-stream",
-                            "description": "For a binary format where no other serialization Media Type fits"
-                        }
-                    ],
+                    "pattern": "^(application|text)\\/[a-zA-Z0-9][a-zA-Z0-9.+\\-]*$",
                     "examples": [
-                        "application/json"
+                        "application/json",
+                        "text/plain",
+                        "application/xml"
                     ]
                 },
                 "url": {
@@ -4778,15 +4850,15 @@
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 }
@@ -4859,10 +4931,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links.",
-                    "examples": [
-                        "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for\nin-memory computing, acts as a digital core, connecting your\nenterprise with people, business networks, the Internet of Things,\nBig Data, and more.\n"
-                    ]
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links."
                 },
                 "partOfPackage": {
                     "type": "string",
@@ -4907,41 +4976,46 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -5059,10 +5133,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links.",
-                    "examples": [
-                        "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for\nin-memory computing, acts as a digital core, connecting your\nenterprise with people, business networks, the Internet of Things,\nBig Data, and more.\n"
-                    ]
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links."
                 },
                 "mandatory": {
                     "type": "boolean",
@@ -5085,6 +5156,13 @@
                     "items": {
                         "$ref": "#/definitions/EventResourceIntegrationAspect"
                     }
+                },
+                "capabilities": {
+                    "type": "array",
+                    "description": "List of Capability Dependencies.",
+                    "items": {
+                        "$ref": "#/definitions/CapabilityIntegrationAspect"
+                    }
                 }
             },
             "additionalProperties": false,
@@ -5225,6 +5303,37 @@
                 "operationId"
             ]
         },
+        "CapabilityIntegrationAspect": {
+            "type": "object",
+            "title": "Capability Integration Aspect",
+            "x-introduced-in-version": "1.14.2",
+            "x-ums-type": "custom",
+            "description": "Capability related integration aspect",
+            "properties": {
+                "ordId": {
+                    "type": "string",
+                    "description": "The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.\n\nIt MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type.",
+                    "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(capability):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
+                    "maxLength": 255,
+                    "examples": [
+                        "sap.foo.bar:capability:fieldExtensibility:v1"
+                    ]
+                },
+                "minVersion": {
+                    "type": "string",
+                    "description": "Minimum version of the references resource that the integration requires.\n",
+                    "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
+                    "examples": [
+                        "1.2.3",
+                        "1.0.0-alpha.1"
+                    ]
+                }
+            },
+            "additionalProperties": false,
+            "required": [
+                "ordId"
+            ]
+        },
         "Vendor": {
             "type": "object",
             "title": "Vendor",
@@ -5311,23 +5420,28 @@
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [
@@ -5388,7 +5502,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown)",
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).",
                     "examples": [
                         "This gives you an overview on where to find which kind of APIs in SAP S/4HANA.\n"
                     ]
@@ -5406,6 +5520,62 @@
                 }
             ]
         },
+        "File": {
+            "type": "object",
+            "title": "File",
+            "x-introduced-in-version": "1.14.2",
+            "description": "File that can be attached on ORD package level.\n",
+            "x-ums-type": "custom",
+            "properties": {
+                "title": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Human readable title of the file.\n\nMUST be unique within the collection of files provided.",
+                    "examples": [
+                        "Developer Guide for SAP Ariba Portal"
+                    ]
+                },
+                "url": {
+                    "type": "string",
+                    "format": "uri-reference",
+                    "description": "[URL](https://tools.ietf.org/html/rfc3986) of the link.\n\nThe file target MAY be relative or absolute.\nIf a relative URL is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl).\nIf an absolute URL is given, then it MUST be openly accessible.",
+                    "examples": [
+                        "/ord/v1/Ariba/Files/DeveloperPortal/SAP-Ariba-developer-portal.pdf"
+                    ]
+                },
+                "description": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links.",
+                    "examples": [
+                        "Includes administrator, quick start, and authentication guides.\n"
+                    ]
+                },
+                "mediaType": {
+                    "description": "The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format.\nA consuming application can use this information to know which file format parser it needs to use.\n\nIf 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.\n",
+                    "type": "string",
+                    "pattern": "^(application|text)\\/[a-zA-Z0-9][a-zA-Z0-9.+\\-]*$",
+                    "examples": [
+                        "application/json",
+                        "text/plain",
+                        "application/xml"
+                    ]
+                }
+            },
+            "required": [
+                "title",
+                "url",
+                "mediaType"
+            ],
+            "examples": [
+                {
+                    "url": "/ord/v1/Ariba/Files/DeveloperPortal/SAP-Ariba-developer-portal.pdf",
+                    "title": "Developer Guide for SAP Ariba Portal",
+                    "description": "Includes administrator, quick start, and authentication guides.",
+                    "mediaType": "application/pdf"
+                }
+            ]
+        },
         "PackageLink": {
             "type": "object",
             "title": "Package Link",
@@ -5983,10 +6153,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links.",
-                    "examples": [
-                        "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for\nin-memory computing, acts as a digital core, connecting your\nenterprise with people, business networks, the Internet of Things,\nBig Data, and more.\n"
-                    ]
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links."
                 },
                 "labels": {
                     "$ref": "#/definitions/Labels"
@@ -6068,10 +6235,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links.",
-                    "examples": [
-                        "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for\nin-memory computing, acts as a digital core, connecting your\nenterprise with people, business networks, the Internet of Things,\nBig Data, and more.\n"
-                    ]
+                    "description": "Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description SHOULD not be excessive in length and is not meant to provide full documentation.\nDetailed documentation SHOULD be attached as (typed) links."
                 },
                 "labels": {
                     "$ref": "#/definitions/Labels"
@@ -6179,6 +6343,8 @@
             "title": "Entity Type Mapping",
             "type": "object",
             "x-introduced-in-version": "1.6.0",
+            "x-deprecated-in-version": "1.11.0",
+            "x-deprecation-text": "Use the simplified `relatedEntityTypes` instead.",
             "x-ums-type": "custom",
             "description": "An API or Event resource may optionally define its `entityTypeMappings`.\nThis is used to map and correlate the API models to the underlying, conceptual **entity types**.\n\nIf the mapping from API resource to entity types is not defined,\ncertain use-cases that rely on this explicit connection will not be possible.\n\nThis mapping is meant to be rather fine granular.\nTherefore, the mapping needs to be done on basis of one of the referenced resource definitions,\nas only there we know the details and the actual contents of the API Model of the API resource.\n\nFor the various resource definition formats the selection of API models may need to be expressed differently.\nAs a consequence, there are different types of selectors that are specialized toward certain resource definition formats.\n\nThe target of the mapping is a correlation to an entity type via a [Correlation ID](../index.md#correlation-id)\nor to an [ORD ID](../index.md#ord-id) of an entity type.\nIt is assumed that the entity types are described in more detail or on a different abstraction level via metadata.\nWhen the correlation ID is used, an ORD consumer may need to know how to access the entity type metadata through conventions.\nThis can be determined either by the namespace of the correlation ID,\nor through a defined and known `implementationStandard` that can resolve the `localId` fragment of the correlation ID .\n\nAt SAP, the metadata about entity types could be retrieved via the CSN_EXPOSURE service.\nTo indicate this, the service needs to be implemented and described in ORD with `implementationStandard` set to `sap:csn-exposure:v1`).\n\nODM 2.0 relies on the entity type mappings and uses the the mapping to express the relationship of an API to the\ncorresponding ODM entity. ORD consumers like SAP Business Accelerator Hub consume the mapping to make the relationships navigate-able for customers.",
             "properties": {
@@ -6284,6 +6450,8 @@
         "ApiModelSelectorOData": {
             "title": "Api Model Selector (Odata)",
             "x-introduced-in-version": "1.6.0",
+            "x-deprecated-in-version": "1.11.0",
+            "x-deprecation-text": "Use the simplified `relatedEntityTypes` instead.\n\nFor creating a mapping from API model to Entity Types, consider using the [Entity Relationship](https://sap.github.io/csn-interop-specification/annotations/entity-relationship) annotations.",
             "x-ums-type": "custom",
             "type": "object",
             "description": "API Model Selector for OData, using entity set names for the selection.\n\nMUST only be used if the API Resource provides an API Resource Definition of type `edmx`.",
@@ -6319,6 +6487,8 @@
         "ApiModelSelectorJsonPointer": {
             "title": "Api Model Selector (Json Pointer)",
             "x-introduced-in-version": "1.6.0",
+            "x-deprecated-in-version": "1.11.0",
+            "x-deprecation-text": "Use the simplified `relatedEntityTypes` instead.\n\nFor creating a mapping from API model to Entity Types, consider using the [Entity Relationship](https://sap.github.io/csn-interop-specification/annotations/entity-relationship) annotations.",
             "x-ums-type": "custom",
             "type": "object",
             "description": "Generic API Model Selector for JSON / YAML based resource definitions.\nIt uses a [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) that points to the\nentity type description within the resource definition.\n\nThe JSON Pointer always to refer to the structure of the document as originally provided, before further post-processing like resolving $ref properties.\n\nMUST only be used if the API Resource provides an API Resource Definition of media type `application/json` or `text/yaml`.",
@@ -6381,6 +6551,8 @@
         "EntityTypeOrdIdTarget": {
             "title": "Entity Type Target (ORD ID)",
             "x-introduced-in-version": "1.6.0",
+            "x-deprecated-in-version": "1.11.0",
+            "x-deprecation-text": "Use the simplified `relatedEntityTypes` instead.",
             "x-ums-type": "custom",
             "type": "object",
             "description": "Define which entity type is the target of an entity type mapping\n\nEntity types can be referenced using a [ORD ID](../index.md#ord-id) of an entity type.",
@@ -6408,6 +6580,8 @@
             "type": "object",
             "description": "Define which entity type is the target of an entity type mapping\n\nEntity types can be referenced using a [Correlation ID](../index.md#correlation-id).",
             "x-introduced-in-version": "1.6.0",
+            "x-deprecated-in-version": "1.11.0",
+            "x-deprecation-text": "Use the simplified `relatedEntityTypes` instead.",
             "x-ums-type": "custom",
             "properties": {
                 "correlationId": {
@@ -6445,10 +6619,15 @@
                 },
                 "relationType": {
                     "type": "string",
-                    "description": "Optional type of the relationship, which defines a stricter semantic what the relationship implies.\n\nIf not provided, the relationship type has no semantics, it's \"related somehow\".",
+                    "description": "Optional type of the relationship, which defines a stricter semantic what the relationship implies.\n\nIf not provided, the relationship type has no semantics, it's \"related somehow\".\n\nMUST be a valid [Concept ID](../index.md#concept-id).",
                     "x-introduced-in-version": "1.12.0",
                     "x-feature-status": "beta",
-                    "oneOf": [
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$",
+                            "description": "Any valid [Concept ID](../index.md#concept-id)."
+                        },
                         {
                             "const": "part-of",
                             "description": "The described entity type is a composite part of the referenced entity type.\nE.g. a `SalesOrderItem` is part of a `SalesOrder`."
@@ -6459,7 +6638,125 @@
                         }
                     ],
                     "examples": [
-                        "can-share-identity"
+                        "can-share-identity",
+                        "foo.bar:relationName"
+                    ]
+                }
+            },
+            "required": [
+                "ordId"
+            ],
+            "additionalProperties": false
+        },
+        "RelatedApiResource": {
+            "title": "Related API Resource",
+            "x-introduced-in-version": "1.14.2",
+            "x-ums-type": "embedded",
+            "type": "object",
+            "description": "Defines a relation to an API Resource (via its ORD ID).",
+            "properties": {
+                "ordId": {
+                    "type": "string",
+                    "description": "The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.\n\nIt MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type.",
+                    "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
+                    "maxLength": 255,
+                    "examples": [
+                        "sap.s4:apiResource:API_BUSINESS_PARTNER:v1"
+                    ],
+                    "x-association-target": [
+                        "#/definitions/ApiResource/ordId"
+                    ]
+                },
+                "relationType": {
+                    "type": "string",
+                    "description": "Optional type of the relationship as a [Concept ID](../index.md#concept-id).\n\nDefines the semantic meaning of the relationship.\nIf not provided, the relationship has no specific semantics (\"related somehow\").",
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$",
+                            "description": "Any valid [Concept ID](../index.md#concept-id)."
+                        }
+                    ],
+                    "examples": [
+                        "foo.bar:relationName"
+                    ]
+                }
+            },
+            "required": [
+                "ordId"
+            ],
+            "additionalProperties": false
+        },
+        "RelatedEventResource": {
+            "title": "Related Event Resource",
+            "x-introduced-in-version": "1.14.2",
+            "x-ums-type": "embedded",
+            "type": "object",
+            "description": "Defines a relation to an Event Resource (via its ORD ID).",
+            "properties": {
+                "ordId": {
+                    "type": "string",
+                    "description": "The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.\n\nIt MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type.",
+                    "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
+                    "maxLength": 255,
+                    "examples": [
+                        "sap.s4:eventResource:BusinessPartnerEvents:v1"
+                    ],
+                    "x-association-target": [
+                        "#/definitions/EventResource/ordId"
+                    ]
+                },
+                "relationType": {
+                    "type": "string",
+                    "description": "Optional type of the relationship as a [Concept ID](../index.md#concept-id).\n\nDefines the semantic meaning of the relationship.\nIf not provided, the relationship has no specific semantics (\"related somehow\").",
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$",
+                            "description": "Any valid [Concept ID](../index.md#concept-id)."
+                        }
+                    ],
+                    "examples": [
+                        "foo.bar:relationName"
+                    ]
+                }
+            },
+            "required": [
+                "ordId"
+            ],
+            "additionalProperties": false
+        },
+        "RelatedCapability": {
+            "title": "Related Capability",
+            "x-introduced-in-version": "1.14.2",
+            "x-ums-type": "embedded",
+            "type": "object",
+            "description": "Defines a relation to another Capability (via its ORD ID).",
+            "properties": {
+                "ordId": {
+                    "type": "string",
+                    "description": "The ORD ID is a stable, globally unique ID for ORD resources or taxonomy.\n\nIt MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type.",
+                    "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(capability):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
+                    "maxLength": 255,
+                    "examples": [
+                        "sap.foo:capability:fieldExtensibility:v1"
+                    ],
+                    "x-association-target": [
+                        "#/definitions/Capability/ordId"
+                    ]
+                },
+                "relationType": {
+                    "type": "string",
+                    "description": "Optional type of the relationship as a [Concept ID](../index.md#concept-id).\n\nDefines the semantic meaning of the relationship.\nIf not provided, the relationship has no specific semantics (\"related somehow\").",
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$",
+                            "description": "Any valid [Concept ID](../index.md#concept-id)."
+                        }
+                    ],
+                    "examples": [
+                        "foo.bar:relationName"
                     ]
                 }
             },
@@ -6555,10 +6852,7 @@
                 "description": {
                     "type": "string",
                     "minLength": 1,
-                    "description": "Optional description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description of a Tombstone MAY be added to the changelog of the removed resource by an ORD aggregator.",
-                    "examples": [
-                        "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for\nin-memory computing, acts as a digital core, connecting your\nenterprise with people, business networks, the Internet of Things,\nBig Data, and more.\n"
-                    ]
+                    "description": "Optional description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThe description of a Tombstone MAY be added to the changelog of the removed resource by an ORD aggregator."
                 }
             },
             "required": [
@@ -6667,41 +6961,46 @@
                 },
                 "visibility": {
                     "type": "string",
-                    "description": "The visibility states who is allowed to \"see\" the described resource or capability.",
+                    "description": "Defines metadata access control - which categories of consumers are allowed to discover and access the resource and its metadata.\n\nThis controls who can see that the resource exists and retrieve its metadata level information.\nIt does NOT control runtime access to the resource itself - that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal implementation details to inappropriate consumer audiences.",
                     "oneOf": [
                         {
                             "const": "public",
-                            "description": "Publicly visible to customers and 3rd parties.\nUsually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html)."
+                            "description": "Metadata can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties.\n\nPublic resources typically come with stability guarantees, expressed via versioning and follow formal API lifecycle management. For more details see [Version and Lifecycle](../index.md#version-and-lifecycle) section.\nand follow formal API lifecycle management and deprecation policies.\n\nExample: A REST API that customers use to integrate with your SaaS product."
                         },
                         {
                             "const": "internal",
-                            "description": "Visible to other applications within the same [vendor](#vendor).\nHowever, they are not officially exposed and communicated to customers and 3rd parties.\nThey might not come with the same guarantees on API stability.\n\nInternal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog.\nInternal resources MAY be published through an internal API Catalog if the access permissions are ensured by it."
+                            "description": "Metadata can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers.\n\nInternal resources are intended for integration between a vendors own applications and services.\nAPI stability and maturity are explicitly defined via the `releaseStatus` property, which is a separate concern from visibility.\n\nInternal resources MUST NOT be made available without checking the necessary access permissions.\nInternal resources MAY be published through an internal API Catalog if access permissions are ensured by it."
                         },
                         {
                             "const": "private",
-                            "description": "Visible only to the provider application or service, usually within the same system namespace / system type.\n\nPrivate resources MUST NOT be made available to public consumers or consumers outside of the \"private\" scope of the described application."
+                            "description": "Metadata should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type).\nUsed for metadata completeness when describing implementation details or dependencies.\n\nPrivate resources usually have no stability guarantees and can change or be removed at any time.\nThese are typically implementation details not meant for consumption by other services.\n\nExample: Services only used within a microservice architecture or APIs that are only used for the own UIs, not for general consumption.\n\nPrivate resources MUST NOT be made discoverable or accessible outside the application / service's own deployment scope."
                         }
                     ]
                 },
                 "releaseStatus": {
                     "type": "string",
-                    "description": "The `releaseStatus` specifies the stability of the resource and its external contract.",
+                    "description": "Defines the maturity level and stability commitment for the resource's API contract (interface, behavior, data models).\n\nThis indicates whether the resource may undergo backward-incompatible changes. It helps consumers understand the risk\nof depending on the resource and whether it's suitable for production use.\n\nNote: This is independent of `visibility` and does not imply availability guarantees or SLAs - it concerns only the API contract stability.\n\nSee [Lifecycle](../index.md#lifecycle) and [Compatibility](../concepts/compatibility.md) for more details.",
                     "oneOf": [
+                        {
+                            "const": "development",
+                            "x-introduced-in-version": "1.14.2",
+                            "description": "The resource is unreleased and under active development. The API contract is unstable and subject to\nbreaking changes at any time. Not intended for consumption outside of the development team."
+                        },
                         {
                             "const": "beta",
-                            "description": "The contract for the resource is beta and may not be meant for productive use.\nResources of `beta` status MAY be changed or deleted at the providers discretion."
+                            "description": "The API contract is released / available to consumers, but has no final stability guarantees.\nBreaking changes may occur at any time without notice or deprecation period.\n\nNot recommended for production use unless you can tolerate breaking changes. Suitable for experimentation, early adopters,\nand feedback gathering. Resources of `beta` status MAY be changed or removed at the provider's discretion."
                         },
                         {
                             "const": "active",
-                            "description": "Resource is meant for productive use and provides a stable API contract."
+                            "description": "The API contract is stable and recommended for production use.\n\nBreaking changes will only be introduced through proper deprecation cycles or new major versions,\nfollowing versioning and compatibility policies. Consumers can rely on active resources with confidence."
                         },
                         {
                             "const": "deprecated",
-                            "description": "Resource has been deprecated.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
+                            "description": "The resource is still functional but scheduled for removal. No new development should depend on it.\n\nIf the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided.\n\nIf successor resources exist, they MUST be referenced through `successors`.\n\nA deprecated resource MAY be sunset (decommissioned/removed) in the future through setting a `Tombstone`.\nOnce the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`."
                         },
                         {
                             "const": "sunset",
-                            "description": "Resource has been sunset, but is still described.\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
+                            "description": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided."
                         }
                     ],
                     "examples": [