ORD Document

How to read this documentation

• The root schema of the document is ORD Document

Technical information

• Example files can be found here.
• Visual diagrams can be found here: ORD Document Class Diagram.
• The interface is described as JSON Schema here: /spec-v1/interfaces/Document.schema.json.
• A high-level overview can also be exported as Excel and CSV file.
• This documentation is automatically generated from ./spec/v1/Document.schema.yaml.

Schema Definitions

ORD Document

The ORD Document object serves as a wrapper for the ORD resources and ORD taxonomy and adds further top-level information that are specific to the document/the service it describes.

The constraints and considerations on ORD Documents MUST be followed.

Property	Type	Description
$schema OPTIONAL	string	Optional URL to the Open Resource Discovery document schema (defined as a JSON Schema). If provided, this enables code intelligence and validation in supported editors (like VSCode) and tools. JSON Schema Format: uri-reference Recommended Values: "https://sap.github.io/open-resource-discovery/spec-v1/interfaces/Document.schema.json"
openResourceDiscovery MANDATORY	string	Version of the Open Resource Discovery specification that is used to describe this document. Allowed Values: "1.0": ORD Version 1.0 "1.1": ORD Version 1.1 "1.2": ORD Version 1.2 "1.3": ORD Version 1.3 "1.4": ORD Version 1.4 "1.5": ORD Version 1.5 "1.6": ORD Version 1.6 "1.7": ORD Version 1.7 "1.8": ORD Version 1.8 "1.9": ORD Version 1.9 Example Values: "1.9"
description OPTIONAL	string	Optional description of the ORD document itself. Please note that this information is NOT further processed or considered by an ORD aggregator. Notated in CommonMark (Markdown). Minimum Length: 1 Example Values: "This ORD document contains all APIs that are system instance aware and have APIs that\ncan change their behavior at runtime.\n"
describedSystemInstance OPTIONAL	System Instance	Information on the system instance that this ORD document describes. This information is optional, but RECOMMENDED to add, as it makes the ORD document self contained. The described system instance MUST be identical to the system instance that provides the ORD information.
policyLevel RECOMMENDED	string	The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values: "none": No policy level chosen. Only the base rules on how to create correct ORD documents apply. "sap:base:v1": Basic SAP rules and guidelines apply. This just ensures technical correctness and essential validations. If chosen the SAP Base V1 rules MUST be followed. "sap:core:v1": SAP core rules and guidelines apply. If chosen the SAP Core V1 rules MUST be followed. "custom": Custom policy level. Further validation MAY be defined and implemented by the policy-level owner. This level MAY be chosen by 3rd party or customer solutions. If chosen, customPolicyLevel MUST be provided. Introduced in Version: 1.3.0 Example Values: "sap:core:v1"
customPolicyLevel OPTIONAL	string	If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided. The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom. MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:customPolicy:v1"
apiResources OPTIONAL	Array<API Resource>	Array of all API Resources that are described in this ORD document.
eventResources OPTIONAL	Array<Event Resource>	Array of all event resources that are described in this ORD document.
entityTypes OPTIONAL	Array<Entity Type>	Array of all entity types that are described in this ORD document. Introduced in Version: 1.6.0
capabilities OPTIONAL	Array<Capability>	Array of all capabilities that are described in this ORD document. Introduced in Version: 1.4.0
dataProducts OPTIONAL	Array<Data Product>	Array of all data products that are described in this ORD document. Introduced in Version: 1.8.0
integrationDependencies OPTIONAL	Array<Integration Dependency>	Array of all integration dependencies that are described in this ORD document. Introduced in Version: 1.7.0
vendors OPTIONAL	Array<Vendor>	Array of all Vendors that are described in this ORD document.
products OPTIONAL	Array<Product>	Array of all Products that are described in this ORD document.
packages OPTIONAL	Array<Package>	Array of all Packages that are described in this ORD document.
consumptionBundles OPTIONAL	Array<Consumption Bundle>	Array of all Consumption Bundles that are described in this ORD document.
groups OPTIONAL	Array<Group>	Array of all Groups that are described in this ORD document.
groupTypes OPTIONAL	Array<Group Type>	Array of all Group Types that are described in this ORD document.
tombstones OPTIONAL	Array<Tombstone>	List of ORD information (resources or taxonomy) that have been "tombstoned"/removed. This MUST be indicated explicitly, so that ORD aggregators and consumers can learn about the removal. A tombstone entry MAY be removed after a grace period of 31 days.

API Resource

The API Resource provides a high-level description of an exposed API. You can find more information, such as the API resource definitions, in the links in the table below.

An API Resource bundles multiple endpoints and resources together. They share the same API namespace and lifecycle (API major version). However, the exact granularity of this is up to the implementer of the API. As a consequence, an API resource MUST NOT bundle together endpoints from different API versions or namespaces.

A common practice is to bundle endpoints that are based on the same domain or Business Object.

Please note that APIs can be described, but still be disabled.

