{ "description": "The [ORD Document](../index.md#ord-document) object serves as a wrapper for the **ORD resources** and **ORD taxonomy** and adds further top-level information\nthat is specific to the document/the service it describes.\n\nThe constraints and considerations on [ORD Documents](../index.md#ord-document) MUST be followed.\n\nThis JSON Schema describes the [ORD document interface](https://open-resource-discovery.org/spec-v1/interfaces/Document) of the [ORD specification](https://open-resource-discovery.org/).", "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://open-resource-discovery.org/spec-v1/interfaces/Document.schema.json#", "title": "Ord Document", "x-ums-type": "ignore", "type": "object", "properties": { "$schema": { "type": "string", "format": "uri-reference", "description": "Optional [URL](https://tools.ietf.org/html/rfc3986) to the Open Resource Discovery document schema (defined as a JSON Schema).\nIf provided, this enables code intelligence and validation in supported editors (like VSCode) and tools.", "anyOf": [ { "type": "string", "format": "uri-reference" }, { "const": "https://open-resource-discovery.org/spec-v1/interfaces/Document.schema.json#" } ] }, "openResourceDiscovery": { "type": "string", "description": "Version of the Open Resource Discovery specification that is used to describe this document.", "enum": [ "1.0", "1.1", "1.2", "1.3", "1.4", "1.5", "1.6", "1.7", "1.8", "1.9", "1.10", "1.11", "1.12", "1.13", "1.14" ], "examples": [ "1.14" ] }, "description": { "type": "string", "minLength": 1, "description": "Optional description of the ORD document itself.\nPlease note that this information is NOT further processed or considered by an ORD aggregator.\n\nNotated in [CommonMark](https://spec.commonmark.org/) (Markdown).", "examples": [ "This ORD document contains all APIs that are system-instance-aware and have APIs that\ncan change their behavior at runtime.\n" ] }, "perspective": { "type": "string", "x-introduced-in-version": "1.12.0", "x-feature-status": "beta", "description": "With ORD it's possible to describe a system from a static or a dynamic [perspective](../index.md#perspectives) (for more details, follow the link).\n\nIt is strongly RECOMMENDED to mark all static ORD documents with perspective `system-version`.\n\nIt is RECOMMENDED to describe dynamic metadata in both static system-version perspective and additionally describe the system-instance perspective where it diverges from the static metadata.\n\nIf not provided, this defaults to `system-instance`, which is the most precise description but also the most costly to replicate.\n\nPlease read the [article on perspectives](../concepts/perspectives) for more explanations.", "oneOf": [ { "const": "system-type", "description": "Describes a static [system-type](../index.md#def-system-type) perspective, which is version independent.\n\nIf a system is not versioned (continuous delivery) or resources are not tied to a system, the system-type perspective\nimplies that the information apply, no matter which system version or instance." }, { "const": "system-version", "description": "Describes the static [system-version](../index.md#system-version) perspective, usually known at deploy-time.\n\nIf chosen, `describedSystemVersion`.`version` MUST be provided, too.\n\nThis perspective describes how a system of a particular type and version generally look like.\nThe latest system-version MAY also be interpreted as the [system-type](../index.md#system-type) perspective." }, { "const": "system-instance", "description": "Describes the complete dynamic [system-instance](../index.md#system-instance) (tenant) perspective as known at run-time.\nThis allows to also reflect tenant specific extensions, customizations and runtime configuration.\n\nIf provided, it will completely override the static system-version perspective when metadata about system instances is requested." }, { "const": "system-independent", "description": "Describes content that is independent of [system-versions](../index.md#system-version) or [system-instances](../index.md#system-instance).\nThis content is always static and has independent visibility and lifecycle from the systems in a particular landscape.\nThe \"system-independent\" content MUST NOT be overridden via system-version or system-instance perspective metadata.\n\nExamples are: Vendors, products, globally aligned entity types, groups and group types (taxonomy), which are usually shared by multiple systems." } ], "default": "system-instance", "examples": [ "system-instance" ] }, "describedSystemInstance": { "$ref": "#/definitions/SystemInstance", "description": "Information on the [system-instance](../index.md#system-instance) that this ORD document describes.\n\nWhether this information is required or recommended to add, depends on the requirements of the ORD aggregator." }, "describedSystemType": { "$ref": "#/definitions/SystemType", "x-introduced-in-version": "1.10.0", "description": "Information on the [system type](../index.md#system-type) that this ORD document describes." }, "describedSystemVersion": { "$ref": "#/definitions/SystemVersion", "x-introduced-in-version": "1.10.0", "description": "Information on the [system version](../index.md#system-version) that this ORD document describes." }, "policyLevel": { "type": "string", "description": "The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with.\nDepending on the chosen policy level, additional expectations and validations rules will be applied.\n\nThe policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "none", "description": "No policy level chosen. Only the base rules on how to create correct ORD documents apply." }, { "const": "custom", "description": "Custom policy level.\nFurther validation MAY be defined and implemented by the policy-level owner.\nThis level MAY be chosen by 3rd party or customer solutions.\nIf chosen, `customPolicyLevel` MUST be provided." } ], "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" ] }, "customPolicyLevel": { "type": "string", "description": "If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.\nThe policy level is inherited from packages to resources they contain, but can be overwritten at resource level.\n\nMUST only be provided if `policyLevel` is set to `custom`.\nMUST be a valid [Specification ID](../index.md#specification-id).", "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" ] }, "policyLevels": { "type": "array", "description": "A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with.\nFor each chosen policy level, additional expectations and validations rules will be applied.\n\nPolicy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n\nA policy level MUST be a valid [Specification ID](../index.md#specification-id).", "x-introduced-in-version": "1.9.9", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:core:v1" ] } }, "apiResources": { "type": "array", "description": "Array of all API Resources that are described in this ORD document.", "items": { "$ref": "#/definitions/ApiResource" } }, "eventResources": { "type": "array", "description": "Array of all event resources that are described in this ORD document.", "items": { "$ref": "#/definitions/EventResource" } }, "entityTypes": { "type": "array", "description": "Array of all entity types that are described in this ORD document.", "x-introduced-in-version": "1.6.0", "items": { "$ref": "#/definitions/EntityType" } }, "capabilities": { "type": "array", "description": "Array of all capabilities that are described in this ORD document.", "x-introduced-in-version": "1.4.0", "items": { "$ref": "#/definitions/Capability" } }, "dataProducts": { "type": "array", "description": "Array of all data products that are described in this ORD document.", "x-introduced-in-version": "1.8.0", "items": { "$ref": "#/definitions/DataProduct" } }, "agents": { "type": "array", "description": "Array of all AI Agents that are described in this ORD document.", "x-introduced-in-version": "1.14.0", "x-feature-status": "beta", "items": { "$ref": "#/definitions/Agent" } }, "integrationDependencies": { "type": "array", "description": "Array of all integration dependencies that are described in this ORD document.", "x-introduced-in-version": "1.7.0", "items": { "$ref": "#/definitions/IntegrationDependency" } }, "vendors": { "type": "array", "description": "Array of all Vendors that are described in this ORD document.", "items": { "$ref": "#/definitions/Vendor" } }, "products": { "type": "array", "description": "Array of all Products that are described in this ORD document.", "items": { "$ref": "#/definitions/Product" } }, "packages": { "type": "array", "description": "Array of all Packages that are described in this ORD document.", "items": { "$ref": "#/definitions/Package" } }, "consumptionBundles": { "type": "array", "description": "Array of all Consumption Bundles that are described in this ORD document.", "items": { "$ref": "#/definitions/ConsumptionBundle" } }, "groups": { "type": "array", "description": "Array of all Groups that are described in this ORD document.", "x-introduced-in-version": "1.9.0", "items": { "$ref": "#/definitions/Group" } }, "groupTypes": { "type": "array", "description": "Array of all Group Types that are described in this ORD document.", "x-introduced-in-version": "1.9.0", "items": { "$ref": "#/definitions/GroupType" } }, "tombstones": { "type": "array", "description": "List of ORD information (resources or taxonomy) that have been \"tombstoned\", indicating removal or archival.\nThis MUST be indicated explicitly, just removing the ORD information itself is not sufficient.\n\nA tombstone entry MAY be removed after a grace period of 31 days.", "items": { "$ref": "#/definitions/Tombstone" } } }, "additionalProperties": false, "required": [ "openResourceDiscovery" ], "x-recommended": [ "policyLevels" ], "definitions": { "Package": { "type": "object", "title": "Package", "x-ums-type": "root", "description": "A [**Package**](../concepts/grouping-and-bundling#package) organizes a set of related resources together, by publishing and catalog presentation concerns.\n\nThe Package can also be used to indicate which products or vendors provided the packaged resources.\nFor partner or customer content, the Package can indicate this via the `vendor` and `partOfProducts` assignments.\nIn any case, the Package `ordID` namespace MUST reflect the namespace of the providing application (which hosts the resource), not the resource definition owner, which could be a customer or partner.\n\nA Package SHOULD contain at least one resource. Avoid empty Packages.\n\nThe Package assignment of a resource MAY change, so consumers MUST not rely on this to be stable.\n\nA Package does not have a `visibility` property.\nWhether it is displayed is decided by the fact, whether it contains any visible resources according to the visibility role of the aggregator.\n\nTo learn more about the concept and further guidance, see [Package](../concepts/grouping-and-bundling#package).", "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]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.xref:package:SomePackage:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "SuccessFactorsRecruiting", "91cd9972-c05d-4d29-8b6e-dbef2a2d48e9" ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing." ] }, "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" ] }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "policyLevel": { "type": "string", "description": "The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with.\nDepending on the chosen policy level, additional expectations and validations rules will be applied.\n\nThe policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "none", "description": "No policy level chosen. Only the base rules on how to create correct ORD documents apply." }, { "const": "custom", "description": "Custom policy level.\nFurther validation MAY be defined and implemented by the policy-level owner.\nThis level MAY be chosen by 3rd party or customer solutions.\nIf chosen, `customPolicyLevel` MUST be provided." } ], "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" ] }, "customPolicyLevel": { "type": "string", "description": "If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.\nThe policy level is inherited from packages to resources they contain, but can be overwritten at resource level.\n\nMUST only be provided if `policyLevel` is set to `custom`.\nMUST be a valid [Specification ID](../index.md#specification-id).", "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" ] }, "policyLevels": { "type": "array", "description": "A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with.\nFor each chosen policy level, additional expectations and validations rules will be applied.\n\nPolicy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n\nA policy level MUST be a valid [Specification ID](../index.md#specification-id).", "x-introduced-in-version": "1.9.9", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:core:v1" ] } }, "packageLinks": { "type": "array", "description": "Links with semantic meaning that are specific to Packages.", "items": { "$ref": "#/definitions/PackageLink" } }, "links": { "type": "array", "description": "Generic links with arbitrary meaning and content.\n\n`packageLinks` MUST be preferred if applicable.", "items": { "$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, "description": "Standardized identifier for the license.\nIt MUST conform to the [SPDX License List](https://spdx.org/licenses)." }, "supportInfo": { "type": "string", "minLength": 1, "description": "Optional information that should be provided when creating a support ticket for the resources bundled in this Package.\nThis can for example be a \"component\" name that needs to be chosen in the support portal.\n\nNotated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nPlease also note that if you want to provide link(s) where you can find support information,\nyou can use `packageLinks` with a link of type `support`.", "x-introduced-in-version": "1.1.0" }, "vendor": { "type": "string", "description": "Vendor / organization that is the creator (or responsible party) of the resources that are part of the `Package`.\n\nMUST be a valid reference to a [Vendor](#vendor) ORD ID.\n\nMUST be set to `customer:vendor:Customer:` if the contents of the Package are created by the customer / user.\n\nMUST be set to a registered partner vendor, if the contents of the Package are created by a partner / third party.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\\-]+):()$", "maxLength": 256, "x-association-target": [ "#/definitions/Vendor/ordId" ], "examples": [ "sap:vendor:SAP:", "customer:vendor:Customer:", "microsoft:vendor:Microsoft:" ] }, "partOfProducts": { "type": "array", "description": "List of products the resources of the Package are a part of.\n\nMUST be a valid reference to a [Product](#product) ORD ID.\n\n`partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "x-association-target": [ "#/definitions/Product/ordId" ] }, "minItems": 0, "examples": [ [ "sap:product:S4HANA_OD:" ] ] }, "countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "List of countries that the Package resources are applicable to.\n\nMUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n`countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "DE", "US" ] ] }, "lineOfBusiness": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Asset Management" }, { "const": "Commerce" }, { "const": "Finance" }, { "const": "Human Resources" }, { "const": "Manufacturing" }, { "const": "Marketing" }, { "const": "R&D Engineering" }, { "const": "Sales" }, { "const": "Service" }, { "const": "Sourcing and Procurement" }, { "const": "Strategy, Compliance, and Governance" }, { "const": "Supply Chain" }, { "const": "Sustainability" }, { "const": "Metering" }, { "const": "Grid Operations and Maintenance" }, { "const": "Plant Operations and Maintenance" }, { "const": "Maintenance and Engineering" } ] }, "description": "List of line of business tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Sales" ] ] }, "industry": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Aerospace and Defense" }, { "const": "Agribusiness" }, { "const": "Automotive" }, { "const": "Banking" }, { "const": "Chemicals" }, { "const": "Consumer Industries" }, { "const": "Consumer Products" }, { "const": "Defense and Security" }, { "const": "Discrete Industries" }, { "const": "Energy and Natural Resources" }, { "const": "Engineering Construction and Operations" }, { "const": "Financial Services" }, { "const": "Future Cities" }, { "const": "Healthcare" }, { "const": "High Tech" }, { "const": "Higher Education and Research" }, { "const": "Industrial Machinery and Components" }, { "const": "Insurance" }, { "const": "Life Sciences" }, { "const": "Media" }, { "const": "Mill Products" }, { "const": "Mining" }, { "const": "Oil and Gas" }, { "const": "Professional Services" }, { "const": "Public Sector" }, { "const": "Public Services" }, { "const": "Retail" }, { "const": "Service Industries" }, { "const": "Sports and Entertainment" }, { "const": "Telecommunications" }, { "const": "Travel and Transportation" }, { "const": "Utilities" }, { "const": "Wholesale Distribution" } ] }, "description": "List of industry tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Automotive" ], [ "Retail", "Public Sector" ], [] ] }, "runtimeRestriction": { "x-introduced-in-version": "1.8.0", "x-feature-status": "alpha", "description": "If provided, all resources that are part of this Package can only run on the listed runtime.\n\nMUST be a valid [system namespace](../index.md#system-namespace).", "type": "string", "pattern": "^[a-z0-9]+(?:[.][a-z0-9]+){1}$", "examples": [ "sap.datasphere" ] }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" } }, "required": [ "ordId", "title", "shortDescription", "description", "version", "vendor" ], "additionalProperties": false }, "ConsumptionBundle": { "type": "object", "title": "Consumption Bundle", "x-ums-type": "root", "description": "A [**Consumption Bundle**](../concepts/grouping-and-bundling#consumption-bundle) groups APIs and Events together that can be consumed with the same credentials and auth mechanism.\nIdeally it also includes instructions and details on how to request access and credentials for resources.\n\nFor more documentation and guidance on how to use this correctly, see [Consumption Bundle](../concepts/grouping-and-bundling#consumption-bundle).\n\nA Consumption Bundle SHOULD have at least one association with a resource (0..n). Avoid empty Consumption Bundles.\nA Consumption Bundle MUST NOT contain APIs and Events that are NOT defined in the ORD document(s) returned\nby the system instance that defines the Consumption Bundle.\n\nPlease note that some ORD consumer use cases MAY depend on Consumption Bundle assignments to work with the resources.\n\nTo learn more about the concept, see [Consumption Bundle](../concepts/grouping-and-bundling#consumption-bundle).", "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]+)*):(consumptionBundle):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.xref:consumptionBundle:bundleXYZ:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "SuccessFactorsRecruiting", "91cd9972-c05d-4d29-8b6e-dbef2a2d48e9" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:communicationScenario:SAP_COM_0008" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP LoB System 3 Cloud Consumption Bundle 1" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP LoB System 3 Cloud, cloud ERP suite designed for in-memory computing" ] }, "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": [ "This Consumption Bundle includes all SAP LoB System 3 Cloud APIs and Events\nthat can be consumed with the same credentials.\n" ] }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ], "x-introduced-in-version": "1.2.1" }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "visibility": { "type": "string", "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": "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": "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": "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." } ] }, "credentialExchangeStrategies": { "type": "array", "x-feature-status": "alpha", "description": "Defines the supported strategies for how the consumption credentials can be exchanged.\n\nIdeally, the system type supports a strategy that can automate the exchange.", "items": { "$ref": "#/definitions/CredentialExchangeStrategy" } }, "links": { "type": "array", "description": "Generic links with arbitrary meaning and content.", "items": { "$ref": "#/definitions/Link" } }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" } }, "required": [ "ordId", "title" ], "x-recommended": [ "lastUpdate", "version" ], "additionalProperties": false }, "ConsumptionBundleReference": { "type": "object", "title": "Consumption Bundle Reference", "x-ums-type": "embedded", "description": "Reference to a Consumption Bundle.\n\nThis is a complex object to allow additional properties / selections to be attached.", "properties": { "ordId": { "type": "string", "description": "The Consumption Bundle ORD ID (`ConsumptionBundle.ordId`) this reference points to.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "x-association-target": [ "#/definitions/ConsumptionBundle/ordId" ], "examples": [ "sap.xref:consumptionBundle:bundleXYZ:v1" ] }, "defaultEntryPoint": { "type": "string", "format": "uri-reference", "description": "In case that an API Resource has multiple entry points, this will indicate which entry point should be used by default\nwhen discovering this resource from the context of the referenced Consumption Bundle.\n\nMUST NOT be provided for Event Resources, as they don't have entry points.\nMUST only be provided if the resource has more than one entry point.\nMUST be in the list of `entryPoints` of the affected resource." } }, "required": [ "ordId" ], "additionalProperties": false }, "ApiResource": { "type": "object", "title": "Api Resource", "x-ums-type": "root", "description": "The API Resource provides a high-level description of an exposed API.\nYou can find more information, such as the API resource definitions, in the links in the table below.\n\nAn API Resource bundles multiple endpoints and resources together.\nThey share the same API namespace and lifecycle (API major version).\nHowever, the exact granularity of this is up to the implementer of the API.\nAs a consequence, an API resource MUST NOT bundle together endpoints from different API versions or namespaces.\n\nA common practice is to bundle endpoints that are based on the same domain or Business Object.\n\nPlease note that APIs can be described, but still be [`disabled`](#api-resource_disabled).\n\nIf the API is not created or owned by the user of the system or by third parties (like partners), it MUST be assigned to dedicated [Packages](#package) that state this the ownership via the `vendor` property.", "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_BILL_OF_MATERIAL_SRV:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "API_BILL_OF_MATERIAL_SRV" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.xref:csnService:SomeLocalID" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "Process Request for Quotation" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "This service enables you to create Request for Quotation (RFQ) through an API call." ] }, "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": [ "This service enables you to create Request for Quotation (RFQ)\nthrough an API call from a source system outside SAP S/4HANA Cloud\nor SAP S/4HANA on-Premise. Furthermore, the service enables you to\nread existing Request for Quotation data from the SAP S/4HANA Cloud\nor SAP S/4HANA on-Premise.\n" ] }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [ "sap.xref:package:SomePackage:v1" ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together." }, "partOfConsumptionBundles": { "type": "array", "description": "List of references to the Consumption Bundles in this resource belongs to.\n\nMUST be a valid reference to a [Consumption Bundle](#consumption-bundle) ORD ID.\n\nAn API resource SHOULD be associated to one or multiple Consumption Bundles, if it is of direction `inbound` or `mixed`.\nSome ORD consumer use cases MAY depend on an association to a Consumption Bundle.\nIf none is given, the resource may not appear as it's unknown how it can be consumed.\n\nIf a resource has no direct incoming consumption characteristics:\n- MUST NOT assign Consumption Bundle to API or Event resources with `direction`: `outbound` (no inbound consumption)\n- MUST NOT assign Consumption Bundle if resource is not accessible directly, but only via intermediaries like event brokers or gateways.\n - In this case the intermediary SHOULD describe the Consumption Bundle instead (potentially also re-describing the resources as well).", "items": { "$ref": "#/definitions/ConsumptionBundleReference" }, "examples": [ [ { "ordId": "sap.xref:consumptionBundle:bundleXYZ:v1" } ] ] }, "defaultConsumptionBundle": { "type": "string", "description": "References the default Consumption Bundle to use for this resource.\n\nMUST be a valid reference to a [Consumption Bundle](#consumption-bundle) ORD ID.\n\nCan be used by clients to make a deterministic and preferred choice when multiple options are available.\n\nThe value MUST be an existing option in the corresponding `partOfConsumptionBundles` array.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/ConsumptionBundle/ordId" ], "maxLength": 255, "examples": [ "sap.xref:consumptionBundle:bundleXYZ:v1" ] }, "partOfProducts": { "type": "array", "description": "List of products the resources of the Package are a part of.\n\nMUST be a valid reference to a [Product](#product) ORD ID.\n\n`partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "x-association-target": [ "#/definitions/Product/ordId" ] }, "minItems": 0, "examples": [ [ "sap:product:S4HANA_OD:" ] ] }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "abstract": { "type": "boolean", "default": false, "x-introduced-in-version": "1.13.0", "x-feature-status": "beta", "description": "Indicates that the resource serves as interface only and cannot be called directly, similar to the abstract keyword in programming languages like Java.\n\nAbstract resources define contracts that other resources can declare compatibility with through the `compatibleWith` property.\n\nMore details can be found on the [Compatibility](../concepts/compatibility) concept page." }, "visibility": { "type": "string", "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": "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": "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": "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": "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "disabled": { "type": "boolean", "default": false, "description": "Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so.\nThis can happen either because it has not been setup for use or disabled by an admin / user.\n\nIf the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance-aware perspective.\n\nThis property can only reflect the knowledge of the described system instance itself.\nOutside factors for availability can't need to be considered (e.g. network connectivity, middlewares).\n\nA disabled resource MAY skip describing its resource definitions.\n" }, "minSystemVersion": { "type": "string", "description": "The resource has been introduced in the given [system version](../index.md#system-version).\nThis implies that the resource is only available if the system instance is of at least that system version.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.", "x-introduced-in-version": "1.10.0", "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", "2024.8.0" ] }, "relatedApiResources": { "type": "array", "x-introduced-in-version": "1.14.3", "description": "Optional list of related API Resources.\n\nUse this to indicate which APIs implement, expose, or are otherwise related to this entity.", "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.3", "description": "Optional list of related Event Resources.\n\nUse this to indicate which events are emitted, consumed, or otherwise related to this entity.", "items": { "$ref": "#/definitions/RelatedEventResource" }, "examples": [ [ { "ordId": "sap.s4:eventResource:BusinessPartnerEvents:v1", "relationType": "foo.bar:relationName" } ] ] }, "deprecationDate": { "type": "string", "format": "date-time", "description": "The deprecation date defines when the resource has been set as deprecated.\nThis is not to be confused with the `sunsetDate` which defines when the resource will be actually sunset, aka. decommissioned / removed / archived.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2020-12-08T15:47:04+00:00" ] }, "sunsetDate": { "type": "string", "format": "date-time", "description": "The sunset date defines when the resource is scheduled to be decommissioned / removed / archived.\n\nIf the `releaseStatus` is set to `deprecated`, the `sunsetDate` SHOULD be provided (if already known).\nOnce the sunset date is known and ready to be communicated externally, it MUST be provided here.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2022-01-08T15:47:04+00:00" ] }, "successors": { "type": "array", "description": "The successor resource(s).\n\nMUST be a valid reference to an ORD ID.\n\nIf the `releaseStatus` is set to `deprecated`, `successors` MUST be provided if one exists.\nIf `successors` is given, the described resource SHOULD set its `releaseStatus` to `deprecated`.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/ApiResource/ordId" ], "maxLength": 255 }, "examples": [ [ "sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v2" ] ] }, "changelogEntries": { "type": "array", "description": "Contains changelog entries that summarize changes with special regards to version and releaseStatus", "items": { "$ref": "#/definitions/ChangelogEntry" } }, "entryPoints": { "type": "array", "description": "List of [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the target host.\n\nIf the API resource can be accessed through an entry point, it MUST be described here.\n\nThe list of entry points MUST not include duplicates.\nIf multiple entry points are provided they MUST be arbitrarily exchangeable without effects.\nThis means that the URLs are just an alias to each other and the `resourceDefinitions` apply to all entry points equally.\nIn case of multiple entry points it is RECOMMENDED to provide a `defaultEntryPoint` through `partOfConsumptionBundles`.\nThe entry point URLs SHOULD match with the target host(s) in the resource definition files (e.g. OpenAPI `servers`).\nIf there is no match, the information in ORD takes precedence.\n\n**Provider View:**\nIf the URL is relative to the system that describes the ORD information,\nit is RECOMMENDED to use relative references and (if known) to provide the `describedSystemInstance`.`baseUrl`.\nIf the URL is not relative to the described system instance [base URL](../index.md#base-url), a full URL MUST be provided.\nIf the entry points are rewritten by middleware - incl. the special case of client/consumer specific entry points - it is RECOMMENDED to provide relative URLs, so only the `describedSystemInstance`.`baseUrl` has to be rewritten.\nThe provider should not have to describe all middleware or consumer specific entry points. If they are enriched later by the aggregator, it MAY omit the entry points.\n\n**Consumer View**:\nWhen fetching the information from an ORD Aggregator, the consumer MAY rely on receiving full URLs.", "items": { "type": "string", "format": "uri-reference" }, "minItems": 0, "examples": [ [ "/api-namespace/v1" ] ] }, "direction": { "type": "string", "description": "Direction of the API Resource consumption.\nIf not provided, \"inbound\" is assumed.\n\nIn case of SOAP APIs, the direction is already indicated through the `apiProtocol`, making this property redundant and optional. But if it is provided, it MUST not be in contradiction with the `apiProtocol` direction.", "oneOf": [ { "const": "inbound", "description": "The described system is the server. It's API Resource is available to external consumers by initiating connectivity." }, { "const": "mixed", "description": "Mixed direction API Resource. This is for example the case with Webhook APIs where both a subscription endpoint exists and also callback requests are made." }, { "const": "outbound", "description": "The described system is the client. It initiates connectivity to an (registered) external consumer.\nIf the API contract is owned by the described system, it can be documented here.\nIf it is owned by an external provider or authority, it needs to be referred to via implementation standard." } ], "default": "inbound" }, "apiProtocol": { "type": "string", "description": "API Protocol including the protocol version if applicable", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "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`, `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`, `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`, `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`, `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`, `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`, `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`, `custom` or any valid [Specification ID](../index.md#specification-id)." }, { "const": "mcp", "description": "[MCP](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide context to LLMs, based on JSON-RPC message format.\nThe protocol version is negotiated at runtime via the protocol itself.\n\nCurrently there is no standard API Resource definition type for MCP." }, { "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` or any valid [Specification ID](../index.md#specification-id)." }, { "const": "a2a", "x-introduced-in-version": "1.12.2", "description": "[A2A](https://a2a-protocol.org/latest/) is open protocol enabling communication and interoperability between opaque agentic applications.\n\nAs API Resource definition the `a2a-agent-card` MUST be provided, usually put under `/.well-known/agent.json`." }, { "const": "sap-rfc", "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", "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", "x-introduced-in-version": "1.8.0", "description": "SAP InA APIs are used by SAP Analytics Cloud solutions to capture data. It is an SAP proprietary protocol that only\nSAP Analytics Cloud MUST consume. It contains a protocol specific metadata retrieval mechanism so that SAP Analytics Cloud users can\nsee the schema of an InA API in SAP Analytics Cloud. An API Resource definition MUST NOT be provided." } ], "examples": [ "rest" ] }, "resourceDefinitions": { "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.", "items": { "$ref": "#/definitions/ApiResourceDefinition" } }, "implementationStandard": { "type": "string", "description": "Declares this API to be a valid implementation of an externally standardized API contract, sub-protocol or protocol variant.\n\nAll APIs that share the same implementation standard MAY be treated the same or similar by a consumer client.", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id).\nIf chosen, `customImplementationStandardDescription` SHOULD be provided." }, { "const": "cff:open-service-broker:v2", "description": "API follows the [Open Service Broker API V2](https://github.com/openservicebrokerapi/servicebroker)." }, { "const": "custom", "description": "If chosen, `customImplementationStandard` MUST be provided.\nIf chosen, `customImplementationStandardDescription` SHOULD be provided." } ], "examples": [ "sap:ord-document-api:v1" ] }, "customImplementationStandard": { "type": "string", "description": "If the fixed `implementationStandard` values need to be extended, an arbitrary `customImplementationStandard` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `implementationStandard` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.xref:some-api-contract:v1" ] }, "customImplementationStandardDescription": { "type": "string", "description": "Full description of the custom implementation standard, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nMUST only be provided if `implementationStandard` is set to `custom`.\n\nSHOULD contain documentation and links that describe the used standard.", "examples": [ "Implemented as defined in the [S/4HANA Attachment Service documentation](https://api.sap.com/api/API_CV_ATTACHMENT_SRV/overview)" ] }, "compatibleWith": { "x-introduced-in-version": "1.13.0", "x-feature-status": "beta", "type": "array", "description": "A reference to the interface (API contract) and its maximum version that this API implements. Even if the interface contract evolves compatible, this resource will not be compatible with versions beyond the specified one.\n\nServes as a declaration of compatible implementation of API contract, effectively functioning as an \"implementationOf\" relationship. The data that compatible APIs return follow the same schema, but itself can be different.\nThis means that if one API is returning 1 record for a dedicated request, a compatible API could return multiple and different records, as long as they adhere to the same schema.\n\nMUST be a valid reference to an (usually external) [API Resource](#api-resource) ORD ID.\n\nAll APIs that share the same `compatibleWith` value MAY be treated the same or similar by a consumer client.\n\nMore details can be found on the [Compatibility](../concepts/compatibility) concept page.", "items": { "$ref": "#/definitions/ApiCompatibility" }, "examples": [ [ { "ordId": "sap.s4com:apiResource:SomeSharedContract:v1", "maxVersion": "1.2" } ] ] }, "responsible": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255, "x-introduced-in-version": "1.8.0", "description": "Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components.", "examples": [ "sap:ach:CIC-DP-CO" ] }, "supportedUseCases": { "type": "array", "description": "List of use cases (types) how the resource is meant to be used for.\n\nThis helps consumers better to understand which use cases had been in mind by the provider\nand are therefore explicitly supported.\nThis is obviously described from a provider perspective, but stating what consumer use cases it potentially supports.\nAs it's not possible to create a list of options that are mutually exclusive, all options that apply should be provided.\n\nIf no array is defined, it is assumed that this information is not provided.", "x-introduced-in-version": "1.8.0", "x-feature-status": "beta", "items": { "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "data-federation", "description": "Resources are designed to support [data federation](https://en.wikipedia.org/wiki/Federated_database_system). This goes beyond plain queries, but typically allowing connections on the data base level, in the context of a business user.\nAs consumers will directly access data, performance of the system must support these use cases." }, { "const": "snapshot", "description": "Resource can be used to get a snapshot with inherent consistency including potential paging requests. Such a snapshot might be the basis for incremental updates. A snapshot API is typically providing unfiltered, complete mass data access by a technical user.\nAs data is typically replicated, performance of the API is important, but less critical for an end-user experience." }, { "const": "incremental", "description": "Resource gives incremental updates on top of snapshots." }, { "const": "streaming", "description": "Resource can be used to get streaming updates. The difference to 'incremental' is that it doesn't need a snapshot ." } ] }, "examples": [ [ "data-federation" ] ] }, "usage": { "x-introduced-in-version": "1.8.0", "x-feature-status": "alpha", "type": "string", "title": "Usage", "description": "Define from where the API resource can be used and accessed", "oneOf": [ { "const": "external", "description": "The API entryPoints are accessible external from the application providing it." }, { "const": "local", "description": "The API is only accessible within the application providing it. Access to (in-app) development tooling is necessary." } ], "default": "external" }, "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" } }, "exposedEntityTypes": { "type": "array", "x-introduced-in-version": "1.11.0", "description": "Optional list of [entity types](#entity-type) that are exposed by the resource.\n\nThis replaces `entityTypeMappings`. If both is given, the `exposedEntityTypes` wins.\n\nMUST be a valid reference to an [EntityType](#entity-type) ORD ID.", "items": { "$ref": "#/definitions/ExposedEntityType" }, "examples": [ [ { "ordId": "sap.odm:entityType:WorkforcePerson:v1" } ], [ { "ordId": "sap.sm:entityType:PurchaseOrderItem:v1" }, { "ordId": "sap.sm:entityType:BusinessPartner:v1" } ] ] }, "apiResourceLinks": { "type": "array", "description": "Links with semantic meaning that are specific to API Resources.", "items": { "$ref": "#/definitions/APIEventResourceLink" } }, "links": { "type": "array", "description": "Generic Links with arbitrary meaning and content.\n\nIf applicable, `apiResourceLinks` MUST be used instead of generic `links`.", "items": { "$ref": "#/definitions/Link" } }, "extensible": { "$ref": "#/definitions/Extensible" }, "countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "List of countries that the Package resources are applicable to.\n\nMUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n`countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "DE", "US" ] ] }, "lineOfBusiness": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Asset Management" }, { "const": "Commerce" }, { "const": "Finance" }, { "const": "Human Resources" }, { "const": "Manufacturing" }, { "const": "Marketing" }, { "const": "R&D Engineering" }, { "const": "Sales" }, { "const": "Service" }, { "const": "Sourcing and Procurement" }, { "const": "Strategy, Compliance, and Governance" }, { "const": "Supply Chain" }, { "const": "Sustainability" }, { "const": "Metering" }, { "const": "Grid Operations and Maintenance" }, { "const": "Plant Operations and Maintenance" }, { "const": "Maintenance and Engineering" } ] }, "description": "List of line of business tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Sales" ] ] }, "industry": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Aerospace and Defense" }, { "const": "Agribusiness" }, { "const": "Automotive" }, { "const": "Banking" }, { "const": "Chemicals" }, { "const": "Consumer Industries" }, { "const": "Consumer Products" }, { "const": "Defense and Security" }, { "const": "Discrete Industries" }, { "const": "Energy and Natural Resources" }, { "const": "Engineering Construction and Operations" }, { "const": "Financial Services" }, { "const": "Future Cities" }, { "const": "Healthcare" }, { "const": "High Tech" }, { "const": "Higher Education and Research" }, { "const": "Industrial Machinery and Components" }, { "const": "Insurance" }, { "const": "Life Sciences" }, { "const": "Media" }, { "const": "Mill Products" }, { "const": "Mining" }, { "const": "Oil and Gas" }, { "const": "Professional Services" }, { "const": "Public Sector" }, { "const": "Public Services" }, { "const": "Retail" }, { "const": "Service Industries" }, { "const": "Sports and Entertainment" }, { "const": "Telecommunications" }, { "const": "Travel and Transportation" }, { "const": "Utilities" }, { "const": "Wholesale Distribution" } ] }, "description": "List of industry tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Automotive" ], [ "Retail", "Public Sector" ], [] ] }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" }, "policyLevel": { "type": "string", "description": "The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with.\nDepending on the chosen policy level, additional expectations and validations rules will be applied.\n\nThe policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "none", "description": "No policy level chosen. Only the base rules on how to create correct ORD documents apply." }, { "const": "custom", "description": "Custom policy level.\nFurther validation MAY be defined and implemented by the policy-level owner.\nThis level MAY be chosen by 3rd party or customer solutions.\nIf chosen, `customPolicyLevel` MUST be provided." } ], "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" ] }, "customPolicyLevel": { "type": "string", "description": "If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.\nThe policy level is inherited from packages to resources they contain, but can be overwritten at resource level.\n\nMUST only be provided if `policyLevel` is set to `custom`.\nMUST be a valid [Specification ID](../index.md#specification-id).", "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" ] }, "policyLevels": { "type": "array", "description": "A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with.\nFor each chosen policy level, additional expectations and validations rules will be applied.\n\nPolicy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n\nA policy level MUST be a valid [Specification ID](../index.md#specification-id).", "x-introduced-in-version": "1.9.9", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:core:v1" ] } }, "systemInstanceAware": { "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 ] } }, "required": [ "ordId", "title", "shortDescription", "description", "version", "releaseStatus", "apiProtocol", "visibility", "partOfPackage" ], "additionalProperties": false }, "EventResource": { "type": "object", "title": "Event Resource", "x-ums-type": "root", "description": "The event resource provides a high-level description of a collection of related Events. More detailed information, such as the event resource definitions, are provided in links in the table below.\nWhich events are considered \"related\" is up to the implementer. A common practice is to bundle events that are based on the same resource/Business Object. It is also an option to bundle all available events into a single event resource/event catalog.\nPlease note that event resources can be described, but still be [`disabled`](#event-resource_disabled).\nIf the event resource is not created or owned by the user / customer of the system or by partners / third parties, it MUST be assigned to dedicated [Packages](#package) that state this the ownership via the `vendor` property.", "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.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1", "sap.s4:eventResource:BillofMaterialEvents:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "BusinessEvents_SubscriptionEvents" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.xref:localConcept:SomeLocalId" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SalesOrder Events", "System XYZ Events" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "All events related to the Business Object SalesOrder" ] }, "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": [ "This event is raised by the SAP S/4HANA Cloud system when an invoice document is cancelled.\n" ] }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [ "sap.xref:package:SomePackage:v1" ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together." }, "partOfConsumptionBundles": { "type": "array", "description": "List of references to the Consumption Bundles in this resource belongs to.\n\nMUST be a valid reference to a [Consumption Bundle](#consumption-bundle) ORD ID.\n\nAn API resource SHOULD be associated to one or multiple Consumption Bundles, if it is of direction `inbound` or `mixed`.\nSome ORD consumer use cases MAY depend on an association to a Consumption Bundle.\nIf none is given, the resource may not appear as it's unknown how it can be consumed.\n\nIf a resource has no direct incoming consumption characteristics:\n- MUST NOT assign Consumption Bundle to API or Event resources with `direction`: `outbound` (no inbound consumption)\n- MUST NOT assign Consumption Bundle if resource is not accessible directly, but only via intermediaries like event brokers or gateways.\n - In this case the intermediary SHOULD describe the Consumption Bundle instead (potentially also re-describing the resources as well).", "items": { "$ref": "#/definitions/ConsumptionBundleReference" }, "examples": [ [ { "ordId": "sap.xref:consumptionBundle:bundleXYZ:v1" } ] ] }, "defaultConsumptionBundle": { "type": "string", "description": "References the default Consumption Bundle to use for this resource.\n\nMUST be a valid reference to a [Consumption Bundle](#consumption-bundle) ORD ID.\n\nCan be used by clients to make a deterministic and preferred choice when multiple options are available.\n\nThe value MUST be an existing option in the corresponding `partOfConsumptionBundles` array.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/ConsumptionBundle/ordId" ], "maxLength": 255, "examples": [ "sap.xref:consumptionBundle:bundleXYZ:v1" ] }, "partOfProducts": { "type": "array", "description": "List of products the resources of the Package are a part of.\n\nMUST be a valid reference to a [Product](#product) ORD ID.\n\n`partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "x-association-target": [ "#/definitions/Product/ordId" ] }, "minItems": 0, "examples": [ [ "sap:product:S4HANA_OD:" ] ] }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "abstract": { "type": "boolean", "default": false, "x-introduced-in-version": "1.13.0", "x-feature-status": "beta", "description": "Indicates that the resource serves as interface only and cannot be called directly, similar to the abstract keyword in programming languages like Java.\n\nAbstract resources define contracts that other resources can declare compatibility with through the `compatibleWith` property.\n\nMore details can be found on the [Compatibility](../concepts/compatibility) concept page." }, "visibility": { "type": "string", "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": "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": "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": "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": "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "disabled": { "type": "boolean", "default": false, "description": "Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so.\nThis can happen either because it has not been setup for use or disabled by an admin / user.\n\nIf the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance-aware perspective.\n\nThis property can only reflect the knowledge of the described system instance itself.\nOutside factors for availability can't need to be considered (e.g. network connectivity, middlewares).\n\nA disabled resource MAY skip describing its resource definitions.\n" }, "minSystemVersion": { "type": "string", "description": "The resource has been introduced in the given [system version](../index.md#system-version).\nThis implies that the resource is only available if the system instance is of at least that system version.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.", "x-introduced-in-version": "1.10.0", "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", "2024.8.0" ] }, "relatedApiResources": { "type": "array", "x-introduced-in-version": "1.14.3", "description": "Optional list of related API Resources.\n\nUse this to indicate which APIs implement, expose, or are otherwise related to this entity.", "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.3", "description": "Optional list of related Event Resources.\n\nUse this to indicate which events are emitted, consumed, or otherwise related to this entity.", "items": { "$ref": "#/definitions/RelatedEventResource" }, "examples": [ [ { "ordId": "sap.s4:eventResource:BusinessPartnerEvents:v1", "relationType": "foo.bar:relationName" } ] ] }, "deprecationDate": { "type": "string", "format": "date-time", "description": "The deprecation date defines when the resource has been set as deprecated.\nThis is not to be confused with the `sunsetDate` which defines when the resource will be actually sunset, aka. decommissioned / removed / archived.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2020-12-08T15:47:04+00:00" ] }, "sunsetDate": { "type": "string", "format": "date-time", "description": "The sunset date defines when the resource is scheduled to be decommissioned / removed / archived.\n\nIf the `releaseStatus` is set to `deprecated`, the `sunsetDate` SHOULD be provided (if already known).\nOnce the sunset date is known and ready to be communicated externally, it MUST be provided here.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2022-01-08T15:47:04+00:00" ] }, "successors": { "type": "array", "description": "The successor resource(s).\n\nMUST be a valid reference to an ORD ID.\n\nIf the `releaseStatus` is set to `deprecated`, `successors` MUST be provided if one exists.\nIf `successors` is given, the described resource SHOULD set its `releaseStatus` to `deprecated`.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "x-association-target": [ "#/definitions/EventResource/ordId" ] }, "examples": [ [ "sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1" ] ] }, "changelogEntries": { "type": "array", "description": "Contains changelog entries that summarize changes with special regards to version and releaseStatus", "items": { "$ref": "#/definitions/ChangelogEntry" } }, "resourceDefinitions": { "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.", "items": { "$ref": "#/definitions/EventResourceDefinition" } }, "implementationStandard": { "type": "string", "description": "Declares this EventResource to be a valid implementation of a standardized or shared contract.\n\nAll implementations of the same implementation standard MAY be treated the same by a consumer.\nHowever, there MAY be differences in the access strategy, and compatible customizations by the implementer.\nThe implementation standard MAY define the role of the implementor (producer, consumer, both) and how it is determined.\n\nAs of now, only custom implementation standards are supported.", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/ApiResource/ordId" ], "description": "Any valid [API Resource ORD ID](../index.md#ord-id).\n\nRECOMMENDED to use if the contract is published via ORD and has an ORD ID." }, { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id).\nIf chosen, `customImplementationStandardDescription` SHOULD be provided." }, { "const": "custom", "description": "If chosen, a custom implementation standard MUST be provided via `customImplementationStandard` and SHOULD be described via `customImplementationStandardDescription`" } ], "examples": [ "custom" ] }, "customImplementationStandard": { "type": "string", "description": "If the fixed `implementationStandard` values need to be extended, an arbitrary `customImplementationStandard` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `implementationStandard` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.xref:some-event-contract:v1" ] }, "customImplementationStandardDescription": { "type": "string", "description": "Full description of the custom implementation standard, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nMUST only be provided if `implementationStandard` is set to `custom`.\n\nSHOULD contain documentation and links that describe the used standard.", "examples": [ "Implemented as defined in [Some Application Documentation](some link)." ] }, "compatibleWith": { "x-introduced-in-version": "1.13.0", "x-feature-status": "beta", "type": "array", "description": "A reference to the interface (event contract) and its maximum version that this event implements. Even if the interface contract evolves compatible, this resource will not be compatible with versions beyond the specified one.\n\nServes as a declaration of compatible implementation of event contract, effectively functioning as an \"implementationOf\" relationship. The data that compatible events return follow the same schema, but itself can be different.\nThis means that if one event is returning 1 record for a dedicated request, a compatible event could return multiple and different records, as long as they adhere to the same schema.\n\nAll events that share the same `compatibleWith` value MAY be treated the same or similar by a consumer client.\n\nMore details can be found on the [Compatibility](../concepts/compatibility) concept page.", "items": { "$ref": "#/definitions/EventCompatibility" }, "examples": [ [ { "ordId": "sap.s4:eventResource:BillofMaterialEvents:v1", "maxVersion": "1.2" } ] ] }, "responsible": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255, "x-introduced-in-version": "1.8.0", "description": "Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components.", "examples": [ "sap:ach:CIC-DP-CO" ] }, "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" } }, "exposedEntityTypes": { "type": "array", "x-introduced-in-version": "1.11.0", "description": "Optional list of [entity types](#entity-type) that are exposed by the resource.\n\nThis replaces `entityTypeMappings`. If both is given, the `exposedEntityTypes` wins.\n\nMUST be a valid reference to an [EntityType](#entity-type) ORD ID.", "items": { "$ref": "#/definitions/ExposedEntityType" }, "examples": [ [ { "ordId": "sap.odm:entityType:WorkforcePerson:v1" } ], [ { "ordId": "sap.sm:entityType:PurchaseOrderItem:v1" }, { "ordId": "sap.sm:entityType:BusinessPartner:v1" } ] ] }, "eventResourceLinks": { "type": "array", "x-introduced-in-version": "1.7.1", "description": "Links with semantic meaning that are specific to event resources.\n\nIf applicable, `eventResourceLinks` MUST be used instead of generic `links`.", "items": { "$ref": "#/definitions/APIEventResourceLink" } }, "links": { "type": "array", "description": "Generic Links with arbitrary meaning and content.", "items": { "$ref": "#/definitions/Link" } }, "extensible": { "$ref": "#/definitions/Extensible" }, "countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "List of countries that the Package resources are applicable to.\n\nMUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n`countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "DE", "US" ] ] }, "lineOfBusiness": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Asset Management" }, { "const": "Commerce" }, { "const": "Finance" }, { "const": "Human Resources" }, { "const": "Manufacturing" }, { "const": "Marketing" }, { "const": "R&D Engineering" }, { "const": "Sales" }, { "const": "Service" }, { "const": "Sourcing and Procurement" }, { "const": "Strategy, Compliance, and Governance" }, { "const": "Supply Chain" }, { "const": "Sustainability" }, { "const": "Metering" }, { "const": "Grid Operations and Maintenance" }, { "const": "Plant Operations and Maintenance" }, { "const": "Maintenance and Engineering" } ] }, "description": "List of line of business tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Sales" ] ] }, "industry": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Aerospace and Defense" }, { "const": "Agribusiness" }, { "const": "Automotive" }, { "const": "Banking" }, { "const": "Chemicals" }, { "const": "Consumer Industries" }, { "const": "Consumer Products" }, { "const": "Defense and Security" }, { "const": "Discrete Industries" }, { "const": "Energy and Natural Resources" }, { "const": "Engineering Construction and Operations" }, { "const": "Financial Services" }, { "const": "Future Cities" }, { "const": "Healthcare" }, { "const": "High Tech" }, { "const": "Higher Education and Research" }, { "const": "Industrial Machinery and Components" }, { "const": "Insurance" }, { "const": "Life Sciences" }, { "const": "Media" }, { "const": "Mill Products" }, { "const": "Mining" }, { "const": "Oil and Gas" }, { "const": "Professional Services" }, { "const": "Public Sector" }, { "const": "Public Services" }, { "const": "Retail" }, { "const": "Service Industries" }, { "const": "Sports and Entertainment" }, { "const": "Telecommunications" }, { "const": "Travel and Transportation" }, { "const": "Utilities" }, { "const": "Wholesale Distribution" } ] }, "description": "List of industry tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Automotive" ], [ "Retail", "Public Sector" ], [] ] }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" }, "policyLevel": { "type": "string", "description": "The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with.\nDepending on the chosen policy level, additional expectations and validations rules will be applied.\n\nThe policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "none", "description": "No policy level chosen. Only the base rules on how to create correct ORD documents apply." }, { "const": "custom", "description": "Custom policy level.\nFurther validation MAY be defined and implemented by the policy-level owner.\nThis level MAY be chosen by 3rd party or customer solutions.\nIf chosen, `customPolicyLevel` MUST be provided." } ], "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" ] }, "customPolicyLevel": { "type": "string", "description": "If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.\nThe policy level is inherited from packages to resources they contain, but can be overwritten at resource level.\n\nMUST only be provided if `policyLevel` is set to `custom`.\nMUST be a valid [Specification ID](../index.md#specification-id).", "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" ] }, "policyLevels": { "type": "array", "description": "A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with.\nFor each chosen policy level, additional expectations and validations rules will be applied.\n\nPolicy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n\nA policy level MUST be a valid [Specification ID](../index.md#specification-id).", "x-introduced-in-version": "1.9.9", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:core:v1" ] } }, "systemInstanceAware": { "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 ] } }, "additionalProperties": false, "required": [ "ordId", "title", "shortDescription", "description", "version", "visibility", "partOfPackage", "releaseStatus" ], "x-recommended": [ "lastUpdate" ] }, "EntityType": { "type": "object", "title": "Entity Type", "x-ums-type": "root", "description": "An [**Entity Type**](../concepts/grouping-and-bundling#entity-type) describes either a business concept / term or an underlying conceptual model (e.g. a business object / domain model).\nEntity Types can be related to API & Event resources, Data Products and other Entity Types, connecting exposed resources to business semantics.\n\nTo learn more about the concept, see [Entity Type](../concepts/grouping-and-bundling#entity-type).", "x-introduced-in-version": "1.8.0", "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]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.odm:entityType:BusinessPartner:v1", "sap.odm:entityType:CostCenter:v1", "sap.odm:entityType:WorkforcePerson:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "BusinessPartner", "CostCenter", "WorkforcePerson" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:sot:BusinessPartner" ], [ "sap.s4:sot:CostCenter" ], [ "sap.s4:sot:WorkforcePerson" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "Business Partner", "Cost Center", "Workforce Person" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "A business partner is a person, an organization, or a group of persons or organizations in which a company has a business interest.", "A cost center is an organizational center where costs are incurred and for which costs are recorded separately.", "A workforce person is a natural person with a work agreement or relationship in form of a work assignment; it can be an employee or a contingent worker." ] }, "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": [ "A business partner is a person, an organization, or a group of persons or organizations in which a company has a business interest.\n", "A cost center is an organizational center where costs are incurred and for which costs are recorded separately.\n", "A workforce person is a natural person with a work agreement or relationship in form of a work assignment; it can be an employee or a contingent worker.\n" ] }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [ "sap.xref:package:SomePackage:v1" ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together." }, "partOfProducts": { "type": "array", "description": "List of products the resources of the Package are a part of.\n\nMUST be a valid reference to a [Product](#product) ORD ID.\n\n`partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "x-association-target": [ "#/definitions/Product/ordId" ] }, "minItems": 0, "examples": [ [ "sap:product:S4HANA_OD:" ] ] }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "visibility": { "type": "string", "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": "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": "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": "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": "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "deprecationDate": { "type": "string", "format": "date-time", "description": "The deprecation date defines when the resource has been set as deprecated.\nThis is not to be confused with the `sunsetDate` which defines when the resource will be actually sunset, aka. decommissioned / removed / archived.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2020-12-08T15:47:04+00:00" ] }, "sunsetDate": { "type": "string", "format": "date-time", "description": "The sunset date defines when the resource is scheduled to be decommissioned / removed / archived.\n\nIf the `releaseStatus` is set to `deprecated`, the `sunsetDate` SHOULD be provided (if already known).\nOnce the sunset date is known and ready to be communicated externally, it MUST be provided here.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2022-01-08T15:47:04+00:00" ] }, "successors": { "type": "array", "description": "The successor resource(s).\n\nMUST be a valid reference to an ORD ID.\n\nIf the `releaseStatus` is set to `deprecated`, `successors` MUST be provided if one exists.\nIf `successors` is given, the described resource SHOULD set its `releaseStatus` to `deprecated`.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/EntityType/ordId" ], "maxLength": 255 }, "examples": [ [ "sap.odm:entityType:BusinessPartner:v2" ], [ "sap.odm:entityType:CostCenter:v2" ], [ "sap.odm:entityType:WorkforcePerson:v2" ] ] }, "changelogEntries": { "type": "array", "description": "Contains changelog entries that summarize changes with special regards to version and releaseStatus", "items": { "$ref": "#/definitions/ChangelogEntry" } }, "level": { "type": "string", "description": "Defining the abstraction level of the entity type using the DDD terminology.\n\nIn Domain-Driven Design, there is a concept of entities and aggregates.\nThere are root entities which may contain further sub entities by composition.\nThe complete \"package\" is then called an aggregate, which gets its name and identity from the root entity.\nAn aggregate is a cluster of domain objects that can be treated as a single unit.\nThe root is the entity that is referenced from outside the aggregate. There must be only one root per aggregate.\nThe root ensures the integrity of the aggregate. A sub entity is any other non-root entity in the aggregate.\n\nSource, see [Martin Fowler on DDD Aggregate](https://martinfowler.com/bliki/DDD_Aggregate.html)", "oneOf": [ { "const": "aggregate", "description": "An aggregate is the combined tree of entity types (combined via composition).\nThe root entity gives the aggregate its identity and ID.\nThe inner structure of an aggregate (sub entities, field, etc.) could be described in the entity type definition." }, { "const": "root-entity", "description": "Represents only the root entity (aka DDD aggregate root). Potential composite sub-entities are NOT included (unlike with `aggregate`)." }, { "const": "sub-entity", "description": "Represents an individual sub entity (aka composite entity).\nDescribing it in ORD may be necessary if the sub-entities need a dedicated ORD ID.\nHowever, we recommend not to expose the internal structure of aggregate if possible." } ], "examples": [ "aggregate" ] }, "relatedEntityTypes": { "type": "array", "x-introduced-in-version": "1.9.0", "description": "States that this Entity Type is related to another Entity Type.\n\nUsually this happens if there are similar conceptual entity types across different namespaces.", "items": { "$ref": "#/definitions/RelatedEntityType" }, "examples": [ [ { "ordId": "sap.odm:entityType:WorkforcePerson:v1" } ] ] }, "links": { "type": "array", "description": "Generic Links with arbitrary meaning and content.", "items": { "$ref": "#/definitions/Link" } }, "extensible": { "$ref": "#/definitions/Extensible" }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" }, "policyLevel": { "type": "string", "description": "The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with.\nDepending on the chosen policy level, additional expectations and validations rules will be applied.\n\nThe policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "none", "description": "No policy level chosen. Only the base rules on how to create correct ORD documents apply." }, { "const": "custom", "description": "Custom policy level.\nFurther validation MAY be defined and implemented by the policy-level owner.\nThis level MAY be chosen by 3rd party or customer solutions.\nIf chosen, `customPolicyLevel` MUST be provided." } ], "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" ] }, "customPolicyLevel": { "type": "string", "description": "If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.\nThe policy level is inherited from packages to resources they contain, but can be overwritten at resource level.\n\nMUST only be provided if `policyLevel` is set to `custom`.\nMUST be a valid [Specification ID](../index.md#specification-id).", "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" ] }, "policyLevels": { "type": "array", "description": "A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with.\nFor each chosen policy level, additional expectations and validations rules will be applied.\n\nPolicy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n\nA policy level MUST be a valid [Specification ID](../index.md#specification-id).", "x-introduced-in-version": "1.9.9", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:core:v1" ] } }, "systemInstanceAware": { "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 ] } }, "additionalProperties": false, "required": [ "ordId", "localId", "level", "title", "version", "visibility", "partOfPackage", "releaseStatus" ], "x-recommended": [ "lastUpdate" ] }, "DataProduct": { "type": "object", "title": "Data Product", "x-ums-type": "root", "x-introduced-in-version": "1.8.0", "description": "A [Data Product](../concepts/data-product) is a data set exposed for consumption outside the boundaries of the producing application via APIs and described by high quality metadata that can be accessed through the [ORD Aggregator](../../spec-v1/#ord-aggregator).\n\nPlease note that this concept is in beta, see [Data Product - Current Status](../concepts/data-product#current-status).", "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]+)*):(dataProduct):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.foo.bar:dataProduct:CustomerOrder:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "CustomerOrder" ] }, "correlationIds": { "x-feature-status": "beta", "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:communicationScenario:SAP_COM_0008" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "Customer Order" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "Offering access to all online and offline orders submitted by customers" ] }, "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": [ "The data product Customer Order offers access to all online and offline orders submitted by customers. It provides a customer view on the orders. For fulfillment-specific aspects please refer to the data product Fulfillment Order." ] }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [ "sap.xref:package:SomePackage:v1" ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together.", "x-feature-status": "beta" }, "partOfProducts": { "type": "array", "description": "List of products this Data Product is a part of or is related to, its e.g. data source systems.\n\nMUST be a valid reference to a [Product](#product) ORD ID.\n\n`partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "x-association-target": [ "#/definitions/Product/ordId" ] }, "minItems": 0, "examples": [ [ "sap:product:S4HANA_OD:" ] ] }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "visibility": { "type": "string", "description": "The visibility/exposure of the data product. A public data product might have private APIs for trusted consumers therefore the having the property on data product", "oneOf": [ { "const": "public", "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": "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": "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 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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "disabled": { "x-feature-status": "beta", "type": "boolean", "default": false, "description": "Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so.\nThis can happen either because it has not been setup for use or disabled by an admin / user.\n\nIf the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance-aware perspective.\n\nThis property can only reflect the knowledge of the described system instance itself.\nOutside factors for availability can't need to be considered (e.g. network connectivity, middlewares).\n\nA disabled resource MAY skip describing its resource definitions.\n" }, "abstract": { "type": "boolean", "default": false, "x-introduced-in-version": "1.13.0", "x-feature-status": "beta", "description": "Indicates that the data product serves as interface only. All output ports MUST be marked as abstract.\n\nImplementations of this data product MUST declare compatible with on their specific output port resources as consumption of data products happens through the output ports." }, "minSystemVersion": { "type": "string", "description": "The resource has been introduced in the given [system version](../index.md#system-version).\nThis implies that the resource is only available if the system instance is of at least that system version.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.", "x-introduced-in-version": "1.10.0", "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", "2024.8.0" ] }, "lifecycleStatus": { "type": "string", "description": "Lifecycle status of the Data Product as a whole.\n\nMUST be provided when describing the system-instance-aware (run-time) perspective.\nSHOULD NOT be provided in static (design-time) perspective. Static aggregators MUST ignore this property.", "oneOf": [ { "const": "inactive", "description": "The data product is currently inactive, but can be provisioned." }, { "const": "provisioning", "description": "The data product is currently being provisioned / installed and is not yet ready to be used.\nThis includes acquiring data from input ports, potentially necessary transformation and making the data available in the output ports.\nDuring the provisioning phase the data product is not yet usable by consumers and metadata MAY still be incomplete." }, { "const": "provisioning-error", "description": "The provisioning of the data product failed with error(s). Consumers cannot expect the metadata or data to be available until all errors are resolved." }, { "const": "data-loading", "x-introduced-in-version": "1.13.0", "description": "The data product metadata is ready, and data loading is in progress. It might have started to acquire or transform data before, but is not yet finished.\nThis includes having all necessary metadata information, but the actual data may still be in the process of being acquired or transformed.\nThe data product might be usable for metadata-driven scenarios, but not yet for actual data consumption." }, { "const": "data-loading-error", "x-introduced-in-version": "1.13.0", "description": "The data product metadata is ready, but errors occurred during data acquisition or transformation.\nConsumers cannot expect the data to be available until all errors are resolved." }, { "const": "active", "description": "The data product is active / live and can be used by consumers.\nThere MAY be warnings but there MUST not be reported errors in the data product." }, { "const": "active-with-errors", "description": "The data product has been successfully provisioned and has gone `active`, but errors prevent proper consumption.\nConsistent usage of the data product is not guaranteed until all errors are resolved." }, { "const": "deprovisioning", "description": "The data product is being deprovisioned / uninstalled and not available for use anymore.\nDeprovisioning includes un-sharing the data from connected consumers and removing the replicated data which is no longer used.\nAfter successful deprovisioning the data product will either be `disabled: true` (preferred) or not described by the tenant at run-time." }, { "const": "deprovisioning-error", "description": "The deprovisioning of the data product failed with error(s).\nConsistent usage of the data product is not guaranteed until all errors are resolved." } ], "examples": [ "active" ] }, "deprecationDate": { "x-feature-status": "beta", "type": "string", "format": "date-time", "description": "The deprecation date defines when the resource has been set as deprecated.\nThis is not to be confused with the `sunsetDate` which defines when the resource will be actually sunset, aka. decommissioned / removed / archived.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2020-12-08T15:47:04+00:00" ] }, "sunsetDate": { "x-feature-status": "beta", "type": "string", "format": "date-time", "description": "The sunset date defines when the resource is scheduled to be decommissioned / removed / archived.\n\nIf the `releaseStatus` is set to `deprecated`, the `sunsetDate` SHOULD be provided (if already known).\nOnce the sunset date is known and ready to be communicated externally, it MUST be provided here.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2022-01-08T15:47:04+00:00" ] }, "successors": { "x-feature-status": "beta", "type": "array", "description": "The successor resource(s).\n\nMUST be a valid reference to an ORD ID.\n\nIf the `releaseStatus` is set to `deprecated`, `successors` MUST be provided if one exists.\nIf `successors` is given, the described resource SHOULD set its `releaseStatus` to `deprecated`.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "x-association-target": [ "#/definitions/DataProduct/ordId" ] }, "examples": [ [ "sap.foo.bar:dataProduct:CustomerOrder:v1" ] ] }, "changelogEntries": { "x-feature-status": "beta", "type": "array", "description": "Contains changelog entries that summarize changes with special regards to version and releaseStatus", "items": { "$ref": "#/definitions/ChangelogEntry" } }, "type": { "description": "Type of the data product. Based on the type some properties of a data product may become optional/mandatory.", "type": "string", "oneOf": [ { "const": "primary", "description": "A producer aligned data product, aka primary data product.\nSuch a data product will be typically served directly from an application and might not have input ports." }, { "const": "derived", "description": "A data product that typically aggregates and combines data from multiple sources to provider value added data sets on top.\nDerived data products must provide at least one input port with an integration dependency that has at least one requirement.\nTo be clarified if we need an additional analytical type for data products that focus on calculating KPIs." } ], "examples": [ "primary" ] }, "category": { "description": "Category of the data-set within data product. Based on its definition, a data product is a \"data set\" - which can include on the values below.\nBased on the type some properties of a data product may become optional/mandatory.\nConsumers might still do analytics on business object like data products.", "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "business-object", "description": "Business Objects: master data, transaction data" }, { "const": "analytical", "description": "Analytical data, including cubes, KPIs and metrics" }, { "const": "other", "description": "Other objects, eg: config data, mixed or just unspecified" } ], "examples": [ "business-object" ] }, "entityTypes": { "x-feature-status": "beta", "type": "array", "description": "Aggregated list of entity types that are at least partially exposed by the data product. Detailed mapping can be found on the output port schema level.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "x-association-target": [ "#/definitions/EntityType/ordId" ] }, "examples": [ [ "sap.odm:entityType:CustomerOrder:v1", "sap.odm:entityType:BusinessPartner:v1" ] ] }, "inputPorts": { "x-feature-status": "beta", "type": "array", "description": "The input ports of a data product indicate the data inputs for lineage purposes.\n\nIt is a list of Integration Dependencies, whose aspects will form the actual input ports.\n\nInput ports can also be understood as the public interface to ingest data into the data product.\nData products of type `derived` consume data through the input ports. Different input ports allowing ingestion of different sub-sets building up the data-set for the data product.\nData products of type `base` might not have any input ports. Their data sets are typically based directly on the applications / services own data.", "minItems": 0, "items": { "$ref": "#/definitions/DataProductInputPort" }, "examples": [ [ { "ordId": "sap.xref:integrationDependency:CustomerOrder:v1" } ] ] }, "outputPorts": { "type": "array", "description": "Output ports are the interface (APIs and Events) through which the data of the data product can be accessed.\n\nOutput ports of the same data product might produce different facets of the data set with different qualities.\nA data set can also be made available via different protocols, which also results in different ports.\n\nAs long as different output ports are accessing the same model beneath, they should belong to the same data product.\nIf the above criteria cannot be reasonably met, consider splitting the data product into multiple smaller data products.", "minItems": 1, "items": { "$ref": "#/definitions/DataProductOutputPort" }, "examples": [ [ { "ordId": "sap.cic:apiResource:RetailTransactionOData:v1" }, { "ordId": "sap.cic:eventResource:RawCustomerOrder:v2" } ] ] }, "responsible": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255, "x-introduced-in-version": "1.8.0", "description": "Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components.", "examples": [ "sap:ach:CIC-DP-CO" ] }, "dataProductLinks": { "x-feature-status": "beta", "type": "array", "description": "Links with semantic meaning that are specific to Data Product Resources.", "items": { "$ref": "#/definitions/DataProductLink" } }, "links": { "x-feature-status": "beta", "type": "array", "description": "Generic Links with arbitrary meaning and content.", "items": { "$ref": "#/definitions/Link" } }, "industry": { "x-feature-status": "beta", "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Aerospace and Defense" }, { "const": "Agribusiness" }, { "const": "Automotive" }, { "const": "Banking" }, { "const": "Chemicals" }, { "const": "Consumer Industries" }, { "const": "Consumer Products" }, { "const": "Defense and Security" }, { "const": "Discrete Industries" }, { "const": "Energy and Natural Resources" }, { "const": "Engineering Construction and Operations" }, { "const": "Financial Services" }, { "const": "Future Cities" }, { "const": "Healthcare" }, { "const": "High Tech" }, { "const": "Higher Education and Research" }, { "const": "Industrial Machinery and Components" }, { "const": "Insurance" }, { "const": "Life Sciences" }, { "const": "Media" }, { "const": "Mill Products" }, { "const": "Mining" }, { "const": "Oil and Gas" }, { "const": "Professional Services" }, { "const": "Public Sector" }, { "const": "Public Services" }, { "const": "Retail" }, { "const": "Service Industries" }, { "const": "Sports and Entertainment" }, { "const": "Telecommunications" }, { "const": "Travel and Transportation" }, { "const": "Utilities" }, { "const": "Wholesale Distribution" } ] }, "description": "List of industry tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Automotive" ], [ "Retail", "Public Sector" ], [] ] }, "lineOfBusiness": { "x-feature-status": "beta", "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Asset Management" }, { "const": "Commerce" }, { "const": "Finance" }, { "const": "Human Resources" }, { "const": "Manufacturing" }, { "const": "Marketing" }, { "const": "R&D Engineering" }, { "const": "Sales" }, { "const": "Service" }, { "const": "Sourcing and Procurement" }, { "const": "Strategy, Compliance, and Governance" }, { "const": "Supply Chain" }, { "const": "Sustainability" }, { "const": "Metering" }, { "const": "Grid Operations and Maintenance" }, { "const": "Plant Operations and Maintenance" }, { "const": "Maintenance and Engineering" } ] }, "description": "List of line of business tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Sales" ] ] }, "countries": { "x-feature-status": "beta", "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "List of countries that the Package resources are applicable to.\n\nMUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n`countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "DE", "US" ] ] }, "tags": { "x-feature-status": "beta", "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "x-feature-status": "beta", "$ref": "#/definitions/Labels" }, "documentationLabels": { "x-feature-status": "beta", "$ref": "#/definitions/DocumentationLabels" }, "policyLevel": { "x-feature-status": "beta", "type": "string", "description": "The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with.\nDepending on the chosen policy level, additional expectations and validations rules will be applied.\n\nThe policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "none", "description": "No policy level chosen. Only the base rules on how to create correct ORD documents apply." }, { "const": "custom", "description": "Custom policy level.\nFurther validation MAY be defined and implemented by the policy-level owner.\nThis level MAY be chosen by 3rd party or customer solutions.\nIf chosen, `customPolicyLevel` MUST be provided." } ], "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" ] }, "customPolicyLevel": { "x-feature-status": "beta", "type": "string", "description": "If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided.\nThe policy level is inherited from packages to resources they contain, but can be overwritten at resource level.\n\nMUST only be provided if `policyLevel` is set to `custom`.\nMUST be a valid [Specification ID](../index.md#specification-id).", "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" ] }, "policyLevels": { "type": "array", "description": "A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with.\nFor each chosen policy level, additional expectations and validations rules will be applied.\n\nPolicy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n\nA policy level MUST be a valid [Specification ID](../index.md#specification-id).", "x-introduced-in-version": "1.9.9", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:core:v1" ] } }, "systemInstanceAware": { "x-feature-status": "beta", "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 ] } }, "additionalProperties": false, "required": [ "ordId", "type", "category", "title", "shortDescription", "description", "version", "releaseStatus", "visibility", "partOfPackage", "responsible", "outputPorts" ], "x-recommended": [ "lastUpdate" ] }, "DataProductInputPort": { "type": "object", "title": "Data Product Input Port", "x-ums-type": "embedded", "description": "An input port of a data product states where it retrieves its data inputs from.\n\nIt is described as via an ORD Integration Dependency.", "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]+)*):(integrationDependency):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.foo.bar:integrationDependency:CustomerOrder:v1" ], "x-association-target": [ "#/definitions/IntegrationDependency/ordId" ] } }, "additionalProperties": false, "required": [ "ordId" ] }, "DataProductOutputPort": { "type": "object", "title": "Data Product Output Port", "x-ums-type": "embedded", "description": "A data product output port references the APIs or Events that can be used to access the data-set.\nIt MAY provide full access to the complete data set, but can also just expose a subset of it - if other output ports cover the missing parts.\n\nReferenced API or Event ORD resources don't need to be provided within the same ORD document.\nIf a data product is built against a specific API contract of another application or data product, this API resource should be referred to.\nIn this case the other application is responsible for the lifecycle of the API contract and will update its ORD description independently.", "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|eventResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.cic:apiResource:RetailTransactionOData:v1", "sap.cic:eventResource:RawCustomerOrder:v2" ], "x-association-target": [ "#/definitions/ApiResource/ordId", "#/definitions/EventResource/ordId" ] } }, "additionalProperties": false, "required": [ "ordId" ] }, "ApiResourceDefinition": { "type": "object", "title": "Api Resource Definition", "description": "Link and categorization of a machine-readable API definition.\nFor example, OpenAPI definition, OData Metadata, etc.", "x-ums-type": "custom", "properties": { "type": { "description": "Type of the API Resource Definition\nIf \"custom\" is chosen, a customType MUST be provided", "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "openapi-v2", "description": "[OpenAPI 2 / Swagger 2](https://spec.openapis.org/oas/v2.0.html) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\nThe `mediaType` MUST be be set to either `application/json` or `text/yaml`." }, { "const": "openapi-v3", "description": "[OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4.html) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\nThe `mediaType` MUST be be set to either `application/json` or `text/yaml`.\n\nFor OpenAPI 3.1+, `openapi-v3.1+` MUST be used instead, as it's not backward compatible with OpenAPI 3.0." }, { "const": "openapi-v3.1+", "description": "[OpenAPI 3.1+](https://spec.openapis.org/oas/v3.1.1.html) (3.1 or greater, but below 4.x) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\nThe `mediaType` MUST be be set to either `application/json` or `text/yaml`." }, { "const": "raml-v1", "description": "[RAML](https://raml.org/) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs.\nThe `mediaType` MUST be be set to `text/yaml`." }, { "const": "edmx", "description": "[OData](https://www.odata.org/documentation/) APIs can be described via edmx XML files.\nFor OData V2 APIs, this is standardized through the [Common Schema Definition Language (CSDL) V2](https://www.odata.org/documentation/odata-version-2-0/overview/#ServiceMetadataDocument).\nFor OData V4 APIs, this is standardized through the [CSDL XML Representation](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html)\nThe `mediaType` MUST be be set to `application/xml`.\nThe `apiProtocol` MUST be set to `odata-v2` or `odata-v4`." }, { "const": "csdl-json", "description": "[OData](https://www.odata.org/documentation/) V4 APIs can also be described via the\n[OData Common Schema Definition Language (CSDL) JSON Representation](https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html).\nThe `mediaType` MUST be be set to `application/json`.\nThe `apiProtocol` MUST be set to `odata-v2` or `odata-v4`." }, { "const": "graphql-sdl", "description": "[GraphQL](https://graphql.org/) APIs can be described via the [GraphQL Schema Definition Language](https://graphql.org/learn/schema/).\nSee also: [GraphQL Specification > Type System](https://spec.graphql.org/October2021/#sec-Type-System).\nThe `mediaType` MUST be be set to `text/plain`.\nThe `apiProtocol` MUST be set to `graphql`." }, { "const": "wsdl-v1", "description": "[WSDL 1](https://www.w3.org/TR/wsdl.html) API Definition for [SOAP](https://en.wikipedia.org/wiki/SOAP) APIs.\nThe `mediaType` MUST be be set to `application/xml`.\nThe `apiProtocol` MUST be set to `soap-inbound` or `soap-outbound`." }, { "const": "wsdl-v2", "description": "[WSDL 2](https://www.w3.org/TR/2007/REC-wsdl20-20070626/) API Definition for [SOAP](https://en.wikipedia.org/wiki/SOAP) APIs.\nThe `mediaType` MUST be be set to `application/xml`.\nThe `apiProtocol` MUST be set to `soap-inbound` or `soap-outbound`." }, { "const": "a2a-agent-card", "description": "[A2A Agent Card](https://a2a-protocol.org/topics/agent-discovery/) is a machine-readable description of an A2A Agent.\nThe `mediaType` MUST be be set to `application/json`.\nThe `apiProtocol` MUST be set to `a2a`.", "x-introduced-in-version": "1.12.2" }, { "const": "sap-rfc-metadata-v1", "description": "Proprietary metadata description format for [SAP RFC](https://help.sap.com/viewer/753088fc00704d0a80e7fbd6803c8adb/202009.000/en-US/4888068ad9134076e10000000a42189d.html).\nThe `mediaType` MUST be be set to `application/xml`." }, { "const": "sap-sql-api-definition-v1", "description": "Metadata description format for SAP SQL API, following the [SQL interface specification for SAP ecosystem](https://github.com/SAP/sql-interface-specification).\nThe `mediaType` MUST be be set to `application/json`.\nThe `apiProtocol` MUST be set to `sap-sql-api-v1`.", "x-introduced-in-version": "1.9.4" }, { "const": "sap-csn-interop-effective-v1", "description": "[CSN Interop Effective](https://sap.github.io/csn-interop-specification/) is a standardized and interoperable [CSN](https://cap.cloud.sap/docs/cds/csn) export, used to describe [CDS](https://cap.cloud.sap/docs/cds/) models.\nThe `mediaType` MUST be be set to `application/json`.", "x-introduced-in-version": "1.9.4" }, { "const": "custom", "description": "If chosen, `customType` MUST be provided." } ], "examples": [ "openapi-v3" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:custom-definition-format:v1" ] }, "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", "pattern": "^(application|text)\\/[a-zA-Z0-9][a-zA-Z0-9.+\\-]*$", "examples": [ "application/json", "text/plain", "application/xml" ] }, "url": { "type": "string", "format": "uri-reference", "description": "[URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.\n\nIt is RECOMMENDED to provide a relative URL (to base URL).", "examples": [ "/api/openApi.yaml", "https://example.com/api/API_RFQ_PROCESS_SRV/$metadata" ] }, "visibility": { "type": "string", "description": "The visibility states who is allowed to \"see\" and access the resource definition, in case it differs from the resource visibility.\n\nIf not given, the resource definition has the same visibility as the resource it describes.\nThe visibility of a resource definition MUST be lower (more restrictive) than the visibility of the resource it describes.\nE.g. a public resource can have metadata definitions that are internal only. An internal resource can't declare to have a public metadata definition.\n\nThis makes it also possible to provide both a public and an internal metadata description of the resource,\nin case that some metadata must only be made accessible to internal consumers.", "oneOf": [ { "const": "public", "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": "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": "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." } ] }, "accessStrategies": { "type": "array", "description": "List of supported access strategies for retrieving metadata from the ORD provider.\nAn ORD Consumer/ORD Aggregator MAY choose any of the strategies.\n\nThe access strategies only apply to the metadata access and not the actual API access.\nThe actual access to the APIs for clients is described via Consumption Bundles.\n\nIf this property is not provided, the definition URL will be available through the same access strategy as this ORD document.\nIt is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process.", "items": { "$ref": "#/definitions/AccessStrategy" }, "minItems": 1, "examples": [ [ { "type": "open" } ] ] } }, "additionalProperties": false, "required": [ "type", "mediaType", "url" ] }, "EventResourceDefinition": { "type": "object", "title": "Event Resource Definition", "x-ums-type": "custom", "description": "Link and categorization of a machine-readable API definition.\nFor example, AsyncAPI or OpenAPI with callbacks, etc.", "properties": { "type": { "description": "Type of the event resource definition", "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "asyncapi-v2", "description": "[AsyncAPI 2](https://www.asyncapi.com/docs/specifications/2.0.0) API definition for events.\nThe SAP Event Catalog Specification also falls under this category, as it is a valid AsyncAPI definition." }, { "const": "sap-csn-interop-effective-v1", "description": "[CSN Interop Effective](https://sap.github.io/csn-interop-specification/) is a standardized and interoperable flavor of [CSN](https://cap.cloud.sap/docs/cds/csn).\nCSN is a notation for compact representations of [CDS](https://cap.cloud.sap/docs/cds/) models.\n\nIn CDS based frameworks (like ABAP, CAP), APIs and Events are derived from a CDS Service definition and its constituent entities.\nIn this case the original CDS service definition MAY be attached, as it usually contains more metadata insight than other formats.\n\nWARNING: Only expose the CDS Service definition that effectively is governed by the API contract and stability. Do not expose internal models!\n\nThe `mediaType` MUST be be set to `application/json`." }, { "const": "custom", "description": "If chosen, `customType` MUST be provided." } ], "examples": [ "asyncapi-v2" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:custom-definition-format:v1" ] }, "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", "pattern": "^(application|text)\\/[a-zA-Z0-9][a-zA-Z0-9.+\\-]*$", "examples": [ "application/json", "text/plain", "application/xml" ] }, "url": { "type": "string", "format": "uri-reference", "description": "[URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.\n\nIt is RECOMMENDED to provide a relative URL (to base URL).", "examples": [ "/some/url/events/eventCatalog.json" ] }, "accessStrategies": { "type": "array", "description": "List of supported access strategies for retrieving metadata from the ORD provider.\nAn ORD Consumer/ORD Aggregator MAY choose any of the strategies.\n\nThe access strategies only apply to the metadata access and not the actual API access.\nThe actual access to the APIs for clients is described via Consumption Bundles.\n\nIf this property is not provided, the definition URL will be available through the same access strategy as this ORD document.\nIt is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process.", "items": { "$ref": "#/definitions/AccessStrategy" }, "minItems": 1, "examples": [ [ { "type": "open" } ] ] }, "visibility": { "type": "string", "description": "The visibility states who is allowed to \"see\" and access the resource definition, in case it differs from the resource visibility.\n\nIf not given, the resource definition has the same visibility as the resource it describes.\nThe visibility of a resource definition MUST be lower (more restrictive) than the visibility of the resource it describes.\nE.g. a public resource can have metadata definitions that are internal only. An internal resource can't declare to have a public metadata definition.\n\nThis makes it also possible to provide both a public and an internal metadata description of the resource,\nin case that some metadata must only be made accessible to internal consumers.", "oneOf": [ { "const": "public", "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": "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": "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." } ] } }, "additionalProperties": false, "required": [ "type", "mediaType", "url" ] }, "Agent": { "type": "object", "title": "Agent", "x-ums-type": "root", "x-introduced-in-version": "1.14.0", "x-feature-status": "beta", "description": "An **Agent** provides a high-level description of an AI-powered autonomous system that can perform tasks, make decisions, and interact with users or other systems to achieve specific business goals.\n\nAn Agent can relate to specific entity types it works with, declare integration dependencies on external systems it requires, and expose its capabilities through APIs using protocols like A2A (Agent-to-Agent).\n\nAgents enable intelligent automation and decision-making within business processes by providing semantic understanding and context-aware capabilities beyond traditional API-based integrations.\n\nFor more details, see [AI Agents and Protocols](../concepts/ai-agents-and-protocols.md).", "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-]+)*):(agent):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.foo.bar:agent:disputeAgent:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "SuccessFactorsRecruiting", "91cd9972-c05d-4d29-8b6e-dbef2a2d48e9" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:communicationScenario:SAP_COM_0008" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "Dispute Agent" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing." ] }, "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." }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [ "sap.xref:package:SomePackage:v1" ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together." }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "visibility": { "type": "string", "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": "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": "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": "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": "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "disabled": { "type": "boolean", "default": false, "description": "Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so.\nThis can happen either because it has not been setup for use or disabled by an admin / user.\n\nIf the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance-aware perspective.\n\nThis property can only reflect the knowledge of the described system instance itself.\nOutside factors for availability can't need to be considered (e.g. network connectivity, middlewares).\n\nA disabled resource MAY skip describing its resource definitions.\n" }, "minSystemVersion": { "type": "string", "description": "The resource has been introduced in the given [system version](../index.md#system-version).\nThis implies that the resource is only available if the system instance is of at least that system version.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.", "x-introduced-in-version": "1.10.0", "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", "2024.8.0" ] }, "partOfProducts": { "type": "array", "description": "List of products the resources of the Package are a part of.\n\nMUST be a valid reference to a [Product](#product) ORD ID.\n\n`partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "x-association-target": [ "#/definitions/Product/ordId" ] }, "minItems": 0, "examples": [ [ "sap:product:S4HANA_OD:" ] ] }, "responsible": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255, "x-introduced-in-version": "1.8.0", "description": "Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components.", "examples": [ "sap:ach:CIC-DP-CO" ] }, "deprecationDate": { "type": "string", "format": "date-time", "description": "The deprecation date defines when the resource has been set as deprecated.\nThis is not to be confused with the `sunsetDate` which defines when the resource will be actually sunset, aka. decommissioned / removed / archived.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2020-12-08T15:47:04+00:00" ] }, "sunsetDate": { "type": "string", "format": "date-time", "description": "The sunset date defines when the resource is scheduled to be decommissioned / removed / archived.\n\nIf the `releaseStatus` is set to `deprecated`, the `sunsetDate` SHOULD be provided (if already known).\nOnce the sunset date is known and ready to be communicated externally, it MUST be provided here.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2022-01-08T15:47:04+00:00" ] }, "successors": { "type": "array", "description": "The successor resource(s).\n\nMUST be a valid reference to an ORD ID.\n\nIf the `releaseStatus` is set to `deprecated`, `successors` MUST be provided if one exists.\nIf `successors` is given, the described resource SHOULD set its `releaseStatus` to `deprecated`.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(agent):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Agent/ordId" ], "maxLength": 255 } }, "changelogEntries": { "type": "array", "description": "Contains changelog entries that summarize changes with special regards to version and releaseStatus", "items": { "$ref": "#/definitions/ChangelogEntry" } }, "policyLevels": { "type": "array", "description": "A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with.\nFor each chosen policy level, additional expectations and validations rules will be applied.\n\nPolicy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level.\n\nA policy level MUST be a valid [Specification ID](../index.md#specification-id).", "x-introduced-in-version": "1.9.9", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:core:v1" ] } }, "countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "List of countries that the Package resources are applicable to.\n\nMUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).\n\n`countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "DE", "US" ] ] }, "lineOfBusiness": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Asset Management" }, { "const": "Commerce" }, { "const": "Finance" }, { "const": "Human Resources" }, { "const": "Manufacturing" }, { "const": "Marketing" }, { "const": "R&D Engineering" }, { "const": "Sales" }, { "const": "Service" }, { "const": "Sourcing and Procurement" }, { "const": "Strategy, Compliance, and Governance" }, { "const": "Supply Chain" }, { "const": "Sustainability" }, { "const": "Metering" }, { "const": "Grid Operations and Maintenance" }, { "const": "Plant Operations and Maintenance" }, { "const": "Maintenance and Engineering" } ] }, "description": "List of line of business tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Sales" ] ] }, "industry": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/& ]*$", "minLength": 1, "anyOf": [ { "type": "string" }, { "const": "Aerospace and Defense" }, { "const": "Agribusiness" }, { "const": "Automotive" }, { "const": "Banking" }, { "const": "Chemicals" }, { "const": "Consumer Industries" }, { "const": "Consumer Products" }, { "const": "Defense and Security" }, { "const": "Discrete Industries" }, { "const": "Energy and Natural Resources" }, { "const": "Engineering Construction and Operations" }, { "const": "Financial Services" }, { "const": "Future Cities" }, { "const": "Healthcare" }, { "const": "High Tech" }, { "const": "Higher Education and Research" }, { "const": "Industrial Machinery and Components" }, { "const": "Insurance" }, { "const": "Life Sciences" }, { "const": "Media" }, { "const": "Mill Products" }, { "const": "Mining" }, { "const": "Oil and Gas" }, { "const": "Professional Services" }, { "const": "Public Sector" }, { "const": "Public Services" }, { "const": "Retail" }, { "const": "Service Industries" }, { "const": "Sports and Entertainment" }, { "const": "Telecommunications" }, { "const": "Travel and Transportation" }, { "const": "Utilities" }, { "const": "Wholesale Distribution" } ] }, "description": "List of industry tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\n`industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "Automotive" ], [ "Retail", "Public Sector" ], [] ] }, "relatedEntityTypes": { "type": "array", "description": "Optional list of related EntityType Resources.\n\nMUST be a valid reference to an [EntityType Resource](#entity-type) ORD ID.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/EntityType/ordId" ] }, "examples": [ [ "sap.odm:entityType:WorkforcePerson:v1" ] ] }, "exposedApiResources": { "type": "array", "description": "Optional list of API Resources that expose the functionality of the agent. Typically using the A2A protocol, but other protocols are possible as well.\n\nMUST be a valid reference to an [API Resource](#api-resource) ORD ID.", "items": { "$ref": "#/definitions/ExposedApiResourcesTarget" }, "examples": [ [ { "ordId": "sap.foo:apiResource:DisputeResolutionAgent:v1" } ] ] }, "integrationDependencies": { "type": "array", "description": "Optional list of integration dependencies that the agent relies on.\n\nMUST be a valid reference to an [Integration Dependency](#integration-dependency) ORD ID.", "items": { "type": "string", "pattern": "^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(integrationDependency):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "x-association-target": [ "#/definitions/IntegrationDependency/ordId" ] }, "examples": [ [ "sap.foo.bar:integrationDependency:DisputeCaseManagement:v1" ] ] }, "links": { "type": "array", "description": "Generic Links with arbitrary meaning and content.", "items": { "$ref": "#/definitions/Link" } }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" } }, "additionalProperties": false, "required": [ "ordId", "title", "version", "releaseStatus", "visibility", "partOfPackage" ], "x-recommended": [ "lastUpdate" ] }, "Product": { "type": "object", "title": "Product", "x-ums-type": "root", "description": "A [**Product**](../concepts/grouping-and-bundling#product) in ORD is understood as a software product or service offering (whether commercial or free).\n\nIt is a high-level entity for structuring the software portfolio from a portfolio / software logistics perspective.\nWhile **system type** is a technical concept, **product** covers the portfolio and marketing view.\n\nPlease note that the ORD concept of a product is very simple on purpose.\nThere is no distinction between products and services and concepts like product versions, variants, etc.\n\nORD assumes that this is handled by specialized systems and that ORD only provides the means to correlate to them.\n\nTo learn more about the concept, see [Product](../concepts/grouping-and-bundling#product).", "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]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "examples": [ "sap:product:S4HANA_OD:" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.xref:product:ABC" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "The next generation digital core designed to help you run simple in a digital economy." ] }, "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": [] }, "vendor": { "type": "string", "description": "Vendor / organization that is responsible for the Product.\n\nMUST be a valid reference to a [Vendor](#vendor) ORD ID.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\\-]+):()$", "maxLength": 256, "x-association-target": [ "#/definitions/Vendor/ordId" ], "examples": [ "sap:vendor:SAP:", "customer:vendor:Customer:", "microsoft:vendor:Microsoft:" ] }, "parent": { "type": "string", "description": "Optional product parent ORD ID, if a hierarchical product structure needs to be expressed.\n\nMUST be a valid reference to a [Product](#product) ORD ID.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\\-]+):()$", "x-association-target": [ "#/definitions/Product/ordId" ], "examples": [ "sap:product:S4HANA_OD:" ] }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" } }, "additionalProperties": false, "required": [ "ordId", "title", "shortDescription", "vendor" ] }, "Capability": { "type": "object", "title": "Capability", "x-ums-type": "root", "x-introduced-in-version": "1.4.0", "description": "Capabilities can be used to describe use case specific capabilities, most notably supported features or additional information (like configuration) that needs to be understood from outside.\nThis is a generic ORD concept that aims to cover many different capability discovery use cases that would otherwise need be implemented as individual service provider interfaces (SPIs).\n\nIf a capability needs to expose more information than possible with generic capability properties, a custom capability definition can be defined and referenced in ORD.\nThis is the same idea and mechanism as with API resources and their resource definition formats.", "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" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "SuccessFactorsRecruiting", "91cd9972-c05d-4d29-8b6e-dbef2a2d48e9" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:communicationScenario:SAP_COM_0008" ] ] }, "type": { "description": "Type of the Capability", "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "sap.mdo:mdi-capability:v1", "description": "Capability for SAP Master Data Integration (MDI).\n\nFor the capability definitions: `type` MUST ONLY be set to `sap.mdo:mdi-capability-definition:v1`." }, { "const": "custom", "description": "If chosen, `customType` MUST be provided." } ], "examples": [ "custom" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:custom-definition-format:v1" ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "MDI Capability" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing." ] }, "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." }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [ "sap.xref:package:SomePackage:v1" ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together." }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "visibility": { "type": "string", "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": "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": "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": "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": "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "disabled": { "type": "boolean", "default": false, "description": "Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so.\nThis can happen either because it has not been setup for use or disabled by an admin / user.\n\nIf the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance-aware perspective.\n\nThis property can only reflect the knowledge of the described system instance itself.\nOutside factors for availability can't need to be considered (e.g. network connectivity, middlewares).\n\nA disabled resource MAY skip describing its resource definitions.\n" }, "minSystemVersion": { "type": "string", "description": "The resource has been introduced in the given [system version](../index.md#system-version).\nThis implies that the resource is only available if the system instance is of at least that system version.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.", "x-introduced-in-version": "1.10.0", "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", "2024.8.0" ] }, "relatedEntityTypes": { "type": "array", "description": "Optional list of related EntityType Resources.\nMUST be a valid reference to an [EntityType Resource](#entity-type) ORD ID.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/EntityType/ordId" ] }, "examples": [ [ "sap.odm:entityType:WorkforcePerson:v1" ] ] }, "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 entity.", "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 entity.", "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.", "items": { "$ref": "#/definitions/CapabilityDefinition" } }, "links": { "type": "array", "description": "Generic Links with arbitrary meaning and content.", "items": { "$ref": "#/definitions/Link" } }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" }, "systemInstanceAware": { "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 ] } }, "additionalProperties": false, "required": [ "ordId", "type", "title", "version", "releaseStatus", "visibility", "partOfPackage" ], "x-recommended": [ "lastUpdate" ] }, "CapabilityDefinition": { "type": "object", "title": "Capability Definition", "x-introduced-in-version": "1.4.0", "x-ums-type": "custom", "description": "Link and categorization of a machine-readable capability definition.", "properties": { "type": { "description": "Type of the capability resource definition", "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "sap.mdo:mdi-capability-definition:v1", "description": "Specification for describing master data integration capabilities for Master Data Orchestration (MDO).\n\nThe `mediaType` MUST be set to `application/json`.\nThe capability `type` MUST be set to `sap.mdo:mdi-capability:v1`." }, { "const": "custom", "description": "If chosen, a custom type MUST be provided via `customType`" } ], "examples": [ "custom" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:custom-definition-format:v1" ] }, "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", "pattern": "^(application|text)\\/[a-zA-Z0-9][a-zA-Z0-9.+\\-]*$", "examples": [ "application/json", "text/plain", "application/xml" ] }, "url": { "type": "string", "format": "uri-reference", "description": "[URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file.\n\nIt is RECOMMENDED to provide a relative URL (to base URL).", "examples": [ "/capabilities/someCapability/someDocument.json" ] }, "accessStrategies": { "type": "array", "description": "List of supported access strategies for retrieving metadata from the ORD provider.\nAn ORD Consumer/ORD Aggregator MAY choose any of the strategies.\n\nThe access strategies only apply to the metadata access and not the actual API access.\nThe actual access to the APIs for clients is described via Consumption Bundles.\n\nIf this property is not provided, the definition URL will be available through the same access strategy as this ORD document.\nIt is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process.", "items": { "$ref": "#/definitions/AccessStrategy" }, "minItems": 1, "examples": [ [ { "type": "open" } ] ] }, "visibility": { "type": "string", "description": "The visibility states who is allowed to \"see\" and access the resource definition, in case it differs from the resource visibility.\n\nIf not given, the resource definition has the same visibility as the resource it describes.\nThe visibility of a resource definition MUST be lower (more restrictive) than the visibility of the resource it describes.\nE.g. a public resource can have metadata definitions that are internal only. An internal resource can't declare to have a public metadata definition.\n\nThis makes it also possible to provide both a public and an internal metadata description of the resource,\nin case that some metadata must only be made accessible to internal consumers.", "oneOf": [ { "const": "public", "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": "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": "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." } ] } }, "additionalProperties": false, "required": [ "type", "mediaType", "url" ] }, "IntegrationDependency": { "type": "object", "title": "Integration Dependency", "x-ums-type": "root", "x-introduced-in-version": "1.7.0", "description": "An [Integration Dependency](../concepts/integration-dependency) states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose.\nThe purpose could be to enable a certain feature or integration scenario, but it could also be a mandatory prerequisite for the described system to work.\n\nThe integration dependency includes a list of individual **aspects** that the integration consists of.\nAspects are an \"ingredient\" for the integration scenario (and are logically combined with AND condition).\nEach aspect can express alternatives (OR condition) on what API and event resources can be used to achieve the same outcome.\n\nThe direction of connection establishment, data flow is not directly implied and needs to be inferred from the referenced resources.\n\nIt is not in scope for the Integration Dependency to describe scenarios that external consumers have with the own exposed resources.\nThis would overstep the boundary of self-description.\n\nIf an integration scenario consists of two sides integration with each other, each need to describe its own part in it as an Integration Dependency.\nTherefore, if an integration with multiple types of systems need to be setup, this SHOULD be separated into distinct Integration Dependencies.\n\nAn integration dependency is also not meant to describe a bigger process.\nInstead it focuses on the technical necessaries to create an integration for one particular purpose.\n\nTo learn more about the concept, see [Integration Dependency](../concepts/integration-dependency).", "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]+)*):(integrationDependency):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.foo.bar:integrationDependency:CustomerOrder:v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [ "SuccessFactorsRecruiting", "91cd9972-c05d-4d29-8b6e-dbef2a2d48e9" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:communicationScenario:SAP_COM_0008" ] ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "Integration Dependency to realize Customer Order data product" ] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing." ] }, "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." }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [ "sap.xref:package:SomePackage:v1" ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together." }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "visibility": { "type": "string", "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": "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": "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": "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": "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "sunsetDate": { "type": "string", "format": "date-time", "description": "The sunset date defines when the resource is scheduled to be decommissioned / removed / archived.\n\nIf the `releaseStatus` is set to `deprecated`, the `sunsetDate` SHOULD be provided (if already known).\nOnce the sunset date is known and ready to be communicated externally, it MUST be provided here.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2022-01-08T15:47:04+00:00" ] }, "successors": { "type": "array", "description": "The successor resource(s).\n\nMUST be a valid reference to an ORD ID.\n\nIf the `releaseStatus` is set to `deprecated`, `successors` MUST be provided if one exists.\nIf `successors` is given, the described resource SHOULD set its `releaseStatus` to `deprecated`.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "x-association-target": [ "#/definitions/IntegrationDependency/ordId" ] }, "examples": [ [ "sap.foo.bar:integrationDependency:CustomerOrder:v2" ] ] }, "mandatory": { "type": "boolean", "description": "If true, the Integration Dependency is mandatory for the described system to function." }, "aspects": { "type": "array", "description": "List of integration aspects that make up the Integration Dependency.\n\nEach aspect listed is a dedicated, constituent part (AND condition).", "items": { "$ref": "#/definitions/IntegrationAspect" } }, "relatedIntegrationDependencies": { "type": "array", "description": "If an Integration Dependency conceptually belongs or related to another Integration Dependency, this can be indicated here.\nOne situation would be where two systems each have an Integration Dependency to describe a two-sided integration from each side.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/IntegrationDependency/ordId" ] }, "examples": [ [ "sap.foo.bar:integrationDependency:SomethingRelated:v1" ] ] }, "links": { "type": "array", "description": "Generic Links with arbitrary meaning and content.", "items": { "$ref": "#/definitions/Link" } }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" } }, "additionalProperties": false, "required": [ "ordId", "title", "version", "releaseStatus", "visibility", "partOfPackage", "mandatory" ] }, "IntegrationAspect": { "type": "object", "title": "Aspect", "x-introduced-in-version": "1.7.0", "x-ums-type": "custom", "description": "An (integration) aspect is the constituent part that makes up an Integration Dependency.\n\nEach aspect can list references to resources, which could be owned and defined by the integration target or by the described system itself.\nIn case the reference links to own resources, it is implied that they are to be used by the integration target to fulfill the Integration Dependency.\n\nIf multiple resources are given within an aspect, they are considered alternatives to each other (OR condition).\nIn case an AND condition is needed, multiple aspects need to be added to the Integration Dependency.", "properties": { "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "Integration Aspect to get Customer Order data" ] }, "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." }, "mandatory": { "type": "boolean", "description": "If true, the aspect is mandatory to realize the Integration Dependency it contains." }, "supportMultipleProviders": { "type": "boolean", "description": "If true, the references resources can be provided by multiple system instances.\nIf not, only one integration target is supported." }, "apiResources": { "type": "array", "description": "List of API Resource Dependencies.", "items": { "$ref": "#/definitions/ApiResourceIntegrationAspect" } }, "eventResources": { "type": "array", "description": "List of Event Resource Dependencies.", "items": { "$ref": "#/definitions/EventResourceIntegrationAspect" } }, "capabilities": { "type": "array", "description": "List of Capability Dependencies.", "items": { "$ref": "#/definitions/CapabilityIntegrationAspect" } } }, "additionalProperties": false, "required": [ "title", "mandatory" ] }, "ApiResourceIntegrationAspect": { "type": "object", "title": "Api Resource Integration Aspect", "x-introduced-in-version": "1.7.0", "x-ums-type": "custom", "description": "API resource 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]+)*):(apiResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV: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" ] }, "subset": { "type": "array", "description": "List of individual API operations that are sufficient to achieve the aspect.", "items": { "$ref": "#/definitions/ApiResourceIntegrationAspectSubset" } } }, "additionalProperties": false, "required": [ "ordId" ] }, "EventResourceIntegrationAspect": { "type": "object", "title": "Event Resource Integration Aspect", "x-introduced-in-version": "1.7.0", "x-ums-type": "custom", "description": "Event resource 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]+)*):(eventResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents: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" ] }, "subset": { "type": "array", "description": "List of individual events or messages that are sufficient to achieve the aspect.", "items": { "$ref": "#/definitions/EventResourceIntegrationAspectSubset" } }, "systemTypeRestriction": { "type": "array", "description": "In case that the event subscriptions are limited to known [system types](../index.md#system-type), they can be listed here as [system namespaces](../index.md#system-namespace).\n\nIf given, only system types of the defined namespaces are supported as integration partners.\nIf not given, there is no restriction which system type provides the events.", "items": { "type": "string", "description": "Valid [system namespace](../index.md#system-namespace).\n", "pattern": "^[a-z0-9]+(?:[.][a-z0-9]+){1}$" }, "minItems": 1, "examples": [ [ "sap.s4" ] ] } }, "additionalProperties": false, "required": [ "ordId" ] }, "EventResourceIntegrationAspectSubset": { "type": "object", "title": "Event Resource Integration Aspect Subset", "x-introduced-in-version": "1.7.0", "x-ums-type": "custom", "description": "Defines that Event Resource Integration Aspect only requires a subset of the referenced contract.\n\nFor events, this could be a list of the events that need to be subscribed in order to make the integration work.\nThis information helps to narrow down what is really necessary and can help optimize the integration, e.g. by only publishing the events that are really needed.", "properties": { "eventType": { "type": "string", "description": "The type ID of the individual event or message.\n\nThis MUST be an ID that is understood by the used protocol and resource definition format.\nE.g. for CloudEvents, the [type](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) can be used.", "examples": [ "sap.cic.Order.OrderTransferred.v1" ] } }, "additionalProperties": false, "required": [ "eventType" ] }, "ApiResourceIntegrationAspectSubset": { "type": "object", "title": "API Resource Integration Aspect Subset", "x-introduced-in-version": "1.10.0", "x-ums-type": "custom", "description": "Defines that API Resource Integration Aspect only requires a subset of the referenced contract.\n\nFor APIs, this is a list of the operations or tools that need to be available in order to make the integration work.\nThis information helps to narrow down what is really necessary and can help optimize the integration.", "properties": { "operationId": { "type": "string", "description": "The ID of the individual API operation or tool.\n\nThis MUST be an ID that is understood by the used protocol and resource definition format.\nE.g. for OpenAPI this is the `operationId`, for MCP this is the tool `name`.", "examples": [ "getOrderById", "createCustomer" ] } }, "additionalProperties": false, "required": [ "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", "x-ums-type": "root", "description": "The vendor of a product or a package, usually a corporation or a customer / user.\n\nThe vendor of a `Package` is the owner or creator of the content of the package.\nThe vendor of a `Product` is the owner of the product.\n\nIf the resources are created by the customer / user of the described system, `customer:vendor:Customer:` MUST be used as vendor.\n\nBoth have already a [vendor namespace](../index.md#vendor-namespace) within their ORD ID.\nThe `Vendor` entity is giving more details on the vendor namespace.\nFor one vendor namespace there MUST only be exactly one `Vendor` ORD entity describing it.\n\nFor example: The only correct value for a SAP vendor reference is `sap:vendor:SAP:`.", "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]+):(vendor):([a-zA-Z0-9._\\-]+):()$", "maxLength": 255, "examples": [ "sap:vendor:SAP:", "customer:vendor:Customer:", "microsoft:vendor:Microsoft:" ] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [ "SAP" ] }, "partners": { "type": "array", "description": "Optional list of partner vendors, referenced through their ORD ID.\n\nMUST be a valid reference to a [Vendor](#vendor) ORD ID.\n\nThis property can be used to indicate partnership relations between vendors.", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\\-]+):()$", "x-association-target": [ "#/definitions/Vendor/ordId" ] }, "examples": [ [ "microsoft:vendor:Microsoft:" ] ] }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" } }, "additionalProperties": false, "required": [ "ordId", "title" ] }, "ChangelogEntry": { "type": "object", "title": "Changelog Entry", "description": "A changelog entry can be used to indicate changes.\nUsually they lead to a change of the version number or the release status.", "x-ums-type": "custom", "properties": { "version": { "type": "string", "minLength": 1, "description": "Full version number that corresponds to the `version` that is described by the changelog entry.\n\nIdeally it follows the [Semantic Versioning 2.0.0](https://semver.org/) standard,\nbut since it should reflect the actual version string / scheme used, this is not a mandatory requirement.", "examples": [ "1.2.3" ] }, "releaseStatus": { "type": "string", "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "date": { "type": "string", "format": "date", "description": "Date of change, without time or timezone information.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2020-04-29" ] }, "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": [ "## Changelog\n..." ] }, "url": { "type": "string", "format": "uri", "description": "Optional [URL](https://tools.ietf.org/html/rfc3986) that links to a more detailed changelog entry.\n\nThe link target MUST be absolute and SHOULD be openly accessible." } }, "additionalProperties": false, "required": [ "version", "releaseStatus", "date" ] }, "Link": { "type": "object", "title": "Link", "description": "Link that can be attached to packages or Open Resource Discovery resources.\n", "x-ums-type": "custom", "properties": { "title": { "type": "string", "minLength": 1, "description": "Human readable title of the link.\n\nMUST be unique within the collection of links provided.", "examples": [ "APIs for SAP S/4HANA" ] }, "url": { "type": "string", "format": "uri", "description": "[URL](https://tools.ietf.org/html/rfc3986) of the link.\n\nThe link target MUST be absolute and SHOULD be openly accessible.", "examples": [ "https://blogs.sap.com/2018/04/11/testing-of-s4hana-inventory-management-odata-apis-via-sap-api-hub/" ] }, "description": { "type": "string", "minLength": 1, "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" ] } }, "required": [ "title", "url" ], "examples": [ { "url": "https://blogs.sap.com/2018/04/11/testing-of-s4hana-inventory-management-odata-apis-via-sap-api-hub/", "title": "APIs for SAP S/4HANA", "description": "This gives you an overview on where to find which kind of APIs in SAP S/4HANA." } ] }, "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", "x-ums-type": "custom", "description": "Links with specific semantic meaning that are related to `Package`.\n\nIf a generic [Link](#link) can also be expressed via a Package Link, the latter MUST be chosen.", "properties": { "type": { "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "terms-of-service", "description": "Link to human-readable terms of service / use documentation." }, { "const": "license", "description": "Link to human-readable license documentation" }, { "const": "client-registration", "description": "Links to a resource where a client may register to use the package" }, { "const": "payment", "description": "Links to a resource detailing pricing details of the package" }, { "const": "sandbox", "description": "Links to a sandbox environment" }, { "const": "service-level-agreement", "description": "Links to a resource detailing the Service Level Agreement relating to the package.\nThis may be machine- or human-readable." }, { "const": "support", "description": "Links to a resource where a client may obtain support for the package" }, { "const": "custom", "description": "If chosen, `customType` MUST be provided." } ], "examples": [ "terms-of-service" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:custom-definition-format:v1" ] }, "url": { "type": "string", "format": "uri", "description": "[URL](https://tools.ietf.org/html/rfc3986) to the PackageLink.\n\nThe link target MUST be absolute and SHOULD be openly accessible.", "examples": [ "https://accounts.sap.com/ui/public/showRegisterForm?spName=https://netweaver.ondemand.com&targetUrl=https://cloudintegration.hana.ondemand.com" ] } }, "required": [ "type", "url" ], "examples": [ { "type": "terms-of-service", "url": "https://www.sap.com/corporate/en/legal/terms-of-use.html" } ] }, "APIEventResourceLink": { "type": "object", "title": "Api and Event Resource Link", "x-ums-type": "custom", "description": "Links with specific semantic meaning that are related to API or event resources.\n\nIf a generic [Link](#link) can also be expressed via an API / Event Resource Link, the latter MUST be chosen.", "properties": { "type": { "type": "string", "description": "See also: [WADG0001 WebAPI type extension](https://webapi-discovery.github.io/rfcs/rfc0001.html#webapiactions)", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "api-documentation", "description": "Link to human-readable documentation describing the API or event resource in more detail." }, { "const": "authentication", "description": "Links to a resource detailing authentication requirements.\nNote that this is a human-readable resource, not an authentication endpoint." }, { "const": "client-registration", "description": "Links to a resource where a client may register to use the API or event resource." }, { "const": "console", "description": "Links to an interactive console where API calls or events may be tested." }, { "const": "payment", "description": "Links to a resource detailing pricing details of the API or event resource." }, { "const": "service-level-agreement", "description": "Links to a resource detailing the Service Level Agreement relating to the API or event resource.\nThis may be machine- or human-readable." }, { "const": "support", "description": "Links to a resource where a client may obtain support for the API or event resource." }, { "const": "custom", "description": "If chosen, `customType` MUST be provided." } ], "examples": [ "console" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:custom-definition-format:v1" ] }, "url": { "type": "string", "format": "uri-reference", "description": "[URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the API or Event Resource Link.\n\nThe link target SHOULD be absolute and SHOULD be openly accessible.\nIf a relative link is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl).", "examples": [ "https://example.com/some/absolute/url", "/some/relative/url" ] } }, "additionalProperties": false, "required": [ "url", "type" ], "examples": [ { "type": "api-documentation", "url": "https://api.sap.com/api/API_OPLACCTGDOCITEMCUBE_SRV/resource" } ] }, "DataProductLink": { "type": "object", "title": "Data Product Link", "x-ums-type": "custom", "description": "Links with specific semantic meaning that are related to Data Product resources.\nIf a generic [Link](#link) can also be expressed via Data Product Link, the latter MUST be chosen.", "properties": { "type": { "type": "string", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id)." }, { "const": "payment", "description": "Links to a resource detailing pricing details of the data product." }, { "const": "terms-of-use", "description": "Set of legal guidelines or contractual agreement that outline how a user can access, utilize, and share data\nprovided through a specific data product, essentially defining the permitted and prohibited actions when interacting with,\nprocessing or storing data, often including details about privacy, security, and potential limitations\non data usage depending on the specific data product and its intended purposes." }, { "const": "service-level-agreement", "description": "Links to a resource detailing the Service Level Agreement relating to the data product.\nThis may be machine- or human-readable." }, { "const": "support", "description": "Links to a resource where a client may obtain support for the data product." }, { "const": "custom", "description": "If chosen, `customType` MUST be provided." } ], "examples": [ "support" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap:custom-definition-format:v1" ] }, "url": { "type": "string", "format": "uri-reference", "description": "[URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the Data Product Link.\n\nThe link target SHOULD be absolute and SHOULD be openly accessible.\nIf a relative link is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl).", "examples": [ "https://example.com/some/absolute/url" ] } }, "additionalProperties": false, "required": [ "url", "type" ], "examples": [ { "type": "support", "url": "https://support.sap.com/CIC_DP_RT/issue/" } ] }, "SystemInstance": { "type": "object", "title": "System Instance", "x-ums-type": "ignore", "description": "A [system instance](../index.md#system-instance) is a concrete, running instance of a system type.\nIn a multi-tenant system, it corresponds to a tenant.\nIn a single-tenant system, it corresponds to the [system deployment](../index.md#system-deployment) itself.", "properties": { "baseUrl": { "type": "string", "format": "uri-reference", "description": "Optional [base URL](../index.md#base-url) of the **system instance**.\nBy providing the base URL, relative URLs in the document are resolved relative to it.\n\nThe `baseUrl` MUST not contain a leading slash.\n\nMUST be provided if the base URL is not known to the ORD aggregators.\nMUST be provided when the document needs to be fully self contained, e.g. when used for manual imports.", "pattern": "^http[s]?:\\/\\/[^:\\/\\s]+\\.[^:\\/\\s\\.]+(:\\d+)?(\\/[a-zA-Z0-9-\\._~]+)*$", "examples": [ "https://example-sap-system.com", "https://sub.foo.bar.com", "https://sub.foo.bar.com/api/v1" ] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "Optional local ID for the system instance, as known by the described system.\n\nIn case of multi-tenant systems, it is equivalent to the local tenant id.", "maxLength": 255, "examples": [ "LocalTenantId123" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.cld:tenant:741234567" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] } }, "additionalProperties": false }, "SystemType": { "type": "object", "title": "System Type", "description": "A [system type](../index.md#system-type) is the abstract type of an application or service, from operational perspective.", "x-ums-type": "ignore", "properties": { "systemNamespace": { "type": "string", "description": "The [system namespace](../index.md#system-namespace) is a unique identifier for the system type.\nIt is used to reference the system type in the ORD.", "pattern": "^[a-z0-9]+(?:[.][a-z0-9]+){1}$", "maxLength": 32, "examples": [ "sap.s4", "sap.c4c", "sap.cld" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.cld:systemRole:S4_PC" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] } }, "additionalProperties": false }, "SystemVersion": { "type": "object", "title": "System Version", "description": "A [system version](../index.md#system-version) states the design-time version / release of a [system instance](../index.md#system-instance).\nIt provides versioning for operational purposes for the [system type](../index.md#system-type).", "x-ums-type": "ignore", "properties": { "version": { "type": "string", "description": "The version of the system instance (run-time) or the version of the described system-version perspective.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\n\nMUST be provided if the ORD document is `perspective`: `system-version`.\n\nFor continuous-delivery systems, the version MAY be fixed to the same value, e.g. `1.0.0`, but be aware that phased rollouts may benefit from a more precise versioning like adding a build number.", "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", "2024.8.0" ] }, "title": { "type": "string", "description": "Human-readable title of the system version.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud 2408" ] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] } }, "additionalProperties": false }, "AccessStrategy": { "type": "object", "title": "Metadata Definition Access Strategy", "description": "Defines the [access strategy](../../spec-extensions/access-strategies/) for accessing the resource definitions.", "x-ums-type": "custom", "properties": { "type": { "type": "string", "description": "Defines the authentication/authorization strategy through which the referenced `resourceDefinitions` are accessible.", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id).\nIf chosen, `customDescription` SHOULD be provided." }, { "const": "open", "description": "The resource definitions are openly accessible and not protected via authentication or authorization.\nPlease find a more detailed documentation [here](../../spec-extensions/access-strategies/open)." }, { "const": "basic-auth", "description": "The resource definitions are protected via generic basic auth.\nPlease find a more detailed documentation [here](../../spec-extensions/access-strategies/basic-auth).", "x-introduced-in-version": "1.12.1" }, { "const": "custom", "description": "If chosen, `customType` MUST be provided.\nIf chosen, `customDescription` SHOULD be provided." } ], "examples": [ "open" ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.xref:open-local-tenant-id:v1" ] }, "customDescription": { "type": "string", "minLength": 1, "description": "Human-readable description about how the access is set up, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nMUST only be provided if `type` is set to `custom`.", "examples": [ "To set up the access to OData APIs, please refer to the [SAP Cloud for Customer OData API](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US) help pages.\"" ] } }, "additionalProperties": false, "required": [ "type" ], "examples": [ { "type": "open" }, { "type": "custom", "customType": "sap.xref:open-local-tenant-id:v1", "customDescription": "Custom description how to use custom access strategy" } ] }, "CredentialExchangeStrategy": { "type": "object", "title": "Credential Exchange Strategy", "x-feature-status": "alpha", "x-ums-type": "custom", "description": "The credential exchange strategy specifies how a set of credentials for a particular usage\nof the APIs in the Consumption Bundle can be obtained.\nUntil a SAP-wide strategy for obtaining such credentials exists and is agreed upon,\nboth LoBs and aggregators (namely Unified Customer Landscape) can define their own strategy specifications.\n\nWhile the actual flow in term of API calls can differ between the different strategies,\nthe end goal would always be the possibility for automatically obtaining credentials for each client\nthat would like to use the APIs from a particular bundle.", "properties": { "type": { "type": "string", "description": "The type of credential exchange strategy.", "anyOf": [ { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "description": "Any valid [Specification ID](../index.md#specification-id).\nIf chosen, `customDescription` SHOULD be provided." }, { "const": "custom", "description": "If chosen, `customType` MUST be provided.\nIf chosen, `customDescription` SHOULD be provided." } ] }, "customType": { "type": "string", "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.xref:credential-exchange:v1" ] }, "customDescription": { "type": "string", "minLength": 1, "description": "Human-readable description about how the credential exchange is achieved, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nMUST only be provided if `type` is set to `custom`.", "examples": [] }, "callbackUrl": { "type": "string", "format": "uri", "description": "[URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the credential exchange callback endpoint.\n\nThis allows requesting a set of credentials that can be used for consuming all the APIs and Events that are part of the bundle.\n\nThe interface contract/protocol is dependent and defined by the chosen `type`.\n\nWhenever a client wants to consume a resource within a particular bundle, this endpoint can be called to obtain the credentials that this client can use.\n\nThe returned credentials MUST be valid for all resources that are part of the respective bundle.\nThe endpoint SHOULD return a different set of credentials on each invocation.", "examples": [ "https://system-instance-1.com/credentials?scenario=SAP_COM_008" ] } }, "additionalProperties": false, "required": [ "type" ] }, "Labels": { "title": "Labels", "type": "object", "description": "Generic key-value labels that can be applied to most ORD information.\nThey are defined as an object that may have arbitrary keys.\nThe value of a key is an array of strings.\n\nLabels can be used to attach technical information that cannot be expressed natively in ORD.\nAn ORD aggregator should allow to categorize and query information based on the labels provided.\n\nTo learn more about the concept, see [Labels](../concepts/grouping-and-bundling#labels).\n\nIf multiple parties rely on the existence of certain label information,\nstandardization through ORD SHOULD be preferred.\n\nAll labels attached to a `Package` will be inherited to the resources they contain.\nDuplicate labels will be merged by the ORD aggregator according to the following rules:\n* Values of the same label key will be merged.\n* Duplicate values of the same label key will be removed.\n\n**RECOMMENDATION**: Use a [Concept ID](../index.md#concept-id) as the label key to indicate ownership and avoid naming conflicts.\nThe namespace in the Concept ID clearly identifies who owns and defines the label's semantics.", "x-ums-type": "custom", "patternProperties": { "^[a-zA-Z0-9-_.]*$": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "examples": [ { "foo.bar:labelKeyName": [ "value" ] }, { "foo.bar:cost-center": [ "CC-12345", "CC-67890" ] } ] }, "GroupType": { "title": "Group Type", "type": "object", "x-ums-type": "root", "description": "A Group Type defines the semantics of [group assignments](#group).\nWhat the Group Type means and how it is to be used correctly SHOULD be described in the `description` (which may include markdown links).\n\nGroup Types can be defined centrally (ownership by authority namespace) or decentrally (defined by application / service itself).\n\nTo learn more about the concept, see [Group Concept Documentation](../concepts/grouping-and-bundling#groups).", "x-introduced-in-version": "1.9.0", "properties": { "groupTypeId": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "description": "GroupType ID, which MUST be a valid [Concept ID](../../spec-v1/#concept-id).", "examples": [ "sap.foo:domain", "sap.cap:service" ] }, "title": { "type": "string", "description": "Human readable title of the group type.", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud" ] }, "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." }, "labels": { "$ref": "#/definitions/Labels" }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:communicationScenario:SAP_COM_0008" ] ] }, "partOfGroupTypes": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/GroupType/groupTypeId" ] }, "description": "A group type can logically be part of another group type, for example in hierarchical taxonomies or graph relationships.\nAssigning a group type to be part of another group type is a lightweight and flexible approach to express such relationships.\n\nThis relationship does not imply inheritance, but can be interpreted as such for specific group types and scenarios." } }, "required": [ "groupTypeId", "title" ], "examples": [ { "groupTypeId": "sap.cds:service", "title": "CAP Service", "description": "Description of the CDS Service concept and how its correctly used for grouping..." } ] }, "Group": { "title": "Group", "type": "object", "x-ums-type": "root", "description": "Group (instance) that resources can be assigned to.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nTo learn more about the concept, see [Group Concept Documentation](../concepts/grouping-and-bundling#groups).", "x-introduced-in-version": "1.9.0", "properties": { "groupId": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "description": "The Group ID consists of two [Concept IDs](../../spec-v1/#concept-id) separated by a `:`.\n\nThe first two fragments MUST be equal to the used Group Type ID (`groupTypeId`).\nThe last two fragments MUST be a valid [Concept ID](../../spec-v1/#concept-id), indicating the group instance assignment.\n\nThe ID concept is a bit unusual, but it ensures globally unique and conflict-free group assignments.", "examples": [ "sap.foo:domain:sap.foo:DomainName" ] }, "groupTypeId": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "description": "Group Type ID.\n\nMUST match with the first two fragments of the own `groupId`.", "examples": [ "sap.foo:domain", "sap.cap:service" ], "x-association-target": [ "#/definitions/GroupType/groupTypeId" ] }, "title": { "type": "string", "description": "Human readable title of the group assignment (for UI).", "minLength": 1, "maxLength": 255, "examples": [ "SAP S/4HANA Cloud" ] }, "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." }, "labels": { "$ref": "#/definitions/Labels" }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [ [ "sap.s4:communicationScenario:SAP_COM_0008" ] ] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "A group (instance) can logically be part of another group, for example in hierarchical taxonomies or graph relationships.\nAssigning a group to be part of another group is a lightweight and flexible approach to express such relationships.\n\nThis relationship does not imply inheritance, but can be interpreted as such for specific group types and scenarios.", "x-feature-status": "beta", "x-introduced-in-version": "1.13.0" } }, "required": [ "groupId", "groupTypeId", "title" ], "examples": [ { "groupId": "sap.cap:service:customer.incidents:incidents.IncidentsService", "groupTypeId": "sap.cap:service", "title": "Incidents Service" } ] }, "DocumentationLabels": { "title": "Documentation Labels", "type": "object", "description": "Generic documentation labels that can be applied to most ORD information.\nThey are defined as an object that may have arbitrary keys.\nThe value of a key is an array of [CommonMark](https://spec.commonmark.org/) (Markdown) text.\n\nDocumentation Labels can be used to attach human readable documentation that cannot be expressed natively in ORD.\nA documentation tool (like an API Catalog) can use the documentation labels to provide generic documentation \"snippets\".\nDue to the given structure they can be displayed e.g. as tables.\n\nThe key of the documentation Label is plain-text (MUST not contain line breaks) and denotes the subject matter that is described.\nThe values (multiple can be provided for the same key) are [CommonMark](https://spec.commonmark.org/) (Markdown) text\nwhich describes the subject matter or lists options for the key.\n\nIn contrast to regular labels, documentation labels are not meant to be used to categorize or query information.", "x-introduced-in-version": "1.1.0", "x-ums-type": "custom", "patternProperties": { "^.*$": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "examples": [ { "Scope Items": [ "[Basic Bank Account Management (BFA)](https://rapid.sap.com/bp/#/scopeitems/BFA \\\" Link To BP \\\")" ] } ] }, "Extensible": { "title": "Extensible", "type": "object", "x-ums-type": "embedded", "description": "Contains information about the extensibility of this resource.\n\nIf applicable, a description and further resources about extending this resource are provided.", "properties": { "supported": { "type": "string", "enum": [ "no", "manual", "automatic" ], "description": "This property defines whether the resource is extensible.\n\n**Not extensible** means that the data model of the resource (i.e. API or event) cannot be extended with custom fields.\n**Manually extensible** means that in addition to defining a custom field, manual activities to include the field in the data model of the resource (i.e. API or event) are required. E.g. using a specific mapping tool or by selecting the resource in the data model extension tool.\n**Automatically extensible** means that after defining a custom field in the local domain model, the resource (i.e. API or event) is automatically extended as part of the default extension field definition." }, "description": { "type": "string", "minLength": 1, "description": "A description about the extensibility capabilities of this API, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nThis description may contain detailed steps on how to extend the API.\nLinks to external resources can be provided within the description as markdown links.\n\nThis description MUST be provided if `supported` is set to `manual` or `automatic`.", "examples": [ "Please find the extensibility documentation [here](#here)" ] } }, "additionalProperties": false, "required": [ "supported" ], "examples": [ { "supported": "manual", "description": "API can be extended by custom fields on the following business contexts (field usage for this API needs to be selected):\r\n* Procurement: Purchasing Document (MM_PURDOC_HEADER)\r\n* Procurement: Purchasing Document Item (MM_PURDOC_ITEM)\r\n\r\n[How to add an extension field to an API](https://help.sap.com/viewer/9a281eac983f4f688d0deedc96b3c61c/latest/en-US/57909455bf7c4fdd8bcf48d76c1eae33.html)" } ] }, "EntityTypeMapping": { "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": { "apiModelSelectors": { "type": "array", "description": "List of selectors for API models within an API Resource.\nIf multiple selectors are given, every selected API model maps to the entity type target(s).\nIf omitted, the complete API resource will be mapped to the `entityTypeTargets` (less specific).\n\nMultiple selectors can be useful, e.g. with a CRUD REST API, to combine the similar API models.\n\nDepending on the chosen API protocol and the available resource definition formats,\ndifferent kind of selectors need to be used.", "items": { "anyOf": [ { "$ref": "#/definitions/ApiModelSelectorOData" }, { "$ref": "#/definitions/ApiModelSelectorJsonPointer" } ] } }, "entityTypeTargets": { "type": "array", "description": "List of entity types the ORD resource maps to.\nIf `apiModelSelectors` are given, the mapping is more precise by also pointing to the specific model in the API.\n\nIf multiple entity types are defined as the mapping target,\nall of them can be at least partially mapped to the source API model(s).\n\nEntity types can be referenced using either using an [ORD ID](../index.md#ord-id) or a [Correlation ID](../index.md#correlation-id).", "items": { "anyOf": [ { "$ref": "#/definitions/EntityTypeOrdIdTarget" }, { "$ref": "#/definitions/EntityTypeCorrelationIdTarget" } ] }, "minItems": 1 } }, "additionalProperties": false, "required": [ "entityTypeTargets" ] }, "ApiCompatibility": { "title": "API Compatibility", "x-introduced-in-version": "1.13.0", "x-ums-type": "embedded", "type": "object", "description": "Describes the compatibility of the API with other APIs. This can be used to express that an API is compatible with another API version.", "properties": { "ordId": { "type": "string", "description": "ORD ID of the APIResource that serves as contract that this resource is compatible with.\n\nMUST be a valid reference to an (usually external) [API Resource](#api-resource) ORD ID.", "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_BILL_OF_MATERIAL_SRV:v1" ] }, "maxVersion": { "type": "string", "description": "Specifies the maximum version of the interface contract that this resource is compatible with. This is the version, that the resource fully implements and supports.\n\nEven if the interface contract evolves compatible, this resource will not be compatible with versions beyond the specified one. It is important to consider, given the example of an API version 1.0, that has the fields A and B.\nBeing compatible with version 1.0 means to have exactly the fields A and B and potential tenant specific extensions in a dedicated namespace.\nIf an API contract changes to version 1.1 compatible by adding field C, the API declaring compatibility towards 1.0, will miss field C. Only if adopting the contract of 1.1 with having fields A, B, and C, such an API is also\ncompatible with version 1.1 of the contract. However, a client relying on version 1.0 of the contract, can still work with the API being compatible with version 1.1 of the contract.\n\nFollowing the [Semantic Versioning 2.0.0](https://semver.org/) standard, patch versions (x.y.Z) must not have impact on the schema/contract. Therefore, the maxVersion are only the major.minor parts of a semantic version.", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$", "examples": [ "1.2", "2.0" ] } }, "additionalProperties": false, "required": [ "ordId", "maxVersion" ] }, "EventCompatibility": { "title": "Event Compatibility", "x-introduced-in-version": "1.13.0", "x-ums-type": "embedded", "type": "object", "description": "Describes the compatibility of the Event with other Events. This can be used to express that an Event is compatible with another Event version.", "properties": { "ordId": { "type": "string", "description": "ORD ID of the EventResource that serves as contract that this resource is compatible with.\n\nMUST be a valid reference to an (usually external) [Event Resource](#event-resource) ORD ID.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.s4:eventResource:BillofMaterialEvents:v1" ] }, "maxVersion": { "type": "string", "description": "Specifies the maximum version of the interface contract that this resource is compatible with. This is the version, that the resource fully implements and supports.\n\nEven if the interface contract evolves compatible, this resource will not be compatible with versions beyond the specified one. It is important to consider, given the example of an event version 1.0, that has the fields A and B. Being compatible with version 1.0 means to have exactly the fields A and B and potential tenant specific extensions in a dedicated namespace.\nIf an event contract changes to version 1.1 compatible by adding field C, the event declaring compatibility towards 1.0, will miss field C. Only if adopting the contract of 1.1 with having fields A, B, and C, such an event is also\ncompatible with version 1.1 of the contract. However, a client relying on version 1.0 of the contract, can still work with the event being compatible with version 1.1 of the contract.\n\nFollowing the [Semantic Versioning 2.0.0](https://semver.org/) standard, patch versions (x.y.Z) must not have impact on the schema/contract. Therefore, the maxVersion are only the major.minor parts of a semantic version.", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$", "examples": [ "1.2", "2.0" ] } }, "additionalProperties": false, "required": [ "ordId", "maxVersion" ] }, "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`.", "properties": { "type": { "type": "string", "description": "The type for OData selectors is fixed to `odata`.", "enum": [ "odata" ] }, "entitySetName": { "type": "string", "description": "OData entity set name.\n\nAs defined in the EDMX, e.g. ``.", "minLength": 1, "examples": [ "AttachmentContent" ] } }, "additionalProperties": false, "required": [ "type", "entitySetName" ], "examples": [ { "type": "odata", "entitySetName": "AttachmentContent" } ] }, "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`.", "properties": { "type": { "type": "string", "description": "The type for generic JSON Pointer selectors is fixed to `json-pointer`.", "enum": [ "json-pointer" ] }, "jsonPointer": { "type": "string", "description": "JSON Pointer to the entity type schema / description within the resource definition format.\n\nMUST be a valid JSON Pointer according to [RFC6901](https://datatracker.ietf.org/doc/html/rfc6901).\n\nThe JSON pointers MUST point to each instance of the mapped entity type in the resource definition file, BEFORE `$ref` JSON Schema References are resolved (dereferenced).", "minLength": 1, "examples": [ "#/objects/schemas/", "#/components/schemas/sap.odm.sales.CustomerOrder.Placed.v0", "#/objects/schemas//table-oriented/" ] } }, "additionalProperties": false, "required": [ "type", "jsonPointer" ], "examples": [ { "type": "json-pointer", "jsonPointer": "#/objects/schemas/AttachmentContent" } ] }, "ExposedApiResourcesTarget": { "title": "Exposed API Resource", "x-introduced-in-version": "1.14.0", "x-ums-type": "embedded", "type": "object", "description": "Reference to an API Resource that exposes the functionality of an agent.\n\nThis is a complex object to allow additional properties / selections to be attached in the future.", "properties": { "ordId": { "type": "string", "description": "The API Resource ORD ID that this reference points to.\n\nMUST be a valid reference to an [API Resource](#api-resource) ORD ID.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.foo:apiResource:DisputeResolutionAgent:v1" ], "x-association-target": [ "#/definitions/ApiResource/ordId" ] } }, "required": [ "ordId" ], "additionalProperties": false }, "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.", "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]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.odm:entityType:BusinessPartner:v1" ], "x-association-target": [ "#/definitions/EntityType/ordId" ] } }, "required": [ "ordId" ], "additionalProperties": false }, "EntityTypeCorrelationIdTarget": { "title": "Entity Type Target (Correlation Id)", "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": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255, "examples": [ "sap.csnexposure:entity:Attachment" ] } }, "required": [ "correlationId" ], "additionalProperties": false }, "RelatedEntityType": { "title": "Related Entity Type", "x-introduced-in-version": "1.9.0", "x-ums-type": "embedded", "type": "object", "description": "Defines the relation between Entity Types (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]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.odm:entityType:BusinessPartner:v1" ], "x-association-target": [ "#/definitions/EntityType/ordId" ] }, "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\".\n\nMUST be a valid [Concept ID](../index.md#concept-id).", "x-introduced-in-version": "1.12.0", "x-feature-status": "beta", "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`." }, { "const": "can-share-identity", "description": "The related entity types can potentially share the same identity in their instance data / be ID mapped.\n\nE.g. a `BusinessPartner` can share the same identity as a `NaturalPerson`." } ], "examples": [ "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" ] } }, "required": [ "ordId" ], "additionalProperties": false }, "ExposedEntityType": { "title": "Exposed Entity Type", "type": "object", "description": "Defines which Entity Type is exposed through (via its ORD ID).", "x-introduced-in-version": "1.11.0", "x-ums-type": "embedded", "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]+)*):(entityType):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "maxLength": 255, "examples": [ "sap.s4.sot:entityType:BusinessPartner:v1" ], "x-association-target": [ "#/definitions/EntityType/ordId" ] } }, "required": [ "ordId" ], "additionalProperties": false }, "Tombstone": { "type": "object", "title": "Tombstone", "x-ums-type": "ignore", "description": "A tombstone indicates that a previously published ORD resource or taxonomy has been removed / decommissioned / archived.\nThis MUST be indicated explicitly, so ORD aggregators and consumers can learn about the removal.\n\nExactly one of the IDs MUST be provided to state which ORD resource or taxonomy item the Tombstone addresses.\n\nThe tombstone MUST be kept sufficiently long (at least 31 days) so that all ORD aggregators can learn about the tombstone.", "properties": { "ordId": { "type": "string", "description": "[ORD ID](../index.md#ord-id) of the ORD resource/taxonomy that has been removed.", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package|consumptionBundle|product|vendor|apiResource|eventResource|capability|entityType|integrationDependency|dataProduct|agent):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*|)?$", "maxLength": 255, "examples": [ "sap.xref:package:SomePackage:v1" ], "x-association-target": [ "#/definitions/Package/ordId", "#/definitions/ConsumptionBundle/ordId", "#/definitions/Product/ordId", "#/definitions/Vendor/ordId", "#/definitions/ApiResource/ordId", "#/definitions/EventResource/ordId", "#/definitions/Capability/ordId", "#/definitions/EntityType/ordId", "#/definitions/IntegrationDependency/ordId", "#/definitions/DataProduct/ordId", "#/definitions/Agent/ordId" ] }, "groupId": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "description": "Group ID of the group that has been removed.", "examples": [ "sap.foo:domain:sap.foo:DomainName" ], "x-association-target": [ "#/definitions/Group/groupId" ] }, "groupTypeId": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "description": "Group Type ID of the group type that has been removed.", "examples": [ "sap.foo:domain", "sap.cap:service" ], "x-association-target": [ "#/definitions/GroupType/groupTypeId" ] }, "removalDate": { "type": "string", "format": "date-time", "description": "The date when the ORD resource/taxonomy was removed.\nThis is related to the `sunsetDate` that can be set to announce a resource as deprecated *before* the removal and setting of a tombstone.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).", "examples": [ "2020-12-02T14:12:59Z" ] }, "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." } }, "required": [ "removalDate" ], "examples": [ { "ordId": "sap.s4:apiResource:API_RFQ_PROCESS_SRV:v2", "removalDate": "2020-12-02T14:12:59Z" }, { "groupId": "sap.foo:domain:sap.foo:DomainName", "removalDate": "2020-12-02T14:12:59Z" } ] }, "OrdResource": { "type": "object", "title": "Ord Resource (abstract)", "x-ums-type": "root", "description": "Abstract definition of shared properties across ORD Resources.", "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|eventResource|capability|dataProduct|agent):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*|)$", "maxLength": 255, "examples": [] }, "localId": { "type": "string", "x-introduced-in-version": "1.2.1", "description": "The locally unique ID under which this resource can be looked up / resolved in the described system itself.\nUnlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name.\n\nIt MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID.\nBut since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID.", "maxLength": 255, "examples": [] }, "correlationIds": { "type": "array", "description": "Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record).\n\nThey express an \"identity\" / \"equals\" / \"mappable\" relationship to the target ID.\n\nIf a \"part of\" relationship needs to be expressed, use the `partOfGroups` assignment instead.\n\nMUST be a valid [Correlation ID](../index.md#correlation-id).", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$", "maxLength": 255 }, "examples": [] }, "title": { "type": "string", "description": "Human-readable title.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [] }, "shortDescription": { "type": "string", "description": "Plain text short description.\n\nMUST NOT exceed 255 chars.\nMUST NOT contain line breaks.", "minLength": 1, "maxLength": 255, "examples": [] }, "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": [] }, "partOfPackage": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$", "x-association-target": [ "#/definitions/Package/ordId" ], "maxLength": 255, "description": "Defines which Package the resource is part of.\n\nMUST be a valid reference to a [Package](#package) ORD ID.\n\nEvery resource MUST be part of one package.", "examples": [] }, "partOfGroups": { "type": "array", "items": { "type": "string", "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+)$", "x-association-target": [ "#/definitions/Group/groupId" ] }, "description": "Defines which groups the resource is assigned to.\n\nThe property is optional, but if given the value MUST be an array of valid Group IDs.\n\nGroups are a lightweight custom taxonomy concept.\nThey express a \"part of\" relationship to the chosen group concept.\nIf an \"identity / equals\" relationship needs to be expressed, use the `correlationIds` instead.\n\nAll resources that share the same group ID assignment are effectively grouped together.", "examples": [] }, "version": { "type": "string", "description": "The complete [SemVer](https://semver.org/) version string.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.\nIt SHOULD be changed if the ORD information or referenced resource definitions changed.\nIt SHOULD express minor and patch changes that don't lead to incompatible changes.\n\nWhen the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical.\nIn case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies.\n\nIf the resource has been extended by the user, the change MUST be indicated via `lastUpdate`.\nThe `version` MUST not be bumped for changes in extensions.\n\nThe general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed.\n\nNote: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly.\nFor example: If a resource within a `Package` changes, but the Package itself did not, the Package version does not need to be incremented.", "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" ] }, "lastUpdate": { "type": "string", "format": "date-time", "x-introduced-in-version": "1.4.0", "description": "Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened.\n\nThe date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).\n\nWhen retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time.\nTherefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files.\n\nIf the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.\n\nTogether with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.", "examples": [ "2022-12-19T15:47:04+00:00" ] }, "visibility": { "type": "string", "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": "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": "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": "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": "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 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` `releaseStatus` MAY be changed or removed at the provider's discretion." }, { "const": "active", "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": "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.\nIf the `releaseStatus` is set to `deprecated`, and the `sunsetDate` is already known, then the `sunsetDate` 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": "The resource has been decommissioned and is no longer available at runtime. This entry exists for historical reference only.\n\nIf the `releaseStatus` is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided." } ], "examples": [ "active" ] }, "links": { "type": "array", "description": "Generic links with arbitrary meaning and content.\n\n`packageLinks` MUST be preferred if applicable.", "items": { "$ref": "#/definitions/Link" } }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_.\\/ ]*$", "minLength": 1 }, "description": "List of free text style tags.\nNo special characters are allowed except `-`, `_`, `.`, `/` and ` `.\n\nTags that are assigned to a `Package` are inherited to all of the ORD resources it contains.", "examples": [ [ "storage", "high-availability" ] ] }, "labels": { "$ref": "#/definitions/Labels" }, "documentationLabels": { "$ref": "#/definitions/DocumentationLabels" } }, "required": [ "ordId", "title", "description", "version", "visibility", "releaseStatus", "partOfPackage" ], "additionalProperties": true } } }