If 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 that state this the ownership via the vendor property.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v1"
localId OPTIONAL	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "API_BILL_OF_MATERIAL_SRV"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.xref:csnService:SomeLocalID"]
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "Process Request for Quotation"
shortDescription MANDATORY	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "This service enables you to create Request for Quotation (RFQ) through an API call."
description MANDATORY	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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 MANDATORY	string	Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
partOfGroups OPTIONAL	Array<string>	Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead. All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
partOfConsumptionBundles OPTIONAL	Array<Consumption Bundle Reference>	List of references to the consumption bundles in this resource belongs to. MUST be a valid reference to a Consumption Bundle ORD ID. An API resource SHOULD be associated to one or multiple consumption bundles, if it is of direction inbound or mixed. Some ORD consumer use cases MAY depend on an association to a consumption bundle. If none is given, the resource may not appear as it's unknown how it can be consumed. If a resource has no direct incoming consumption characteristics: - MUST NOT assign consumption bundle to API or Event resources with direction: outbound (no inbound consumption) - MUST NOT assign consumption bundle if resource is not accessible directly, but only via intermediaries like event brokers or gateways. - In this case the intermediary SHOULD describe the consumption bundle instead (potentially also re-describing the resources as well). Example Values: [{"ordId":"sap.xref:consumptionBundle:bundleXYZ:v1"}]
defaultConsumptionBundle OPTIONAL	string	References the default consumption bundle to use for this resource. MUST be a valid reference to a Consumption Bundle ORD ID. Can be used by clients to make a deterministic and preferred choice when multiple options are available. The value MUST be an existing option in the corresponding partOfConsumptionBundles array. Association Target: Consumption Bundle.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:consumptionBundle:bundleXYZ:v1"
partOfProducts OPTIONAL	Array<string>	List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values: ["sap:product:S4HANA_OD:"]
version MANDATORY	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
lastUpdate OPTIONAL	string	Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with systemInstanceAware, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values: "2022-12-19T15:47:04+00:00"
visibility MANDATORY	string	The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values: "public": Resources are publicly accessible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the SAP API Deprecation Policy. "internal": Resources are accessible to other applications within the same organization. However, they are not officially exposed and communicated to customers and 3rd parties. They might not come with the same guarantees on API stability. Internal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog. Internal resources MAY be published through an internal API Catalog if the access permissions are ensured by it. "private": Resources that are exclusively used within an application or service. This includes resources that may be called from outside but serve purely private purposes and are not supposed to be known by other outside parties. E.g., webhooks for provisioning callbacks or backing services. Private resources MUST NOT be made available to public consumers or consumers outside of the "private" scope or without the necessary access permissions.
releaseStatus MANDATORY	string	The releaseStatus specifies the stability of the resource and its external contract. Allowed Values: "active": Resource is meant for productive use and provides a stable API contract. "beta": The contract for the resource is beta and MAY not be meant for productive use. In the SAP context, beta APIs may be changed or deleted at SAPs discretion. "deprecated": Resource has been deprecated. If successor resources exist, they MUST be referenced through successors. If it is deprecated without defining its successors, a sunsetDate SHOULD be provided. A deprecated resource MAY be decommissioned (removed) in the future. This removal MUST be explicitly indicated through a Tombstone. Once the resource is decommissioned, it MUST be removed from ORD. Example Values: "active"
disabled OPTIONAL	boolean	Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. This can happen either because it has not been setup for use or disabled by an admin / user. If 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. This property can only reflect the knowledge of the described system instance itself. Outside factors for availability can't need to be considered (e.g. network connectivity, middlewares). A disabled resource MAY skip describing its resource definitions.
deprecationDate OPTIONAL	string	The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed. If the releaseStatus is set to deprecated, the deprecationDate SHOULD be provided. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2020-12-08T15:47:04+00:00"
sunsetDate OPTIONAL	string	The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated, the sunsetDate SHOULD be provided (if already known). Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2022-01-08T15:47:04+00:00"
successors OPTIONAL	Array<string>	The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated, successors MUST be provided if one exists. If successors is given, the described resource SHOULD set its releaseStatus to deprecated. Array Item Association Target: API Resource.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v2"]
changelogEntries OPTIONAL	Array<Changelog Entry>	Contains changelog entries that summarize changes with special regards to version and releaseStatus
entryPoints OPTIONAL	Array<string>	List of URL reference (URL or relative reference) to the target host. If the API resource can be accessed through an entry point, it MUST be described here. The list of entry points MUST not include duplicates. If multiple entry points are provided they MUST be arbitrarily exchangeable without effects. This means that the URLs are just an alias to each other and the resourceDefinitions apply to all entry points equally. In case of multiple entry points it is RECOMMENDED to provide a defaultEntryPoint through partOfConsumptionBundles. The entry point URLs SHOULD match with the target host(s) in the resource definition files (e.g. OpenAPI servers). If there is no match, the information in ORD takes precedence. Provider View: If the URL is relative to the system that describes the ORD information, it is RECOMMENDED to use relative references and (if known) to provide the describedSystemInstance.baseUrl. If the URL is not relative to the described system instance base URL, a full URL MUST be provided. Consumer View: When fetching the information from an ORD Aggregator, the consumer MAY rely on receiving full URLs. Array Item Format: uri-reference Example Values: ["/api-namespace/v1"]
direction OPTIONAL	string	Direction of the API Resource consumption. If not provided, "inbound" is assumed. In 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. Default Value: "inbound" Allowed Values: "inbound": The described system is the server. It's API Resource is available to external consumers by initiating connectivity. "mixed": 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. "outbound": The described system is the client. It initiates connectivity to an (registered) external consumer. If the API contract is owned by the described system, it can be documented here. If it is owned by an external provider or authority, it needs to be referred to via implementation standard.
apiProtocol MANDATORY	string	API Protocol including the protocol version if applicable Allowed Values: "odata-v2": OData Version 2.0 API. An API Resource definition of type edmx MUST be provided. For each API Resource definition: type MUST ONLY be set to edmx, csdl-json, openapi-v2, openapi-v3, sap-csn-interop-effective-v1 or custom. "odata-v4": OData Version 4 API. An OData V4 API MUST be described via a Common Schema Definition Language (CSDL). An API Resource definition of type edmx MUST be provided. For each API Resource definition: type MUST ONLY be set to edmx, csdl-json, openapi-v2, openapi-v3, sap-csn-interop-effective-v1 or custom. "rest": Generic REST API. Please not that while OData is also a REST API, the most precise/opinionated apiProtocol MUST be chosen. An API Resource definition of type openapi-v3 (RECOMMENDED) or another appropriate option SHOULD be provided. For each API Resource definition: type MUST ONLY be set to openapi-v2, openapi-v3, raml-v1, sap-csn-interop-effective-v1 or custom. "graphql": GraphQL API. An API Resource definition of type graphql-sdl SHOULD be provided. For each API Resource definition: type MUST ONLY be set to graphql-sdl, sap-csn-interop-effective-v1 or custom. "delta-sharing": Delta Sharing Protocol, where one API Resource corresponds to a share. For each API Resource definition: type MUST ONLY be set to sap-csn-interop-effective-v1 or to custom. For delta-sharing APIs the resource definition MAY be omitted, as the protocol itself allows for metadata discovery at runtime. Introduced in Version: 1.8.0 "soap-inbound": SOAP API that provides inbound interfaces. An API Resource definition of type wsdl-v2 (RECOMMENDED) or wsdl-v1 MUST be provided. For each API Resource definition: type MUST ONLY be set to wsdl-v1, wsdl-v2 or custom. "soap-outbound": SOAP API that provides/describes outbound interfaces for async communication. An API Resource definition of type wsdl-v2 (RECOMMENDED) or wsdl-v1 MUST be provided. For each API Resource definition: type MUST ONLY be set to wsdl-v1, wsdl-v2 or custom. "websocket": Generic WebSocket Protocol. Since WebSocket is very generic, it is important to also define or least describe which semantics are concretely used, e.g. via an implementationStandard. The API Resource definitions type MUST ONLY be set to custom. "sap-rfc": SAP RFC (Remote Function Call) is the standard SAP interface for communication between SAP systems. RFC calls a function to be executed in a remote system. An API Resource definition of type sap-rfc-metadata-v1 MUST be provided. For each API Resource definition: type MUST ONLY be set to sap-rfc-metadata-v1 or custom. "sap-sql-api-v1": SAP SQL API that follows the SQL interface specification for SAP ecosystem. An API Resource definition of type sap-sql-api-definition-v1 MUST be provided. For each API Resource definition: type MUST ONLY be set to sap-sql-api-definition-v1, sap-csn-interop-effective-v1 or custom. "sap-ina-api-v1": SAP InA APIs are used by SAP Analytics Cloud solutions to capture data. It is an SAP proprietary protocol that only SAP Analytics Cloud MUST consume. It contains a protocol specific metadata retrieval mechanism so that SAP Analytics Cloud users can see the schema of an InA API in SAP Analytics Cloud. An API Resource definition MUST NOT be provided. Introduced in Version: 1.8.0 Example Values: "rest"
resourceDefinitions OPTIONAL	Array<API Resource Definition>	List of available machine-readable definitions, which describe the resource or capability in detail. Each definition is to be understood as an alternative description format, describing the same resource / capability. As a consequence the same definition type MUST NOT be provided more than once. It is RECOMMENDED to provide the definitions as they enable machine-readable use cases. If the definitions are added or changed, the version MUST be incremented. An ORD aggregator MAY only (re)fetch the definitions again when the version was incremented.
implementationStandard OPTIONAL	string	Declares this API to be a valid implementation of an externally standardized API contract, sub-protocol or protocol variant. All APIs that share the same implementation standard MAY be treated the same or similar by a consumer client. Allowed Values: "sap:ord-document-api:v1": API follows the Open Resource Discovery v1 Document API contract. "cff:open-service-broker:v2": API follows the Open Service Broker API V2. "sap:csn-exposure:v1": API follows the SAP CSN_EXPOSURE service for exposing metadata in the CSN-format. "sap:ape-api:v1": API follows the SAP ABAP Pipeline Engine (APE) API protocol via ABAP WebSocket RFC for efficient data extraction. The apiProtocol MUST be set to websocket. "sap:cdi-api:v1": Implementation of the SAP Cloud Data Integration (CDI) interface for delta-enabled data extraction. The apiProtocol MUST be set to odata-v4, as this is a sub-protocol of OData. "sap:delta-sharing:v1": SAP opinionated implementation of delta-sharing API protocol. This implementation has some compatible extension wrt. to standard delta-share such as providing key information. The apiProtocol MUST be set to delta-sharing, as this is a special flavor of Delta Sharing. Introduced in Version: 1.9.0 "sap:hana-cloud-sql:v1": Specific additional implementation of the sap-sql-api-v1 API (sub-)protocol that provide replication support when connecting from an Hana Cloud system see SAP HANA Cloud documentation. The apiProtocol MUST be set to sap-sql-api-v1, as this is a sub-protocol / variant of the SAP SQL API. Introduced in Version: 1.8.0 "custom": If chosen, customImplementationStandard MUST be provided. If chosen, customImplementationStandardDescription SHOULD be provided. Example Values: "sap:ord-document-api:v1"
customImplementationStandard OPTIONAL	string	If the fixed implementationStandard values need to be extended, an arbitrary customImplementationStandard can be provided. MUST be a valid Specification ID. MUST only be provided if implementationStandard is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap.xref:some-api-contract:v1"
customImplementationStandardDescription OPTIONAL	string	Full description of the custom implementation standard, notated in CommonMark (Markdown). MUST only be provided if implementationStandard is set to custom. SHOULD contain documentation and links that describe the used standard. Example Values: "Implemented as defined in the [S/4HANA Attachment Service documentation](https://api.sap.com/api/API_CV_ATTACHMENT_SRV/overview)"
responsible OPTIONAL	string	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. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Introduced in Version: 1.8.0 Example Values: "sap:ach:CIC-DP-CO"
supportedUseCases OPTIONAL BETA	Array<string>	List of use cases (types) how the resource is meant to be used for. This helps consumers better to understand which use cases had been in mind by the provider and are therefore explicitly supported. This is obviously described from a provider perspective, but stating what consumer use cases it potentially supports. As it's not possible to create a list of options that are mutually exclusive, all options that apply should be provided. If no array is defined, it is assumed that this information is not provided. Array Item Allowed Values: "data-federation": Resources are designed to support data federation. This goes beyond plain queries, but typically allowing connections on the data base level, in the context of a business user. As consumers will directly access data, performance of the system must support these use cases. "snapshot": 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. As data is typically replicated, performance of the API is important, but less critical for an end-user experience. "incremental": Resource gives incremental updates on top of snapshots. "streaming": Resource can be used to get streaming updates. The difference to 'incremental' is that it doesn't need a snapshot . Introduced in Version: 1.8.0 Example Values: ["data-federation"]
usage OPTIONAL ALPHA	string	Usage Define from where the API resource can be used and accessed Default Value: "external" Allowed Values: "external": The API entryPoints are accessible external from the application providing it. "local": The API is only accessible within the application providing it. Access to (in-app) development tooling is necessary. Introduced in Version: 1.8.0
entityTypeMappings OPTIONAL	Array<Entity Type Mapping>	Describes mappings between the API Models of the described resource to the underlying, conceptual entity types. Introduced in Version: 1.6.0
apiResourceLinks OPTIONAL	Array<API and Event Resource Link>	Links with semantic meaning that are specific to API Resources.
links OPTIONAL	Array<Link>	Generic Links with arbitrary meaning and content. If applicable, apiResourceLinks MUST be used instead of generic links.
extensible OPTIONAL	Extensible	Describes extensibility (by customers or partners) of this resource. Extensibility usually happens at run-time by the end-users. Extensions can be field or entity extensions that come on top of the baseline contract. Changes in extensions do not lead to an increase in the version, but MUST lead to an updated lastUpdate date. Since the extensions are managed by the customer or a partner, whether those changes are compatible or not is not guaranteed by the base contract of the resource.
countries OPTIONAL	Array<string>	List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to IES ISO-3166 ALPHA-2. countries that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[A-Z]2$ Example Values: ["DE","US"]
lineOfBusiness OPTIONAL	Array<string>	List of line of business tags. No special characters are allowed except -, _, ., / and . lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Asset Management" "Commerce" "Finance" "Human Resources" "Manufacturing" "Marketing" "R&D Engineering" "Sales" "Service" "Sourcing and Procurement" "Supply Chain" "Sustainability" "Metering" "Grid Operations and Maintenance" "Plant Operations and Maintenance" "Maintenance and Engineering" Example Values: ["Sales"]
industry OPTIONAL	Array<string>	List of industry tags. No special characters are allowed except -, _, ., / and . industry that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Aerospace and Defense" "Automotive" "Banking" "Chemicals" "Consumer Products" "Defense and Security" "Engineering Construction and Operations" "Healthcare" "Higher Education and Research" "High Tech" "Industrial Machinery and Components" "Insurance" "Life Sciences" "Media" "Mill Products" "Mining" "Oil and Gas" "Professional Services" "Public Sector" "Retail" "Sports and Entertainment" "Telecommunications" "Travel and Transportation" "Utilities" "Wholesale Distribution" Example Values: ["Automotive"] ["Retail","Public Sector"] []
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.
policyLevel OPTIONAL	string	The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values: "none": No policy level chosen. Only the base rules on how to create correct ORD documents apply. "sap:base:v1": Basic SAP rules and guidelines apply. This just ensures technical correctness and essential validations. If chosen the SAP Base V1 rules MUST be followed. "sap:core:v1": SAP core rules and guidelines apply. If chosen the SAP Core V1 rules MUST be followed. "custom": Custom policy level. Further validation MAY be defined and implemented by the policy-level owner. This level MAY be chosen by 3rd party or customer solutions. If chosen, customPolicyLevel MUST be provided. Introduced in Version: 1.3.0 Example Values: "sap:core:v1"
customPolicyLevel OPTIONAL	string	If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided. The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom. MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:customPolicy:v1"
systemInstanceAware OPTIONAL	boolean	Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true. An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values: true

Event Resource

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. Which 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. Please note that event resources can be described, but still be disabled. If 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 that state this the ownership via the vendor property.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1" "sap.s4:eventResource:BillofMaterialEvents:v1"
localId OPTIONAL	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "BusinessEvents_SubscriptionEvents"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.xref:localConcept:SomeLocalId"]
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SalesOrder Events" "System XYZ Events"
shortDescription MANDATORY	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "All events related to the Business Object SalesOrder"
description MANDATORY	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "This event is raised by the SAP S/4HANA Cloud system when an invoice document is cancelled.\n"
partOfPackage MANDATORY	string	Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
partOfGroups OPTIONAL	Array<string>	Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead. All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
partOfConsumptionBundles OPTIONAL	Array<Consumption Bundle Reference>	List of references to the consumption bundles in this resource belongs to. MUST be a valid reference to a Consumption Bundle ORD ID. An API resource SHOULD be associated to one or multiple consumption bundles, if it is of direction inbound or mixed. Some ORD consumer use cases MAY depend on an association to a consumption bundle. If none is given, the resource may not appear as it's unknown how it can be consumed. If a resource has no direct incoming consumption characteristics: - MUST NOT assign consumption bundle to API or Event resources with direction: outbound (no inbound consumption) - MUST NOT assign consumption bundle if resource is not accessible directly, but only via intermediaries like event brokers or gateways. - In this case the intermediary SHOULD describe the consumption bundle instead (potentially also re-describing the resources as well). Example Values: [{"ordId":"sap.xref:consumptionBundle:bundleXYZ:v1"}]
defaultConsumptionBundle OPTIONAL	string	References the default consumption bundle to use for this resource. MUST be a valid reference to a Consumption Bundle ORD ID. Can be used by clients to make a deterministic and preferred choice when multiple options are available. The value MUST be an existing option in the corresponding partOfConsumptionBundles array. Association Target: Consumption Bundle.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:consumptionBundle:bundleXYZ:v1"
partOfProducts OPTIONAL	Array<string>	List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values: ["sap:product:S4HANA_OD:"]
version MANDATORY	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
lastUpdate RECOMMENDED	string	Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with systemInstanceAware, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values: "2022-12-19T15:47:04+00:00"
visibility MANDATORY	string	The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values: "public": Resources are publicly accessible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the SAP API Deprecation Policy. "internal": Resources are accessible to other applications within the same organization. However, they are not officially exposed and communicated to customers and 3rd parties. They might not come with the same guarantees on API stability. Internal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog. Internal resources MAY be published through an internal API Catalog if the access permissions are ensured by it. "private": Resources that are exclusively used within an application or service. This includes resources that may be called from outside but serve purely private purposes and are not supposed to be known by other outside parties. E.g., webhooks for provisioning callbacks or backing services. Private resources MUST NOT be made available to public consumers or consumers outside of the "private" scope or without the necessary access permissions.
releaseStatus MANDATORY	string	The releaseStatus specifies the stability of the resource and its external contract. Allowed Values: "active": Resource is meant for productive use and provides a stable API contract. "beta": The contract for the resource is beta and MAY not be meant for productive use. In the SAP context, beta APIs may be changed or deleted at SAPs discretion. "deprecated": Resource has been deprecated. If successor resources exist, they MUST be referenced through successors. If it is deprecated without defining its successors, a sunsetDate SHOULD be provided. A deprecated resource MAY be decommissioned (removed) in the future. This removal MUST be explicitly indicated through a Tombstone. Once the resource is decommissioned, it MUST be removed from ORD. Example Values: "active"
disabled OPTIONAL	boolean	Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. This can happen either because it has not been setup for use or disabled by an admin / user. If 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. This property can only reflect the knowledge of the described system instance itself. Outside factors for availability can't need to be considered (e.g. network connectivity, middlewares). A disabled resource MAY skip describing its resource definitions.
deprecationDate OPTIONAL	string	The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed. If the releaseStatus is set to deprecated, the deprecationDate SHOULD be provided. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2020-12-08T15:47:04+00:00"
sunsetDate OPTIONAL	string	The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated, the sunsetDate SHOULD be provided (if already known). Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2022-01-08T15:47:04+00:00"
successors OPTIONAL	Array<string>	The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated, successors MUST be provided if one exists. If successors is given, the described resource SHOULD set its releaseStatus to deprecated. Array Item Association Target: Event Resource.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1"]
changelogEntries OPTIONAL	Array<Changelog Entry>	Contains changelog entries that summarize changes with special regards to version and releaseStatus
resourceDefinitions OPTIONAL	Array<Event Resource Definition>	List of available machine-readable definitions, which describe the resource or capability in detail. Each definition is to be understood as an alternative description format, describing the same resource / capability. As a consequence the same definition type MUST NOT be provided more than once. It is RECOMMENDED to provide the definitions as they enable machine-readable use cases. If the definitions are added or changed, the version MUST be incremented. An ORD aggregator MAY only (re)fetch the definitions again when the version was incremented.
implementationStandard OPTIONAL	string	Declares this EventResource to be a valid implementation of a standardized or shared contract. All implementations of the same implementation standard MAY be treated the same by a consumer. However, there MAY be differences in the access strategy, and compatible customizations by the implementer. The implementation standard MAY define the role of the implementor (producer, consumer, both) and how it is determined. As of now, only custom implementation standards are supported. Allowed Values: "custom": If chosen, a custom implementation standard MUST be provided via customImplementationStandard and SHOULD be described via customImplementationStandardDescription Example Values: "custom"
customImplementationStandard OPTIONAL	string	If the fixed implementationStandard values need to be extended, an arbitrary customImplementationStandard can be provided. MUST be a valid Specification ID. MUST only be provided if implementationStandard is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap.xref:some-event-contract:v1"
customImplementationStandardDescription OPTIONAL	string	Full description of the custom implementation standard, notated in CommonMark (Markdown). MUST only be provided if implementationStandard is set to custom. SHOULD contain documentation and links that describe the used standard. Example Values: "Implemented as defined in [Some Application Documentation](some link)."
responsible OPTIONAL	string	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. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Introduced in Version: 1.8.0 Example Values: "sap:ach:CIC-DP-CO"
entityTypeMappings OPTIONAL	Array<Entity Type Mapping>	Describes mappings between the API Models of the described resource to the underlying, conceptual entity types. Introduced in Version: 1.6.0
eventResourceLinks OPTIONAL	Array<API and Event Resource Link>	Links with semantic meaning that are specific to event resources. If applicable, eventResourceLinks MUST be used instead of generic links. Introduced in Version: 1.7.1
links OPTIONAL	Array<Link>	Generic Links with arbitrary meaning and content.
extensible OPTIONAL	Extensible	Describes extensibility (by customers or partners) of this resource. Extensibility usually happens at run-time by the end-users. Extensions can be field or entity extensions that come on top of the baseline contract. Changes in extensions do not lead to an increase in the version, but MUST lead to an updated lastUpdate date. Since the extensions are managed by the customer or a partner, whether those changes are compatible or not is not guaranteed by the base contract of the resource.
countries OPTIONAL	Array<string>	List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to IES ISO-3166 ALPHA-2. countries that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[A-Z]2$ Example Values: ["DE","US"]
lineOfBusiness OPTIONAL	Array<string>	List of line of business tags. No special characters are allowed except -, _, ., / and . lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Asset Management" "Commerce" "Finance" "Human Resources" "Manufacturing" "Marketing" "R&D Engineering" "Sales" "Service" "Sourcing and Procurement" "Supply Chain" "Sustainability" "Metering" "Grid Operations and Maintenance" "Plant Operations and Maintenance" "Maintenance and Engineering" Example Values: ["Sales"]
industry OPTIONAL	Array<string>	List of industry tags. No special characters are allowed except -, _, ., / and . industry that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Aerospace and Defense" "Automotive" "Banking" "Chemicals" "Consumer Products" "Defense and Security" "Engineering Construction and Operations" "Healthcare" "Higher Education and Research" "High Tech" "Industrial Machinery and Components" "Insurance" "Life Sciences" "Media" "Mill Products" "Mining" "Oil and Gas" "Professional Services" "Public Sector" "Retail" "Sports and Entertainment" "Telecommunications" "Travel and Transportation" "Utilities" "Wholesale Distribution" Example Values: ["Automotive"] ["Retail","Public Sector"] []
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.
policyLevel OPTIONAL	string	The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values: "none": No policy level chosen. Only the base rules on how to create correct ORD documents apply. "sap:base:v1": Basic SAP rules and guidelines apply. This just ensures technical correctness and essential validations. If chosen the SAP Base V1 rules MUST be followed. "sap:core:v1": SAP core rules and guidelines apply. If chosen the SAP Core V1 rules MUST be followed. "custom": Custom policy level. Further validation MAY be defined and implemented by the policy-level owner. This level MAY be chosen by 3rd party or customer solutions. If chosen, customPolicyLevel MUST be provided. Introduced in Version: 1.3.0 Example Values: "sap:core:v1"
customPolicyLevel OPTIONAL	string	If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided. The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom. MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:customPolicy:v1"
systemInstanceAware OPTIONAL	boolean	Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true. An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values: true

Entity Type

An Entity Type describes either a business concept / term or an underlying conceptual model. The same entity type can be exposed through one or multiple API and events resources.

To learn more about the concept, see Entity Type.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.odm:entityType:BusinessPartner:v1" "sap.odm:entityType:CostCenter:v1" "sap.odm:entityType:WorkforcePerson:v1"
localId MANDATORY	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "BusinessPartner" "CostCenter" "WorkforcePerson"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.s4:sot:BusinessPartner"] ["sap.s4:sot:CostCenter"] ["sap.s4:sot:WorkforcePerson"]
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "Business Partner" "Cost Center" "Workforce Person"
shortDescription OPTIONAL	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "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 OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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 MANDATORY	string	Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
partOfGroups OPTIONAL	Array<string>	Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead. All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
partOfProducts OPTIONAL	Array<string>	List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values: ["sap:product:S4HANA_OD:"]
version MANDATORY	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
lastUpdate RECOMMENDED	string	Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with systemInstanceAware, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values: "2022-12-19T15:47:04+00:00"
visibility MANDATORY	string	The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values: "public": Resources are publicly accessible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the SAP API Deprecation Policy. "internal": Resources are accessible to other applications within the same organization. However, they are not officially exposed and communicated to customers and 3rd parties. They might not come with the same guarantees on API stability. Internal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog. Internal resources MAY be published through an internal API Catalog if the access permissions are ensured by it. "private": Resources that are exclusively used within an application or service. This includes resources that may be called from outside but serve purely private purposes and are not supposed to be known by other outside parties. E.g., webhooks for provisioning callbacks or backing services. Private resources MUST NOT be made available to public consumers or consumers outside of the "private" scope or without the necessary access permissions.
releaseStatus MANDATORY	string	The releaseStatus specifies the stability of the resource and its external contract. Allowed Values: "active": Resource is meant for productive use and provides a stable API contract. "beta": The contract for the resource is beta and MAY not be meant for productive use. In the SAP context, beta APIs may be changed or deleted at SAPs discretion. "deprecated": Resource has been deprecated. If successor resources exist, they MUST be referenced through successors. If it is deprecated without defining its successors, a sunsetDate SHOULD be provided. A deprecated resource MAY be decommissioned (removed) in the future. This removal MUST be explicitly indicated through a Tombstone. Once the resource is decommissioned, it MUST be removed from ORD. Example Values: "active"
deprecationDate OPTIONAL	string	The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed. If the releaseStatus is set to deprecated, the deprecationDate SHOULD be provided. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2020-12-08T15:47:04+00:00"
sunsetDate OPTIONAL	string	The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated, the sunsetDate SHOULD be provided (if already known). Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2022-01-08T15:47:04+00:00"
successors OPTIONAL	Array<string>	The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated, successors MUST be provided if one exists. If successors is given, the described resource SHOULD set its releaseStatus to deprecated. Array Item Association Target: Entity Type.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.odm:entityType:BusinessPartner:v2"] ["sap.odm:entityType:CostCenter:v2"] ["sap.odm:entityType:WorkforcePerson:v2"]
changelogEntries OPTIONAL	Array<Changelog Entry>	Contains changelog entries that summarize changes with special regards to version and releaseStatus
level MANDATORY	string	Defining the abstraction level of the entity type using the DDD terminology. In Domain-Driven Design, there is a concept of entities and aggregates. There are root entities which may contain further sub entities by composition. The complete “package” is then called an aggregate, which gets its name and identity from the root entity. An aggregate is a cluster of domain objects that can be treated as a single unit. The root is the entity that is referenced from outside the aggregate. There must be only one root per aggregate. The root ensures the integrity of the aggregate. A sub entity is any other non-root entity in the aggregate. Source, see Martin Fowler on DDD Aggregate For now, we decided to only cover the aggregate level, which is described in the enum value. Allowed Values: "aggregate": An aggregate is a tree of entity types. The root entity gives the aggregate its identity and ID. But every entity that is part of the tree due to a composition relationship is also part of the aggregate. The inner structure of an aggregate (sub entities, field, etc.) can be described in the entity type definition. Example Values: "aggregate"
relatedEntityTypes OPTIONAL	Array<Related Entity Type>	States that this Entity Type is related to another Entity Type. Usually this happens if there are similar conceptual entity types across different namespaces. Introduced in Version: 1.9.0
links OPTIONAL	Array<Link>	Generic Links with arbitrary meaning and content.
extensible OPTIONAL	Extensible	Describes extensibility (by customers or partners) of this resource. Extensibility usually happens at run-time by the end-users. Extensions can be field or entity extensions that come on top of the baseline contract. Changes in extensions do not lead to an increase in the version, but MUST lead to an updated lastUpdate date. Since the extensions are managed by the customer or a partner, whether those changes are compatible or not is not guaranteed by the base contract of the resource.
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.
policyLevel OPTIONAL	string	The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values: "none": No policy level chosen. Only the base rules on how to create correct ORD documents apply. "sap:base:v1": Basic SAP rules and guidelines apply. This just ensures technical correctness and essential validations. If chosen the SAP Base V1 rules MUST be followed. "sap:core:v1": SAP core rules and guidelines apply. If chosen the SAP Core V1 rules MUST be followed. "custom": Custom policy level. Further validation MAY be defined and implemented by the policy-level owner. This level MAY be chosen by 3rd party or customer solutions. If chosen, customPolicyLevel MUST be provided. Introduced in Version: 1.3.0 Example Values: "sap:core:v1"
customPolicyLevel OPTIONAL	string	If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided. The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom. MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:customPolicy:v1"
systemInstanceAware OPTIONAL	boolean	Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true. An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values: true

Capability

Capabilities can be used to describe use case specific capabilities, most notably supported features or additional information (like configuration) that needs to be understood from outside. This is a generic ORD concept that aims to cover many different capability discovery use cases that would otherwise need be implemented as individual service provider interfaces (SPIs).

If a capability needs to expose more information than possible with generic capability properties, a custom capability definition can be defined and referenced in ORD. This is the same idea and mechanism as with API resources and their resource definition formats.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(capability):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.foo.bar:capability:fieldExtensibility:v1"
localId OPTIONAL	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "SuccessFactorsRecruiting"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.s4:communicationScenario:SAP_COM_0008"]
type MANDATORY	string	Type of the Capability Allowed Values: "custom": If chosen, customType MUST be provided. "sap.mdo:mdi-capability:v1": Capability for SAP Master Data Integration (MDI). For the capability definitions: type MUST ONLY be set to sap.mdo:mdi-capability-definition:v1. Example Values: "custom"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap:custom-definition-format:v1"
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "MDI Capability"
shortDescription OPTIONAL	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing."
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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"
partOfPackage MANDATORY	string	Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
partOfGroups OPTIONAL	Array<string>	Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead. All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
version MANDATORY	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
lastUpdate RECOMMENDED	string	Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with systemInstanceAware, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values: "2022-12-19T15:47:04+00:00"
visibility MANDATORY	string	The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values: "public": Resources are publicly accessible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the SAP API Deprecation Policy. "internal": Resources are accessible to other applications within the same organization. However, they are not officially exposed and communicated to customers and 3rd parties. They might not come with the same guarantees on API stability. Internal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog. Internal resources MAY be published through an internal API Catalog if the access permissions are ensured by it. "private": Resources that are exclusively used within an application or service. This includes resources that may be called from outside but serve purely private purposes and are not supposed to be known by other outside parties. E.g., webhooks for provisioning callbacks or backing services. Private resources MUST NOT be made available to public consumers or consumers outside of the "private" scope or without the necessary access permissions.
releaseStatus MANDATORY	string	The releaseStatus specifies the stability of the resource and its external contract. Allowed Values: "active": Resource is meant for productive use and provides a stable API contract. "beta": The contract for the resource is beta and MAY not be meant for productive use. In the SAP context, beta APIs may be changed or deleted at SAPs discretion. "deprecated": Resource has been deprecated. If successor resources exist, they MUST be referenced through successors. If it is deprecated without defining its successors, a sunsetDate SHOULD be provided. A deprecated resource MAY be decommissioned (removed) in the future. This removal MUST be explicitly indicated through a Tombstone. Once the resource is decommissioned, it MUST be removed from ORD. Example Values: "active"
relatedEntityTypes OPTIONAL	Array<string>	Optional list of related EntityType Resources. MUST be a valid reference to an EntityType Resource ORD ID. Array Item Association Target: Entity Type.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.odm:entityType:WorkforcePerson:v1"]
definitions OPTIONAL	Array<Capability Definition>	List of available machine-readable definitions, which describe the resource or capability in detail. Each definition is to be understood as an alternative description format, describing the same resource / capability. As a consequence the same definition type MUST NOT be provided more than once. It is RECOMMENDED to provide the definitions as they enable machine-readable use cases. If the definitions are added or changed, the version MUST be incremented. An ORD aggregator MAY only (re)fetch the definitions again when the version was incremented.
links OPTIONAL	Array<Link>	Generic Links with arbitrary meaning and content.
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.
systemInstanceAware OPTIONAL	boolean	Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true. An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values: true

Data Product

BETA

A 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.

Please note that this concept is in beta, see Data Product - Beta Status.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.foo.bar:dataProduct:CustomerOrder:v1"
localId OPTIONAL	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "CustomerOrder"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.s4:communicationScenario:SAP_COM_0008"]
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "Customer Order"
shortDescription MANDATORY	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "Offering access to all online and offline orders submitted by customers"
description MANDATORY	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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 MANDATORY	string	Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
partOfGroups OPTIONAL	Array<string>	Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead. All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
version MANDATORY	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
lastUpdate RECOMMENDED	string	Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with systemInstanceAware, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values: "2022-12-19T15:47:04+00:00"
visibility MANDATORY	string	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 Allowed Values: "public": Resources are publicly accessible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the SAP API Deprecation Policy. "internal": Resources are accessible to other applications within the same organization. However, they are not officially exposed and communicated to customers and 3rd parties. They might not come with the same guarantees on API stability. Internal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog. Internal resources MAY be published through an internal API Catalog if the access permissions are ensured by it. "private": Resources that are exclusively used within an application or service. This includes resources that may be called from outside but serve purely private purposes and are not supposed to be known by other outside parties. E.g., webhooks for provisioning callbacks or backing services. Private resources MUST NOT be made available to public consumers or consumers outside of the "private" scope or without the necessary access permissions.
releaseStatus MANDATORY	string	The releaseStatus specifies the stability towards incompatible changes in the future. In the context of data products, it it covers only properties on the data product level. APIs that are part of the input and output ports have their own independent releaseStatus and version. Allowed Values: "active": Resource is meant for productive use and provides a stable API contract. "beta": The contract for the resource is beta and MAY not be meant for productive use. In the SAP context, beta APIs may be changed or deleted at SAPs discretion. "deprecated": Resource has been deprecated. If successor resources exist, they MUST be referenced through successors. If it is deprecated without defining its successors, a sunsetDate SHOULD be provided. A deprecated resource MAY be decommissioned (removed) in the future. This removal MUST be explicitly indicated through a Tombstone. Once the resource is decommissioned, it MUST be removed from ORD. Example Values: "active"
lifecycleStatus OPTIONAL	string	Lifecycle status of the Data Product as a whole. MUST be provided when describing the system-instance aware (run-time) perspective. SHOULD NOT be provided in static (design-time) perspective. Static aggregators MUST ignore this property. Allowed Values: "inactive": The data product is currently inactive, but can be provisioned. "provisioning": The data product is currently being provisioned / installed and is not yet ready to be used. This includes acquiring data from input ports, potentially necessary transformation and making the data available in the output ports. "active": The data product is active / live and can be used by consumers. There MAY be warnings but there MUST not be reported errors in the data product. "deprovisioning": The data product is being deprovisioned / uninstalled and not available for use anymore. Deprovisioning includes un-sharing the data from connected consumers and removing the replicated data which is no longer used. After successful deprovisioning the data product will either be disabled: true (preferred) or not described by the tenant at run-time. "active-with-errors": The data product has been successfully provisioned and has gone active, but errors prevent proper consumption. Consistent usage of the data product is not guaranteed until all errors are resolved. "provisioning-error": The provisioning of the data product failed with error(s). "deprovisioning-error": The deprovisioning of the data product failed with error(s). Consistent usage of the data product is not guaranteed until all errors are resolved. Example Values: "active"
deprecationDate OPTIONAL	string	The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed. If the releaseStatus is set to deprecated, the deprecationDate SHOULD be provided. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2020-12-08T15:47:04+00:00"
sunsetDate OPTIONAL	string	The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated, the sunsetDate SHOULD be provided (if already known). Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2022-01-08T15:47:04+00:00"
successors OPTIONAL	Array<string>	The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated, successors MUST be provided if one exists. If successors is given, the described resource SHOULD set its releaseStatus to deprecated. Array Item Association Target: Data Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.foo.bar:dataProduct:CustomerOrder:v1"]
changelogEntries OPTIONAL	Array<Changelog Entry>	Contains changelog entries that summarize changes with special regards to version and releaseStatus
type MANDATORY	string	Type of the data product. Based on the type some properties of a data product may become optional/mandatory. Allowed Values: "primary": A producer aligned data product, aka primary data product. Such a data product will be typically served directly from an application and might not have input ports. "derived": A data product that typically aggregates and combines data from multiple sources to provider value added data sets on top. Derived data products must provide at least one input port with an integration dependency that has at least one requirement. To be clarified if we need an additional analytical type for data products that focus on calculating KPIs. Example Values: "primary"
category MANDATORY	string	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. Based on the type some properties of a data product may become optional/mandatory. Consumers might still do analytics on business object like data products. Allowed Values: "business-object": Business Objects: master data, transaction data "analytical": Analytical data, including cubes, KPIs and metrics "other": Other objects, eg: config data, mixed or just unspecified Example Values: "business-object"
entityTypes OPTIONAL	Array<string>	List of entity types that are at least partially exposed by the data product. Array Item Association Target: Entity Type.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.odm:entityType:CustomerOrder:v1","sap.odm:entityType:BusinessPartner:v1"]
inputPorts OPTIONAL	Array<Data Product Input Port>	The input ports of a data product indicate the data inputs for lineage purposes. It is a list of Integration Dependencies, whose aspects will form the actual input ports. Input ports can also be understood as the public interface to ingest data into the data product. Data 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. Data products of type base might not have any input ports. Their data sets are typically based directly on the applications / services own data. Example Values: [{"ordId":"sap.xref:integrationDependency:CustomerOrder:v1"}]
outputPorts MANDATORY	Array<Data Product Output Port>	Output ports are the interface (APIs and Events) through which the data of the data product can be accessed. Output ports of the same data product might produce different facets of the data set with different qualities. A data set can also be made available via different protocols, which also results in different ports. As long as different output ports are accessing the same model beneath, they should belong to the same data product. If the above criteria cannot be reasonably met, consider splitting the data product into multiple smaller data products. Array Constraint: MUST have at least 1 items Example Values: [{"ordId":"sap.cic:apiResource:RetailTransactionOData:v1"},{"ordId":"sap.cic:eventResource:RawCustomerOrder:v2"}]
responsible MANDATORY	string	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. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Introduced in Version: 1.8.0 Example Values: "sap:ach:CIC-DP-CO"
dataProductLinks OPTIONAL	Array<Data Product Link>	Links with semantic meaning that are specific to Data Product Resources.
links OPTIONAL	Array<Link>	Generic Links with arbitrary meaning and content.
industry OPTIONAL	Array<string>	List of industry tags. No special characters are allowed except -, _, ., / and . industry that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Aerospace and Defense" "Automotive" "Banking" "Chemicals" "Consumer Products" "Defense and Security" "Engineering Construction and Operations" "Healthcare" "Higher Education and Research" "High Tech" "Industrial Machinery and Components" "Insurance" "Life Sciences" "Media" "Mill Products" "Mining" "Oil and Gas" "Professional Services" "Public Sector" "Retail" "Sports and Entertainment" "Telecommunications" "Travel and Transportation" "Utilities" "Wholesale Distribution" Example Values: ["Automotive"] ["Retail","Public Sector"] []
lineOfBusiness OPTIONAL	Array<string>	List of line of business tags. No special characters are allowed except -, _, ., / and . lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Asset Management" "Commerce" "Finance" "Human Resources" "Manufacturing" "Marketing" "R&D Engineering" "Sales" "Service" "Sourcing and Procurement" "Supply Chain" "Sustainability" "Metering" "Grid Operations and Maintenance" "Plant Operations and Maintenance" "Maintenance and Engineering" Example Values: ["Sales"]
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.
policyLevel OPTIONAL	string	The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values: "none": No policy level chosen. Only the base rules on how to create correct ORD documents apply. "sap:base:v1": Basic SAP rules and guidelines apply. This just ensures technical correctness and essential validations. If chosen the SAP Base V1 rules MUST be followed. "sap:core:v1": SAP core rules and guidelines apply. If chosen the SAP Core V1 rules MUST be followed. "custom": Custom policy level. Further validation MAY be defined and implemented by the policy-level owner. This level MAY be chosen by 3rd party or customer solutions. If chosen, customPolicyLevel MUST be provided. Introduced in Version: 1.3.0 Example Values: "sap:core:v1"
customPolicyLevel OPTIONAL	string	If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided. The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom. MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:customPolicy:v1"
systemInstanceAware OPTIONAL	boolean	Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true. An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values: true

Integration Dependency

An Integration Dependency states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose. The purpose could be to enable a certain feature or integration scenario, but it could also be a mandatory prerequisite for the described system to work.

The integration dependency includes a list of individual aspects that the integration consists of. Aspects are an "ingredient" for the integration scenario (and are logically combined with AND condition). Each aspect can express alternatives (OR condition) on what API and event resources can be used to achieve the same outcome.

The direction of connection establishment, data flow is not directly implied and needs to be inferred from the referenced resources.

It is not in scope for the Integration Dependency to describe scenarios that external consumers have with the own exposed resources. This would overstep the boundary of self-description.

If an integration scenario consists of two sides integration with each other, each need to describe its own part in it as an Integration Dependency. Therefore, if an integration with multiple types of systems need to be setup, this SHOULD be separated into distinct Integration Dependencies.

An integration dependency is also not meant to describe a bigger process. Instead it focuses on the technical necessaries to create an integration for one particular purpose.

To learn more about the concept, see Integration Dependency.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.foo.bar:integrationDependency:CustomerOrder:v1"
localId OPTIONAL	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "SuccessFactorsRecruiting"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.s4:communicationScenario:SAP_COM_0008"]
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "Integration Dependency to realize Customer Order data product"
shortDescription OPTIONAL	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing."
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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"
partOfPackage MANDATORY	string	Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
partOfGroups OPTIONAL	Array<string>	Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead. All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
version MANDATORY	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
lastUpdate OPTIONAL	string	Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with systemInstanceAware, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values: "2022-12-19T15:47:04+00:00"
visibility MANDATORY	string	The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values: "public": Resources are publicly accessible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the SAP API Deprecation Policy. "internal": Resources are accessible to other applications within the same organization. However, they are not officially exposed and communicated to customers and 3rd parties. They might not come with the same guarantees on API stability. Internal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog. Internal resources MAY be published through an internal API Catalog if the access permissions are ensured by it. "private": Resources that are exclusively used within an application or service. This includes resources that may be called from outside but serve purely private purposes and are not supposed to be known by other outside parties. E.g., webhooks for provisioning callbacks or backing services. Private resources MUST NOT be made available to public consumers or consumers outside of the "private" scope or without the necessary access permissions.
releaseStatus MANDATORY	string	The releaseStatus specifies the stability of the resource and its external contract. Allowed Values: "active": Resource is meant for productive use and provides a stable API contract. "beta": The contract for the resource is beta and MAY not be meant for productive use. In the SAP context, beta APIs may be changed or deleted at SAPs discretion. "deprecated": Resource has been deprecated. If successor resources exist, they MUST be referenced through successors. If it is deprecated without defining its successors, a sunsetDate SHOULD be provided. A deprecated resource MAY be decommissioned (removed) in the future. This removal MUST be explicitly indicated through a Tombstone. Once the resource is decommissioned, it MUST be removed from ORD. Example Values: "active"
sunsetDate OPTIONAL	string	The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated, the sunsetDate SHOULD be provided (if already known). Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2022-01-08T15:47:04+00:00"
successors OPTIONAL	Array<string>	The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated, successors MUST be provided if one exists. If successors is given, the described resource SHOULD set its releaseStatus to deprecated. Array Item Association Target: Integration Dependency.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.foo.bar:integrationDependency:CustomerOrder:v2"]
mandatory MANDATORY	boolean	If true, the Integration Dependency is mandatory for the described system to function.
aspects OPTIONAL	Array<Aspect>	List of integration aspects that make up the Integration Dependency. Each aspect listed is a dedicated, constituent part (AND condition).
relatedIntegrationDependencies OPTIONAL	Array<string>	If an Integration Dependency conceptually belongs or related to another Integration Dependency, this can be indicated here. One situation would be where two systems each have an Integration Dependency to describe a two-sided integration from each side. Array Item Association Target: Integration Dependency.ordId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values: ["sap.foo.bar:integrationDependency:SomethingRelated:v1"]
links OPTIONAL	Array<Link>	Generic Links with arbitrary meaning and content.
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.

Vendor

The vendor of a product or a package, usually a corporation or a customer / user.

The vendor of a Package is the owner or creator of the content of the package. The vendor of a Product is the owner of the product.

If the resources are created by the customer / user of the described system, customer:vendor:Customer: MUST be used as vendor.

Both have already a vendor namespace within their ORD ID. The Vendor entity is giving more details on the vendor namespace. For one vendor namespace there MUST only be exactly one Vendor ORD entity describing it.

For example: The only correct value for a SAP vendor reference is sap:vendor:SAP:.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+):(vendor):([a-zA-Z0-9._\-]+):()$ Maximum Length: 255 Example Values: "sap:vendor:SAP:" "customer:vendor:Customer:" "microsoft:vendor:Microsoft:"
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP"
partners OPTIONAL	Array<string>	Optional list of partner vendors, referenced through their ORD ID. MUST be a valid reference to a Vendor ORD ID. This property can be used to indicate partnership relations between vendors. Array Item Association Target: Vendor.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ Example Values: ["microsoft:vendor:Microsoft:"]
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.

Product

A product in ORD is understood as a commercial product or service.

It is a high-level entity for structuring the software portfolio from a sales / software logistics perspective. While system type is a technical concept, product covers the commercial and marketing view.

Please note that the ORD concept of a product is very simple on purpose. There is no distinction between products and services and concepts like product versions, variants, etc.

ORD assumes that this is handled by specialized systems and that ORD only provides the means to correlate to them.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Maximum Length: 255 Example Values: "sap:product:S4HANA_OD:"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.xref:product:ABC"]
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP S/4HANA Cloud"
shortDescription MANDATORY	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "The next generation digital core designed to help you run simple in a digital economy."
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
vendor MANDATORY	string	Vendor / organization that is responsible for the Product. MUST be a valid reference to a Vendor ORD ID. Association Target: Vendor.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ Maximum Length: 256 Example Values: "sap:vendor:SAP:" "customer:vendor:Customer:" "microsoft:vendor:Microsoft:"
parent OPTIONAL	string	Optional product parent ORD ID, if a hierarchical product structure needs to be expressed. MUST be a valid reference to a Product ORD ID. Association Target: Product.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values: "sap:product:S4HANA_OD:"
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.

Package

A Package organizes a set of related resources together, by publishing and catalog presentation concerns.

The Package can also be used to indicate which products or vendors provided the packaged resources. For partner or customer content, the package can indicate this via the vendor and partOfProducts assignments. In 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.

A package SHOULD contain at least one resource. Avoid empty packages.

A package does not have a visibility property. Whether it is displayed is decided by the fact, whether it contains any visible resources according to the visibility role of the aggregator.

To learn more about the concept and further guidance, see Package.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
localId OPTIONAL	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "SuccessFactorsRecruiting"
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP S/4HANA Cloud"
shortDescription MANDATORY	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing."
description MANDATORY	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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 MANDATORY	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
policyLevel OPTIONAL	string	The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values: "none": No policy level chosen. Only the base rules on how to create correct ORD documents apply. "sap:base:v1": Basic SAP rules and guidelines apply. This just ensures technical correctness and essential validations. If chosen the SAP Base V1 rules MUST be followed. "sap:core:v1": SAP core rules and guidelines apply. If chosen the SAP Core V1 rules MUST be followed. "custom": Custom policy level. Further validation MAY be defined and implemented by the policy-level owner. This level MAY be chosen by 3rd party or customer solutions. If chosen, customPolicyLevel MUST be provided. Introduced in Version: 1.3.0 Example Values: "sap:core:v1"
customPolicyLevel OPTIONAL	string	If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided. The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom. MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:customPolicy:v1"
packageLinks OPTIONAL	Array<Package Link>	Links with semantic meaning that are specific to packages.
links OPTIONAL	Array<Link>	Generic links with arbitrary meaning and content. packageLinks MUST be preferred if applicable.
licenseType OPTIONAL	string	Standardized identifier for the license. It MUST conform to the SPDX License List. Minimum Length: 1
supportInfo OPTIONAL	string	Optional information that should be provided when creating a support ticket for the resources bundled in this package. This can for example be a "component" name that needs to be chosen in the support portal. Notated in CommonMark (Markdown). Please also note that if you want to provide link(s) where you can find support information, you can use packageLinks with a link of type support. Minimum Length: 1 Introduced in Version: 1.1.0
vendor MANDATORY	string	Vendor / organization that is the creator (or responsible party) of the resources that are part of the Package. MUST be a valid reference to a Vendor ORD ID. MUST be set to customer:vendor:Customer: if the contents of the package are created by the customer / user. MUST be set to a registered partner vendor, if the contents of the package are created by a partner / third party. Association Target: Vendor.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ Maximum Length: 256 Example Values: "sap:vendor:SAP:" "customer:vendor:Customer:" "microsoft:vendor:Microsoft:"
partOfProducts OPTIONAL	Array<string>	List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values: ["sap:product:S4HANA_OD:"]
countries OPTIONAL	Array<string>	List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to IES ISO-3166 ALPHA-2. countries that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[A-Z]2$ Example Values: ["DE","US"]
lineOfBusiness OPTIONAL	Array<string>	List of line of business tags. No special characters are allowed except -, _, ., / and . lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Asset Management" "Commerce" "Finance" "Human Resources" "Manufacturing" "Marketing" "R&D Engineering" "Sales" "Service" "Sourcing and Procurement" "Supply Chain" "Sustainability" "Metering" "Grid Operations and Maintenance" "Plant Operations and Maintenance" "Maintenance and Engineering" Example Values: ["Sales"]
industry OPTIONAL	Array<string>	List of industry tags. No special characters are allowed except -, _, ., / and . industry that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values: "Aerospace and Defense" "Automotive" "Banking" "Chemicals" "Consumer Products" "Defense and Security" "Engineering Construction and Operations" "Healthcare" "Higher Education and Research" "High Tech" "Industrial Machinery and Components" "Insurance" "Life Sciences" "Media" "Mill Products" "Mining" "Oil and Gas" "Professional Services" "Public Sector" "Retail" "Sports and Entertainment" "Telecommunications" "Travel and Transportation" "Utilities" "Wholesale Distribution" Example Values: ["Automotive"] ["Retail","Public Sector"] []
runtimeRestriction OPTIONAL ALPHA	string	Runtime Restriction If provided, all resources that are part of this package can only run on the listed runtime. Allowed Values: "sap.datasphere" Introduced in Version: 1.8.0
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.

Consumption Bundle

A Consumption Bundle groups APIs and Events together that can be consumed with the credentials and auth mechanism. Ideally it also includes instructions and details how to request access and credentials for resources.

For more documentation and guidance how to correctly this correctly, see Consumption Bundle details.

A consumption bundle SHOULD have at least one association with a resource (0..n). Avoid empty consumption bundles. A consumption bundle MUST NOT contain APIs and Events that are NOT defined in the ORD document(s) returned by the system instance that defines the consumption bundle.

Please note that some ORD consumer use cases MAY depend on consumption bundle assignments to work with the resources.

To learn more about the concept, see Consumption Bundle.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:consumptionBundle:bundleXYZ:v1"
localId OPTIONAL	string	Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "SuccessFactorsRecruiting"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.s4:communicationScenario:SAP_COM_0008"]
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP LoB System 3 Cloud Consumption Bundle 1"
shortDescription OPTIONAL	string	Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP LoB System 3 Cloud, cloud ERP suite designed for in-memory computing"
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "This consumption bundle includes all SAP LoB System 3 Cloud APIs and Events\nthat can be consumed with the same credentials.\n"
version RECOMMENDED	string	The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. OpenAPI info.version), it MUST be equal with the resource version to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via lastUpdate. The version MUST not be bumped for changes in extensions. The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented. Regex 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-]+)*))?$ Introduced in Version: 1.2.1 Example Values: "1.2.3" "1.0.0-alpha.1"
lastUpdate RECOMMENDED	string	Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with systemInstanceAware, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values: "2022-12-19T15:47:04+00:00"
visibility OPTIONAL	string	The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values: "public": Resources are publicly accessible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the SAP API Deprecation Policy. "internal": Resources are accessible to other applications within the same organization. However, they are not officially exposed and communicated to customers and 3rd parties. They might not come with the same guarantees on API stability. Internal resources MUST NOT be made available to consumers without checking the necessary access permissions, e.g., a public API Catalog. Internal resources MAY be published through an internal API Catalog if the access permissions are ensured by it. "private": Resources that are exclusively used within an application or service. This includes resources that may be called from outside but serve purely private purposes and are not supposed to be known by other outside parties. E.g., webhooks for provisioning callbacks or backing services. Private resources MUST NOT be made available to public consumers or consumers outside of the "private" scope or without the necessary access permissions.
credentialExchangeStrategies OPTIONAL ALPHA	Array<Credential Exchange Strategy>	Defines the supported strategies for how the consumption credentials can be exchanged. Ideally, the system type supports a strategy that can automate the exchange.
links OPTIONAL	Array<Link>	Generic links with arbitrary meaning and content.
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.

Group

Group (instance) that resources can be assigned to.

Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead.

To learn more about the concept, see Group Concept Documentation.

Property	Type	Description
groupId MANDATORY	string	The Group ID consists of two Concept IDs separated by a :. The first two fragments MUST be equal to the used Group Type ID (groupTypeId). The last two fragments MUST be a valid Concept ID, indicating the group instance assignment. The ID concept is a bit unusual, but it ensures globally unique and conflict free group assignments. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values: "sap.foo:domain:sap.foo:DomainName"
groupTypeId MANDATORY	string	Group Type ID. MUST match with the first two fragments of the own groupId. Association Target: Group Type.groupTypeId Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values: "sap.foo:domain" "sap.cap:service"
title MANDATORY	string	Human readable title of the group assignment (for UI). Minimum Length: 1 Maximum Length: 255 Example Values: "SAP S/4HANA Cloud"
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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"

Group Examples

{
  "groupId": "sap.cap:service:customer.incidents:incidents.IncidentsService",
  "groupTypeId": "sap.cap:service",
  "title": "Incidents Service"
}

Group Type

A Group Type defines the semantics of group assignments. What the Group Type means and how it is to be used correctly SHOULD be described in the description (which may include markdown links).

Group Types can be defined centrally (ownership by authority namespace) or decentrally (defined by application / service itself).

To learn more about the concept, see Group Concept Documentation.

Property	Type	Description
groupTypeId MANDATORY	string	GroupType ID, which MUST be a valid Concept ID. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values: "sap.foo:domain" "sap.cap:service"
title MANDATORY	string	Human readable title of the group type. Minimum Length: 1 Maximum Length: 255 Example Values: "SAP S/4HANA Cloud"
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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"

Group Type Examples

{
  "groupTypeId": "sap.cds:service",
  "title": "CAP Service",
  "description": "Description of the CDS Service concept and how its correctly used for grouping..."
}

Tombstone

A tombstone indicates that a previously published ORD resource or taxonomy has been removed / decommissioned. This MUST be indicated explicitly, so ORD aggregators and consumers can learn about the removal.

Exactly one of the IDs MUST be provided to state which ORD resource or taxonomy item the Tombstone addresses.

It MUST be kept sufficiently long so that all ORD aggregators can learn about the tombstone. After that it MAY be removed.

Property	Type	Description
ordId OPTIONAL	string	ORD ID of the ORD resource/taxonomy that has been removed. Association Target: Package.ordId | Consumption Bundle.ordId | Product.ordId | Vendor.ordId | API Resource.ordId | Event Resource.ordId | Capability.ordId | Entity Type.ordId | Integration Dependency.ordId | Data Product.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package|consumptionBundle|product|vendor|apiResource|eventResource|capability|entityType|integrationDependency|dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*|)?$ Maximum Length: 255 Example Values: "sap.xref:package:SomePackage:v1"
groupId OPTIONAL	string	Group ID of the group that has been removed. Association Target: Group.groupId Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values: "sap.foo:domain:sap.foo:DomainName"
groupTypeId OPTIONAL	string	Group Type ID of the group type that has been removed. Association Target: Group Type.groupTypeId Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values: "sap.foo:domain" "sap.cap:service"
removalDate MANDATORY	string	The date when the ORD resource/taxonomy was removed. This is related to the sunsetDate that can be set to announce a resource as deprecated before the removal and setting of a tombstone. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values: "2020-12-02T14:12:59Z"
description OPTIONAL	string	Optional description, notated in CommonMark (Markdown). The description of a Tombstone MAY be added to the changelog of the removed resource by an ORD aggregator. Minimum Length: 1 Example Values: "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"

Tombstone 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"
}

Consumption Bundle Reference

Reference to a Consumption bundle.

This is a complex object to allow additional properties / selections to be attached.

Property	Type	Description
ordId MANDATORY	string	The consumption bundle ORD ID (ConsumptionBundle.ordId) this reference points to. Association Target: Consumption Bundle.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.xref:consumptionBundle:bundleXYZ:v1"
defaultEntryPoint OPTIONAL	string	In case that an API Resource has multiple entry points, this will indicate which entry point should be used by default when discovering this resource from the context of the referenced Consumption Bundle. MUST NOT be provided for Event Resources, as they don't have entry points. MUST only be provided if the resource has more than one entry point. MUST be in the list of entryPoints of the affected resource. JSON Schema Format: uri-reference

Data Product Input Port

An input port of a data product states where it retrieves its data inputs from.

It is described as via an ORD Integration Dependency.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: Integration Dependency.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.foo.bar:integrationDependency:CustomerOrder:v1"

Data Product Output Port

A data product output port references the APIs or Events that can be used to access the data-set. It 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.

Referenced API or Event ORD resources don't need to be provided within the same ORD document. If a data product is built against a specific API contract of another application or data product, this API resource should be referred to. In this case the other application is responsible for the lifecycle of the API contract and will update its ORD description independently.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: API Resource.ordId | Event Resource.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource|eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.cic:apiResource:RetailTransactionOData:v1" "sap.cic:eventResource:RawCustomerOrder:v2"

API Resource Definition

Link and categorization of a machine-readable API definition. For example, OpenAPI definition, OData Metadata, etc.

Property	Type	Description
type MANDATORY	string	Type of the API Resource Definition If "custom" is chosen, a customType MUST be provided Allowed Values: "openapi-v2": OpenAPI 2 / Swagger 2 API Definition for REST APIs. The mediaType MUST be be set to either application/json or text/yaml. "openapi-v3": OpenAPI 3 API Definition for REST APIs. The mediaType MUST be be set to either application/json or text/yaml. "raml-v1": RAML API Definition for REST APIs. The mediaType MUST be be set to text/yaml. "edmx": OData APIs can be described via edmx XML files. For OData V2 APIs, this is standardized through the Common Schema Definition Language (CSDL) V2. For OData V4 APIs, this is standardized through the CSDL XML Representation The mediaType MUST be be set to application/xml. The apiProtocol MUST be set to odata-v2 or odata-v4. "csdl-json": OData V4 APIs can also be described via the OData Common Schema Definition Language (CSDL) JSON Representation. The mediaType MUST be be set to application/json. The apiProtocol MUST be set to odata-v2 or odata-v4. "graphql-sdl": GraphQL APIs can be described via the GraphQL Schema Definition Language. See also: GraphQL Specification > Type System. The mediaType MUST be be set to text/plain. The apiProtocol MUST be set to graphql. "wsdl-v1": WSDL 1 API Definition for SOAP APIs. The mediaType MUST be be set to application/xml. The apiProtocol MUST be set to soap-inbound or soap-outbound. "wsdl-v2": WSDL 2 API Definition for SOAP APIs. The mediaType MUST be be set to application/xml. The apiProtocol MUST be set to soap-inbound or soap-outbound. "sap-rfc-metadata-v1": Proprietary metadata description format for SAP RFC. The mediaType MUST be be set to application/xml. "sap-sql-api-definition-v1": Metadata description format for SAP SQL API, following the SQL interface specification for SAP ecosystem. The mediaType MUST be be set to application/json. The apiProtocol MUST be set to sap-sql-api-v1. "sap-csn-interop-effective-v1": CSN Interop Effective is a standardized and interoperable flavor of CSNand a notation for compact representations of CDS models. The mediaType MUST be be set to application/json. "custom": If chosen, customType MUST be provided. Example Values: "openapi-v3"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap:custom-definition-format:v1"
mediaType MANDATORY	string	The Media Type of the definition serialization format. A consuming application can use this information to know which file format parser it needs to use. For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON. If no Media Type is registered for the referenced file, text/plain MAY be used for arbitrary plain-text and application/octet-stream for arbitrary binary data. Allowed Values: "application/json" "application/xml" "text/yaml" "text/plain": For a plain-text format where no other serialization Media Type fits "application/octet-stream": For a binary format where no other serialization Media Type fits Example Values: "application/json"
url MANDATORY	string	URL reference (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). JSON Schema Format: uri-reference Example Values: "/api/openApi.yaml" "https://example.com/api/API_RFQ_PROCESS_SRV/$metadata"
accessStrategies OPTIONAL	Array<Access Strategy>	List of supported access strategies for retrieving metadata from the ORD provider. An ORD Consumer/ORD Aggregator MAY choose any of the strategies. The access strategies only apply to the metadata access and not the actual API access. The actual access to the APIs for clients is described via Consumption Bundles. If this property is not provided, the definition URL will be available through the same access strategy as this ORD document. It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process. Array Constraint: MUST have at least 1 items Example Values: [{"type":"open"}]

Event Resource Definition

Link and categorization of a machine-readable API definition. For example, AsyncAPI or OpenAPI with callbacks, etc.

Property	Type	Description
type MANDATORY	string	Type of the event resource definition Allowed Values: "asyncapi-v2": AsyncAPI 2 API definition for events. The SAP Event Catalog Specification also falls under this category, as it is a valid AsyncAPI definition. "sap-csn-interop-effective-v1": CSN Interop Effective is a standardized and interoperable flavor of CSN. CSN is a notation for compact representations of CDS models. In CDS based frameworks (like ABAP, CAP), APIs and Events are derived from a CDS Service definition and its constituent entities. In this case the original CDS service definition MAY be attached, as it usually contains more metadata insight than other formats. WARNING: Only expose the CDS Service definition that effectively is governed by the API contract and stability. Do not expose internal models! The mediaType MUST be be set to application/json. "custom": If chosen, customType MUST be provided. Example Values: "asyncapi-v2"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap:custom-definition-format:v1"
mediaType MANDATORY	string	The Media Type of the definition serialization format. A consuming application can use this information to know which file format parser it needs to use. For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON. If no Media Type is registered for the referenced file, text/plain MAY be used for arbitrary plain-text and application/octet-stream for arbitrary binary data. Allowed Values: "application/json" "application/xml" "text/yaml" "text/plain": For a plain-text format where no other serialization Media Type fits "application/octet-stream": For a binary format where no other serialization Media Type fits Example Values: "application/json"
url MANDATORY	string	URL reference (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). JSON Schema Format: uri-reference Example Values: "/some/url/events/eventCatalog.json"
accessStrategies OPTIONAL	Array<Access Strategy>	List of supported access strategies for retrieving metadata from the ORD provider. An ORD Consumer/ORD Aggregator MAY choose any of the strategies. The access strategies only apply to the metadata access and not the actual API access. The actual access to the APIs for clients is described via Consumption Bundles. If this property is not provided, the definition URL will be available through the same access strategy as this ORD document. It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process. Array Constraint: MUST have at least 1 items Example Values: [{"type":"open"}]

Capability Definition

Link and categorization of a machine-readable capability definition.

Property	Type	Description
type MANDATORY	string	Type of the capability resource definition Allowed Values: "custom": If chosen, a custom type MUST be provided via customType "sap.mdo:mdi-capability-definition:v1": Specification for describing master data integration capabilities for Master Data Orchestration (MDO). The mediaType MUST be set to application/json. The capability type MUST be set to sap.mdo:mdi-capability:v1. Example Values: "custom"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap:custom-definition-format:v1"
mediaType MANDATORY	string	The Media Type of the definition serialization format. A consuming application can use this information to know which file format parser it needs to use. For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON. If no Media Type is registered for the referenced file, text/plain MAY be used for arbitrary plain-text and application/octet-stream for arbitrary binary data. Allowed Values: "application/json" "application/xml" "text/yaml" "text/plain": For a plain-text format where no other serialization Media Type fits "application/octet-stream": For a binary format where no other serialization Media Type fits Example Values: "application/json"
url MANDATORY	string	URL reference (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). JSON Schema Format: uri-reference Example Values: "/capabilities/someCapability/someDocument.json"
accessStrategies OPTIONAL	Array<Access Strategy>	List of supported access strategies for retrieving metadata from the ORD provider. An ORD Consumer/ORD Aggregator MAY choose any of the strategies. The access strategies only apply to the metadata access and not the actual API access. The actual access to the APIs for clients is described via Consumption Bundles. If this property is not provided, the definition URL will be available through the same access strategy as this ORD document. It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process. Array Constraint: MUST have at least 1 items Example Values: [{"type":"open"}]

Aspect

An (integration) aspect is the constituent part that makes up an Integration Dependency.

Each aspect can list references to resources, which could be owned and defined by the integration target or by the described system itself. In 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.

If multiple resources are given within an aspect, they are considered alternatives to each other (OR condition). In case an AND condition is needed, multiple aspects need to be added to the Integration Dependency.

Property	Type	Description
title MANDATORY	string	Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values: "Integration Aspect to get Customer Order data"
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "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"
mandatory MANDATORY	boolean	If true, the aspect is mandatory to realize the Integration Dependency it contains.
supportMultipleProviders OPTIONAL	boolean	If true, the references resources can be provided by multiple system instances. If not, only one integration target is supported.
apiResources OPTIONAL	Array<API Resource Integration Aspect>	List of API Resource Dependencies.
eventResources OPTIONAL	Array<Event Resource Integration Aspect>	List of Event Resource Dependencies.

API Resource Integration Aspect

API resource related integration aspect

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v1"
minVersion OPTIONAL	string	Minimum version of the references resource that the integration requires. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"

Event Resource Integration Aspect

Event resource related integration aspect

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1"
minVersion OPTIONAL	string	Minimum version of the references resource that the integration requires. Regex 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-]+)*))?$ Example Values: "1.2.3" "1.0.0-alpha.1"
subset OPTIONAL	Array<Event Resource Integration Aspect Subset>	List of individual events or messages that are sufficient to achieve the aspect.
systemTypeRestriction OPTIONAL	Array<string>	In case that the event subscriptions are limited to known system types, they can be listed here as system namespaces. If given, only system types of the defined namespaces are supported as integration partners. If not given, there is no restriction which system type provides the events. Array Constraint: MUST have at least 1 items Array Item Regex Pattern: ^[a-z0-9]+(?:[.][a-z0-9]+)1$ Example Values: ["sap.s4"]

Event Resource Integration Aspect Subset

Defines that Event Resource Integration Aspect only requires a subset of the referenced contract.

For events, this could be a list of the events that need to be subscribed in order to make the integration work. This 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.

Property	Type	Description
eventType MANDATORY	string	The type ID of the individual event or message. This MUST be an ID that is understood by the used protocol and resource definition format. E.g. for CloudEvents, the type can be used. Example Values: "sap.cic.Order.OrderTransferred.v1"

Changelog Entry

A changelog entry can be used to indicate changes. Usually they lead to a change of the version number or the release status.

Property	Type	Description
version MANDATORY	string	Full version number that corresponds to the version that is described by the changelog entry. Ideally it follows the Semantic Versioning 2.0.0 standard, but since it should reflect the actual version string / scheme used, this is not a mandatory requirement. Minimum Length: 1 Example Values: "1.2.3"
releaseStatus MANDATORY	string	The releaseStatus specifies the stability of the resource and its external contract. Allowed Values: "active": Resource is meant for productive use and provides a stable API contract. "beta": The contract for the resource is beta and MAY not be meant for productive use. In the SAP context, beta APIs may be changed or deleted at SAPs discretion. "deprecated": Resource has been deprecated. If successor resources exist, they MUST be referenced through successors. If it is deprecated without defining its successors, a sunsetDate SHOULD be provided. A deprecated resource MAY be decommissioned (removed) in the future. This removal MUST be explicitly indicated through a Tombstone. Once the resource is decommissioned, it MUST be removed from ORD. Example Values: "active"
date MANDATORY	string	Date of change, without time or timezone information. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date Example Values: "2020-04-29"
description OPTIONAL	string	Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: "## Changelog\n..."
url OPTIONAL	string	Optional URL that links to a more detailed changelog entry. JSON Schema Format: uri

Link

Link that can be attached to packages or Open Resource Discovery resources.

Property	Type	Description
title MANDATORY	string	Human readable title of the link. MUST be unique within the collection of links provided. Minimum Length: 1 Example Values: "APIs for SAP S/4HANA"
url MANDATORY	string	URL of the link. JSON Schema Format: uri Example Values: "https://blogs.sap.com/2018/04/11/testing-of-s4hana-inventory-management-odata-apis-via-sap-api-hub/"
description OPTIONAL	string	Full description, notated in CommonMark (Markdown) Minimum Length: 1 Example Values: "This gives you an overview on where to find which kind of APIs in SAP S/4HANA.\n"

Link 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."
}

Package Link

Links with specific semantic meaning that are related to Package.

If a generic Link can also be expressed via PackageLink, the latter MUST be chosen.

Property	Type	Description
type MANDATORY	string	Package link type Allowed Values: "terms-of-service": Link to human-readable terms of service documentation. "license": Link to human-readable license documentation "client-registration": Links to a resource where a client may register to use the package "payment": Links to a resource detailing pricing details of the package "sandbox": Links to a sandbox environment "service-level-agreement": Links to a resource detailing the Service Level Agreement relating to the package. This may be machine- or human-readable. "support": Links to a resource where a client may obtain support for the package "custom": If chosen, customType MUST be provided. Example Values: "terms-of-service"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap:custom-definition-format:v1"
url MANDATORY	string	URL to the PackageLink. For more information, see type. JSON Schema Format: uri Example Values: "https://accounts.sap.com/ui/public/showRegisterForm?spName=https://netweaver.ondemand.com&targetUrl=https://cloudintegration.hana.ondemand.com"

Package Link Examples

{
  "type": "terms-of-service",
  "url": "https://www.sap.com/corporate/en/legal/terms-of-use.html"
}

API and Event Resource Link

Links with specific semantic meaning that are related to API or event resources.

If a generic Link can also be expressed via an APIEventResourceLink, the latter MUST be chosen.

Property	Type	Description
type MANDATORY	string	See also: WADG0001 WebAPI type extension Allowed Values: "api-documentation": Link to human-readable documentation describing the API or event resource in more detail. "authentication": Links to a resource detailing authentication requirements. Note that this is a human-readable resource, not an authentication endpoint. "client-registration": Links to a resource where a client may register to use the API or event resource. "console": Links to an interactive console where API calls or events may be tested. "payment": Links to a resource detailing pricing details of the API or event resource. "service-level-agreement": Links to a resource detailing the Service Level Agreement relating to the API or event resource. This may be machine- or human-readable. "support": Links to a resource where a client may obtain support for the API or event resource. "custom": If chosen, customType MUST be provided. Example Values: "console"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap:custom-definition-format:v1"
url MANDATORY	string	URL reference (URL or relative reference) to the endpoint or UI for the action. If the link is relative to base URL, it is RECOMMENDED to provide a relative URL. JSON Schema Format: uri-reference Example Values: "/some/relative/url" "https://example.com/some/absolute/url"

API and Event Resource Link Examples

{
  "type": "api-documentation",
  "url": "https://api.sap.com/api/API_OPLACCTGDOCITEMCUBE_SRV/resource"
}

Data Product Link

Links with specific semantic meaning that are related to Data Product resources. If a generic Link can also be expressed via DataProductLink, the latter MUST be chosen.

Property	Type	Description
type MANDATORY	string	API action type. See also: WADG0001 WebAPI type extension Allowed Values: "payment": Links to a resource detailing pricing details of the data product. "service-level-agreement": Links to a resource detailing the Service Level Agreement relating to the data product. This may be machine- or human-readable. "support": Links to a resource where a client may obtain support for the data product. "custom": If chosen, customType MUST be provided. Example Values: "support"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap:custom-definition-format:v1"
url MANDATORY	string	URL reference (URL or relative reference) to the endpoint or UI for the action. If the link is relative to base URL, it is RECOMMENDED to provide a relative URL. JSON Schema Format: uri-reference Example Values: "/some/relative/url" "https://example.com/some/absolute/url"

Data Product Link Examples

{
  "type": "support",
  "url": "https://support.sap.com/CIC_DP_RT/issue/"
}

System Instance

A system instance is a concrete, running instance of a system type. In a multi-tenant system, this corresponds to a tenant.

Property	Type	Description
baseUrl OPTIONAL	string	Optional base URL of the system instance. By providing the base URL, all relative references in the document are resolved relative to it. The baseUrl MUST not contain a leading slash. MUST be provided if the base URL is not known to the ORD aggregators. MUST be provided when the document needs to be fully self contained, e.g. when used for manual imports. JSON Schema Format: uri Regex Pattern: ^http[s]?:\/\/[^:\/\s]+\.[^:\/\s\.]+(:\d+)?(\/[a-zA-Z0-9-\._~]+)*$ Example Values: "https://example-sap-system.com" "https://sub.foo.bar.com" "https://sub.foo.bar.com/api/v1"
localId OPTIONAL	string	Optional local ID for the system instance, as known by the described system. In the context of a system instance, this is usually the local tenant id. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values: "LocalTenantId123"
correlationIds OPTIONAL	Array<string>	Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead. MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values: ["sap.cld:tenant:741234567"]
tags OPTIONAL	Array<string>	List of free text style tags. No special characters are allowed except -, _, ., / and . Tags that are assigned to a Package are inherited to all of the ORD resources it contains. Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values: ["storage","high-availability"]
labels OPTIONAL	Labels	Generic labels that can be applied to most ORD information.
documentationLabels OPTIONAL	Documentation Labels	Generic documentation labels that can be applied to most ORD information.

Access Strategy

Defines the access strategy for accessing the resource definitions.

Property	Type	Description
type MANDATORY	string	Defines the authentication/authorization strategy through which the referenced resourceDefinitions are accessible. Allowed Values: "open": The resource definitions are openly accessible and not protected via authentication or authorization. Please find a more detailed documentation here. "sap:cmp-mtls:v1": The ORD information are accessible via Unified Customer Landscape's client certificate. Please find a more detailed documentation here. "sap.businesshub:basic-auth:v1": The ORD information are accessible for SAP Business Accelerator Hub via Basic Auth strategy. Please find a more detailed documentation here. "custom": If chosen, customType MUST be provided. If chosen, customDescription SHOULD be provided. Example Values: "open"
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap.xref:open-local-tenant-id:v1"
customDescription OPTIONAL	string	Human-readable description about how the access is set up, notated in CommonMark (Markdown). MUST only be provided if type is set to custom. Minimum Length: 1 Example Values: "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.\""

Access Strategy Examples

{
  "type": "open"
}

{
  "type": "custom",
  "customType": "sap.xref:open-local-tenant-id:v1",
  "customDescription": "Custom description how to use custom access strategy"
}

Credential Exchange Strategy

ALPHA

The credential exchange strategy specifies how a set of credentials for a particular usage of the APIs in the consumption bundle can be obtained. Until a SAP-wide strategy for obtaining such credentials exists and is agreed upon, both LoBs and aggregators (namely Unified Customer Landscape) can define their own strategy specifications.

While the actual flow in term of API calls can differ between the different strategies, the end goal would always be the possibility for automatically obtaining credentials for each client that would like to use the APIs from a particular bundle.

Property	Type	Description
type MANDATORY	string	The type of credential exchange strategy. Allowed Values: "custom": If chosen, customType MUST be provided. If chosen, customDescription SHOULD be provided.
customType OPTIONAL	string	If the fixed type enum values need to be extended, an arbitrary customType can be provided. MUST be a valid Specification ID. MUST only be provided if type is set to custom. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values: "sap.xref:credential-exchange:v1"
customDescription OPTIONAL	string	Human-readable description about how the credential exchange is achieved, notated in CommonMark (Markdown). MUST only be provided if type is set to custom. Minimum Length: 1 Example Values:
callbackUrl OPTIONAL	string	URL reference (URL or relative reference) to the credential exchange callback endpoint. This allows requesting a set of credentials that can be used for consuming all the APIs and Events that are part of the bundle. The interface contract/protocol is dependent and defined by the chosen type. Whenever 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. The returned credentials MUST be valid for all resources that are part of the respective bundle. The endpoint SHOULD return a different set of credentials on each invocation. JSON Schema Format: uri Example Values: "https://system-instance-1.com/credentials?scenario=SAP_COM_008"

Labels

Generic labels that can be applied to most ORD information. They are defined as an object that may have arbitrary keys. The value of a key is an array of strings.

Labels can be used to attach technical information that cannot be expressed natively in ORD. An ORD aggregator should allow to categorize and query information based on the labels provided.

If multiple parties rely on the existence of certain label information, standardization through ORD SHOULD be preferred.

All labels attached to a Package will be inherited to the resources they contain. Duplicate labels will be merged by the ORD aggregator according to the following rules:

• Values of the same label key will be merged.
• Duplicate values of the same label key will be removed.

Property	Type	Description
^[a-zA-Z0-9-_.]*$	array<string>	Additional properties with a key name pattern "^[a-zA-Z0-9-_.]*$" MAY be added.

Labels Examples

{
  "label-key-1": [
    "label-value-1",
    "label-value-2"
  ]
}

Documentation Labels

Generic documentation labels that can be applied to most ORD information. They are defined as an object that may have arbitrary keys. The value of a key is an array of CommonMark (Markdown) text.

Documentation Labels can be used to attach human readable documentation that cannot be expressed natively in ORD. A documentation tool (like an API Catalog) can use the documentation labels to provide generic documentation "snippets". Due to the given structure they can be displayed e.g. as tables.

The key of the documentation Label is plain-text (MUST not contain line breaks) and denotes the subject matter that is described. The values (multiple can be provided for the same key) are CommonMark (Markdown) text which describes the subject matter or lists options for the key.

In contrast to regular labels, documentation labels are not meant to be used to categorize or query information.

Property	Type	Description
^.*$	array<string>	Additional properties with a key name pattern "^.*$" MAY be added.

Documentation Labels Examples

{
  "Scope Items": [
    "[Basic Bank Account Management (BFA)](https://rapid.sap.com/bp/#/scopeitems/BFA \\\" Link To BP \\\")"
  ]
}

Extensible

Contains information about the extensibility of this resource.

If applicable, a description and further resources about extending this resource are provided.

Property	Type	Description
supported MANDATORY	string	This property defines whether the resource is extensible. Not extensible means that the data model of the resource (i.e. API or event) cannot be extended with custom fields. Manually extensible means that in addition to defining a custom field, manual activities to include the field in the data model of the resource (i.e. API or event) are required. E.g. using a specific mapping tool or by selecting the resource in the data model extension tool. Automatically extensible means that after defining a custom field in the local domain model, the resource (i.e. API or event) is automatically extended as part of the default extension field definition. Allowed Values: "no" "manual" "automatic"
description OPTIONAL	string	A description about the extensibility capabilities of this API, notated in CommonMark (Markdown). This description may contain detailed steps on how to extend the API. Links to external resources can be provided within the description as markdown links. This description MUST be provided if supported is set to manual or automatic. Minimum Length: 1 Example Values: "Please find the extensibility documentation [here](#here)"

Extensible 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)"
}

Entity Type Mapping

An API or Event resource may optionally define its entityTypeMappings. This is used to map and correlate the API models to the underlying, conceptual entity types.

If the mapping from API resource to entity types is not defined, certain use-cases that rely on this explicit connection will not be possible.

This mapping is meant to be rather fine granular. Therefore, the mapping needs to be done on basis of one of the referenced resource definitions, as only there we know the details and the actual contents of the API Model of the API resource.

For the various resource definition formats the selection of API models may need to be expressed differently. As a consequence, there are different types of selectors that are specialized toward certain resource definition formats.

The target of the mapping is a correlation to an entity type via a Correlation ID or to an [ORD ID] of an entity type. It is assumed that the entity types are described in more detail or on a different abstraction level via metadata. When the correlation ID is used, an ORD consumer may need to know how to access the entity type metadata through conventions. This can be determined either by the namespace of the correlation ID, or through a defined and known implementationStandard that can resolve the localId fragment of the correlation ID .

At SAP, the metadata about entity types could be retrieved via the CSN_EXPOSURE service. To indicate this, the service needs to be implemented and described in ORD with implementationStandard set to sap:csn-exposure:v1).

ODM 2.0 relies on the entity type mappings and uses the the mapping to express the relationship of an API to the corresponding ODM entity. ORD consumers like SAP Business Accelerator Hub consume the mapping to make the relationships navigatable for customers.

Property	Type	Description
apiModelSelectors OPTIONAL	Array<API Model Selector (OData) | API Model Selector (JSON Pointer)>	List of selectors for API models within an API Resource. If multiple selectors are given, every selected API model maps to the entity type target(s). If omitted, the complete API resource will be mapped to the entityTypeTargets (less specific). Multiple selectors can be useful, e.g. with a CRUD REST API, to combine the similar API models. Depending on the chosen API protocol and the available resource definition formats, different kind of selectors need to be used.
entityTypeTargets MANDATORY	Array<Entity Type Target (ORD ID) | Entity Type Target (Correlation ID)>	List of entity types the ORD resource maps to. If apiModelSelectors are given, the mapping is more precise by also pointing to the specific model in the API. If multiple entity types are defined as the mapping target, all of them can be at least partially mapped to the source API model(s). Entity types can be referenced using either using an ORD ID or a Correlation ID. Array Constraint: MUST have at least 1 items

API Model Selector (OData)

API Model Selector for OData, using entity set names for the selection.

MUST only be used if the API Resource provides an API Resource Definition of type edmx.

Property	Type	Description
type MANDATORY	string	The type for OData selectors is fixed to odata. Allowed Values: "odata"
entitySetName MANDATORY	string	OData entity set name. As defined in the EDMX, e.g. <EntitySet Name="AttachmentContent">. Minimum Length: 1 Example Values: "AttachmentContent"

API Model Selector (OData) Examples

{
  "type": "odata",
  "entitySetName": "AttachmentContent"
}

API Model Selector (JSON Pointer)

Generic API Model Selector for JSON / YAML based resource definitions. It uses a JSON Pointer that points to the entity type description within the resource definition.

The JSON Pointer always to refer to the structure of the document as originally provided, before further post-processing like resolving $ref properties.

MUST only be used if the API Resource provides an API Resource Definition of media type application/json or text/yaml.

Property	Type	Description
type MANDATORY	string	The type for generic JSON Pointer selectors is fixed to json-pointer. Allowed Values: "json-pointer"
jsonPointer MANDATORY	string	JSON Pointer to the entity type schema / description within the resource definition format. MUST be a valid JSON Pointer according to RFC6901. The 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). Minimum Length: 1 Example Values: "#/objects/schemas/<schema name>" "#/components/schemas/sap.odm.sales.CustomerOrder.Placed.v0" "#/objects/schemas/<schema name>/table-oriented/<table name>"

API Model Selector (JSON Pointer) Examples

{
  "type": "json-pointer",
  "jsonPointer": "#/objects/schemas/AttachmentContent"
}

Related Entity Type

Defines which Entity Type is related (via its ORD ID). In the future, this could include stating the relationship type, too.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: Entity Type.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.odm:entityType:BusinessPartner:v1"

Entity Type Target (ORD ID)

Define which entity type is the target of an entity type mapping

Entity types can be referenced using a ORD ID of an entity type.

Property	Type	Description
ordId MANDATORY	string	The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: Entity Type.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values: "sap.odm:entityType:BusinessPartner:v1"

Entity Type Target (Correlation ID)

Define which entity type is the target of an entity type mapping

Entity types can be referenced using a Correlation ID.

Property	Type	Description
correlationId MANDATORY	string	Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Example Values: "sap.csnexposure:entity:Attachment"