description: >- The [ORD Document](../index.md#ord-document) object serves as a wrapper for the **ORD resources** and **ORD taxonomy** and adds further top-level information that are specific to the document/the service it describes. The constraints and considerations on [ORD Documents](../index.md#ord-document) MUST be followed. This JSON Schema describes the [ORD document interface](https://open-resource-discovery.org/spec-v1/interfaces/Document) of the [ORD specification](https://open-resource-discovery.org/). $schema: http://json-schema.org/draft-07/schema# $id: https://open-resource-discovery.org/spec-v1/interfaces/Document.schema.json# title: Ord Document type: object properties: $schema: type: string format: uri-reference description: >- Optional [URL](https://tools.ietf.org/html/rfc3986) to the Open Resource Discovery document schema (defined as a JSON Schema). If provided, this enables code intelligence and validation in supported editors (like VSCode) and tools. anyOf: - type: string format: uri-reference - const: >- https://open-resource-discovery.org/spec-v1/interfaces/Document.schema.json# openResourceDiscovery: type: string description: >- Version of the Open Resource Discovery specification that is used to describe this document. enum: - '1.0' - '1.1' - '1.2' - '1.3' - '1.4' - '1.5' - '1.6' - '1.7' - '1.8' - '1.9' - '1.10' - '1.11' - '1.12' examples: - '1.12' description: type: string minLength: 1 description: >- 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](https://spec.commonmark.org/) (Markdown). examples: - > This ORD document contains all APIs that are system instance aware and have APIs that can change their behavior at runtime. perspective: type: string x-introduced-in-version: 1.12.0 x-feature-status: beta description: >- With ORD it's possible to describe a system from a static or a dynamic [perspective](../index.md#perspectives) (for more details, follow the link). It is strongly RECOMMENDED to mark all static ORD documents with perspective `system-version`. It is RECOMMENDED to describe dynamic metadata in both static system-version perspective and additionally describe the system-instance perspective where it diverges from the static metadata. If not provided, this defaults to `system-instance`, which is the most precise description but also the most costly to replicate. Please read the [article on perspectives](../concepts/perspectives) for more explanations. oneOf: - const: system-version description: >- Describes the static [system-version](../index.md#def-system-version) perspective, usually known at deploy-time. If chosen, `describedSystemVersion`.`version` MUST be provided, too. This perspective describes how a system of a particular type and version generally look like. The latest system-version MAY also be interpreted as the [system-type](../index.md#def-system-type) perspective. - const: system-instance description: >- Describes the complete dynamic [system-instance](../index.md#def-system-instance) (tenant) perspective as known at run-time. This allows to also reflect tenant specific extensions, customizations and runtime configuration. If provided, it will completely override the static system-version perspective when metadata about system instances is requested. - const: system-independent description: >- Describes content that is independent of [system-versions](../index.md#def-system-version) or [system-instances](../index.md#def-system-instance). This content is always static and has independent visibility and lifecycle from the systems in a particular landscape. The "system-independent" content MUST NOT be overridden via system-version or system-instance perspective metadata. Examples are: Vendors, products, globally aligned entity types, groups and group types (taxonomy), which are usually shared by multiple systems. default: system instance examples: - system-instance describedSystemInstance: $ref: '#/definitions/SystemInstance' description: >- Information on the [system-instance](../index.md#def-system-instance) that this ORD document describes. Whether this information is required or recommended to add, depends on the requirements of the ORD aggregator. describedSystemType: $ref: '#/definitions/SystemType' x-introduced-in-version: 1.10.0 description: >- Information on the [system type](../index.md#def-system-type) that this ORD document describes. describedSystemVersion: $ref: '#/definitions/SystemVersion' x-introduced-in-version: 1.10.0 description: >- Information on the [system version](../index.md#def-system-version) that this ORD document describes. policyLevel: type: string description: > The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with. 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. anyOf: - type: string pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: none description: >- No policy level chosen. Only the base rules on how to create correct ORD documents apply. - const: custom description: >- Custom policy level. 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. default: none x-introduced-in-version: 1.3.0 examples: - sap:core:v1 customPolicyLevel: type: string description: >- 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](../index.md#specification-id). pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-introduced-in-version: 1.3.0 examples: - sap.xref:customPolicy:v1 policyLevels: type: array description: >- A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with. For each chosen policy level, additional expectations and validations rules will be applied. Policy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level. A policy level MUST be a valid [Specification ID](../index.md#specification-id). x-introduced-in-version: 1.9.9 items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:core:v1 apiResources: type: array description: Array of all API Resources that are described in this ORD document. items: $ref: '#/definitions/ApiResource' eventResources: type: array description: Array of all event resources that are described in this ORD document. items: $ref: '#/definitions/EventResource' entityTypes: type: array description: Array of all entity types that are described in this ORD document. x-introduced-in-version: 1.6.0 items: $ref: '#/definitions/EntityType' capabilities: type: array description: Array of all capabilities that are described in this ORD document. x-introduced-in-version: 1.4.0 items: $ref: '#/definitions/Capability' dataProducts: type: array description: Array of all data products that are described in this ORD document. x-introduced-in-version: 1.8.0 items: $ref: '#/definitions/DataProduct' integrationDependencies: type: array description: >- Array of all integration dependencies that are described in this ORD document. x-introduced-in-version: 1.7.0 items: $ref: '#/definitions/IntegrationDependency' vendors: type: array description: Array of all Vendors that are described in this ORD document. items: $ref: '#/definitions/Vendor' products: type: array description: Array of all Products that are described in this ORD document. items: $ref: '#/definitions/Product' packages: type: array description: Array of all Packages that are described in this ORD document. items: $ref: '#/definitions/Package' consumptionBundles: type: array description: Array of all Consumption Bundles that are described in this ORD document. items: $ref: '#/definitions/ConsumptionBundle' groups: type: array description: Array of all Groups that are described in this ORD document. x-introduced-in-version: 1.9.0 items: $ref: '#/definitions/Group' groupTypes: type: array description: Array of all Group Types that are described in this ORD document. x-introduced-in-version: 1.9.0 items: $ref: '#/definitions/GroupType' tombstones: type: array description: >- List of ORD information (resources or taxonomy) that have been "tombstoned", indicating removal or archival. This MUST be indicated explicitly, just removing the ORD information itself is not sufficient. A tombstone entry MAY be removed after a grace period of 31 days. items: $ref: '#/definitions/Tombstone' additionalProperties: false required: - openResourceDiscovery x-recommended: - policyLevels definitions: Package: type: object title: Package description: >- A [**Package**](../concepts/grouping-and-bundling#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. The package assignment of a resource MAY change, so consumers MUST not rely on this to be stable. 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](../concepts/grouping-and-bundling#package). properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.xref:package:SomePackage:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - SuccessFactorsRecruiting - 91cd9972-c05d-4d29-8b6e-dbef2a2d48e9 title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - SAP S/4HANA Cloud shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing. description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - | SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing, acts as a digital core, connecting your enterprise with people, business networks, the Internet of Things, Big Data, and more. version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 policyLevel: type: string description: > The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with. 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. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: none description: >- No policy level chosen. Only the base rules on how to create correct ORD documents apply. - const: custom description: >- Custom policy level. 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. default: none x-introduced-in-version: 1.3.0 examples: - sap:core:v1 customPolicyLevel: type: string description: >- 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](../index.md#specification-id). pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-introduced-in-version: 1.3.0 examples: - sap.xref:customPolicy:v1 policyLevels: type: array description: >- A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with. For each chosen policy level, additional expectations and validations rules will be applied. Policy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level. A policy level MUST be a valid [Specification ID](../index.md#specification-id). x-introduced-in-version: 1.9.9 items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:core:v1 packageLinks: type: array description: Links with semantic meaning that are specific to packages. items: $ref: '#/definitions/PackageLink' links: type: array description: |- Generic links with arbitrary meaning and content. `packageLinks` MUST be preferred if applicable. items: $ref: '#/definitions/Link' licenseType: type: string minLength: 1 description: |- Standardized identifier for the license. It MUST conform to the [SPDX License List](https://spdx.org/licenses). supportInfo: type: string minLength: 1 description: >- Optional information that should be provided when creating a support ticket for the resources bundled in this package. This can for example be a "component" name that needs to be chosen in the support portal. Notated in [CommonMark](https://spec.commonmark.org/) (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`. x-introduced-in-version: 1.1.0 vendor: type: string description: >- Vendor / organization that is the creator (or responsible party) of the resources that are part of the `Package`. MUST be a valid reference to a [Vendor](#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. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ maxLength: 256 x-association-target: - '#/definitions/Vendor/ordId' examples: - 'sap:vendor:SAP:' - 'customer:vendor:Customer:' - 'microsoft:vendor:Microsoft:' partOfProducts: type: array description: >- List of products the resources of the package are a part of. MUST be a valid reference to a [Product](#product) ORD ID. `partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains. items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ maxLength: 255 x-association-target: - '#/definitions/Product/ordId' minItems: 0 examples: - - 'sap:product:S4HANA_OD:' countries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). `countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - DE - US lineOfBusiness: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Asset Management - const: Commerce - const: Finance - const: Human Resources - const: Manufacturing - const: Marketing - const: R&D Engineering - const: Sales - const: Service - const: Sourcing and Procurement - const: Strategy, Compliance, and Governance - const: Supply Chain - const: Sustainability - const: Metering - const: Grid Operations and Maintenance - const: Plant Operations and Maintenance - const: Maintenance and Engineering description: >- List of line of business tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Sales industry: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Aerospace and Defense - const: Agribusiness - const: Automotive - const: Banking - const: Chemicals - const: Consumer Industries - const: Consumer Products - const: Defense and Security - const: Discrete Industries - const: Energy and Natural Resources - const: Engineering Construction and Operations - const: Financial Services - const: Future Cities - const: Healthcare - const: High Tech - const: Higher Education and Research - const: Industrial Machinery and Components - const: Insurance - const: Life Sciences - const: Media - const: Mill Products - const: Mining - const: Oil and Gas - const: Professional Services - const: Public Sector - const: Public Services - const: Retail - const: Service Industries - const: Sports and Entertainment - const: Telecommunications - const: Travel and Transportation - const: Utilities - const: Wholesale Distribution description: >- List of industry tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Automotive - - Retail - Public Sector - [] runtimeRestriction: x-introduced-in-version: 1.8.0 x-feature-status: alpha description: >- If provided, all resources that are part of this package can only run on the listed runtime. MUST be a valid [system namespace](../index.md#system-namespace). type: string pattern: ^[a-z0-9]+(?:[.][a-z0-9]+){1}$ examples: - sap.datasphere tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' required: - ordId - title - shortDescription - description - version - vendor additionalProperties: false ConsumptionBundle: type: object title: Consumption Bundle description: >- A [**Consumption Bundle**](../concepts/grouping-and-bundling#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](../concepts/grouping-and-bundling#consumption-bundle). 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](../concepts/grouping-and-bundling#consumption-bundle). properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.xref:consumptionBundle:bundleXYZ:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - SuccessFactorsRecruiting - 91cd9972-c05d-4d29-8b6e-dbef2a2d48e9 correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.s4:communicationScenario:SAP_COM_0008 title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - SAP LoB System 3 Cloud Consumption Bundle 1 shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- SAP LoB System 3 Cloud, cloud ERP suite designed for in-memory computing description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - > This consumption bundle includes all SAP LoB System 3 Cloud APIs and Events that can be consumed with the same credentials. version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 x-introduced-in-version: 1.2.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility states who is allowed to "see" the described resource or capability. oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: array x-feature-status: alpha description: >- Defines the supported strategies for how the consumption credentials can be exchanged. Ideally, the system type supports a strategy that can automate the exchange. items: $ref: '#/definitions/CredentialExchangeStrategy' links: type: array description: Generic links with arbitrary meaning and content. items: $ref: '#/definitions/Link' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' required: - ordId - title x-recommended: - lastUpdate - version additionalProperties: false ConsumptionBundleReference: type: object title: Consumption Bundle Reference description: >- Reference to a Consumption bundle. This is a complex object to allow additional properties / selections to be attached. properties: ordId: type: string description: >- The consumption bundle ORD ID (`ConsumptionBundle.ordId`) this reference points to. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-association-target: - '#/definitions/ConsumptionBundle/ordId' examples: - sap.xref:consumptionBundle:bundleXYZ:v1 defaultEntryPoint: type: string format: uri-reference description: >- In case that an API Resource has multiple entry points, this will indicate which entry point should be used by default 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. required: - ordId additionalProperties: false ApiResource: type: object title: Api Resource description: >- 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`](#api-resource_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](#package) that state this the ownership via the `vendor` property. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - API_BILL_OF_MATERIAL_SRV correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.xref:csnService:SomeLocalID title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - Process Request for Quotation shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- This service enables you to create Request for Quotation (RFQ) through an API call. description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - | This service enables you to create Request for Quotation (RFQ) through an API call from a source system outside SAP S/4HANA Cloud or SAP S/4HANA on-Premise. Furthermore, the service enables you to read existing Request for Quotation data from the SAP S/4HANA Cloud or SAP S/4HANA on-Premise. partOfPackage: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/Package/ordId' maxLength: 255 description: |- Defines which Package the resource is part of. MUST be a valid reference to a [Package](#package) ORD ID. Every resource MUST be part of one package. examples: - sap.xref:package:SomePackage:v1 partOfGroups: type: array items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ x-association-target: - '#/definitions/Group/groupId' description: >- Defines which groups the resource is assigned to. 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. partOfConsumptionBundles: type: array description: >- List of references to the consumption bundles in this resource belongs to. MUST be a valid reference to a [Consumption Bundle](#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). items: $ref: '#/definitions/ConsumptionBundleReference' examples: - - ordId: sap.xref:consumptionBundle:bundleXYZ:v1 defaultConsumptionBundle: type: string description: >- References the default consumption bundle to use for this resource. MUST be a valid reference to a [Consumption Bundle](#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. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/ConsumptionBundle/ordId' maxLength: 255 examples: - sap.xref:consumptionBundle:bundleXYZ:v1 partOfProducts: type: array description: >- List of products the resources of the package are a part of. MUST be a valid reference to a [Product](#product) ORD ID. `partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains. items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ maxLength: 255 x-association-target: - '#/definitions/Product/ordId' minItems: 0 examples: - - 'sap:product:S4HANA_OD:' version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility states who is allowed to "see" the described resource or capability. oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: string description: >- The `releaseStatus` specifies the stability of the resource and its external contract. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active disabled: type: boolean default: false description: > Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. 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. minSystemVersion: type: string description: >- The resource has been introduced in the given [system version](../index.md#def-system-version). This implies that the resource is only available if the system instance is of at least that system version. deprecationDate: type: string format: date-time description: >- 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 sunset, aka. decommissioned / removed / archived. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2020-12-08T15:47:04+00:00' sunsetDate: type: string format: date-time description: >- The sunset date defines when the resource is scheduled to be decommissioned / removed / archived. 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](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2022-01-08T15:47:04+00:00' successors: type: array description: >- The successor resource(s). 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`. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/ApiResource/ordId' maxLength: 255 examples: - - sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v2 changelogEntries: type: array description: >- Contains changelog entries that summarize changes with special regards to version and releaseStatus items: $ref: '#/definitions/ChangelogEntry' entryPoints: type: array description: >- List of [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the target host. 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](../index.md#def-base-url), a full URL MUST be provided. If the entry points are rewritten by middleware - incl. the special case of client/consumer specific entry points - it is RECOMMENDED to provide relative URLs, so only the `describedSystemInstance`.`baseUrl` has to be rewritten. The provider should not have to describe all middleware or consumer specific entry points. If they are enriched later by the aggregator, it MAY omit the entry points. **Consumer View**: When fetching the information from an ORD Aggregator, the consumer MAY rely on receiving full URLs. items: type: string format: uri-reference minItems: 0 examples: - - /api-namespace/v1 direction: type: string description: >- Direction of the API Resource consumption. 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. oneOf: - const: inbound description: >- The described system is the server. It's API Resource is available to external consumers by initiating connectivity. - const: mixed description: >- Mixed direction API Resource. This is for example the case with Webhook APIs where both a subscription endpoint exists and also callback requests are made. - const: outbound description: >- The described system is the client. It initiates connectivity to an (registered) external consumer. 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. default: inbound apiProtocol: type: string description: API Protocol including the protocol version if applicable anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: odata-v2 description: >- [OData Version 2.0](https://www.odata.org/documentation/odata-version-2-0/) API. 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`, `openapi-v3.1+`, `sap-csn-interop-effective-v1` or `custom`. - const: odata-v4 description: >- [OData Version 4](https://www.odata.org/documentation/) 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`, `openapi-v3.1+`, `sap-csn-interop-effective-v1` or `custom`. - const: rest description: >- Generic [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) 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`, `openapi-v3.1+`, `raml-v1`, `sap-csn-interop-effective-v1` or `custom`. - const: graphql description: >- [GraphQL](https://graphql.org/) 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`. - const: delta-sharing x-introduced-in-version: 1.8.0 description: >- [Delta Sharing](https://github.com/delta-io/delta-sharing/blob/main/PROTOCOL.md) Protocol, where one API Resource corresponds to a share. 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. - const: soap-inbound description: >- [SOAP](https://en.wikipedia.org/wiki/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`. - const: soap-outbound description: >- [SOAP](https://en.wikipedia.org/wiki/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`. - const: mcp description: >- [MCP](https://modelcontextprotocol.io) is an open protocol that standardizes how applications provide context to LLMs, based on JSON-RPC message format. The protocol version is negotiated at runtime via the protocol itself. Currently there is no standard API Resource definition type for MCP. - const: websocket description: >- Generic [WebSocket](https://datatracker.ietf.org/doc/html/rfc6455) 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`. - const: a2a x-introduced-in-version: 1.12.2 description: >- [A2A](https://a2a-protocol.org/latest/) is open protocol enabling communication and interoperability between opaque agentic applications. As API Resource definition the `a2a-agent-card` MUST be provided, usually put under `/.well-known/agent.json`. - const: sap-rfc description: >- [SAP RFC](https://help.sap.com/viewer/753088fc00704d0a80e7fbd6803c8adb/202009.000/en-US/4888068ad9134076e10000000a42189d.html) (Remote Function Call) is the standard SAP interface for communication between SAP systems. 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`. - const: sap-sql-api-v1 description: >- SAP SQL API that follows the [SQL interface specification for SAP ecosystem](https://github.com/SAP/sql-interface-specification). 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`. - const: sap-ina-api-v1 x-introduced-in-version: 1.8.0 description: >- SAP InA APIs are used by SAP Analytics Cloud solutions to capture data. It is an SAP proprietary protocol that only 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. examples: - rest resourceDefinitions: type: array description: >- 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. items: $ref: '#/definitions/ApiResourceDefinition' implementationStandard: type: string description: >- Declares this API to be a valid implementation of an externally standardized API contract, sub-protocol or protocol variant. All APIs that share the same implementation standard MAY be treated the same or similar by a consumer client. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: >- Any valid [Specification ID](../index.md#specification-id). If chosen, `customImplementationStandardDescription` SHOULD be provided. - const: cff:open-service-broker:v2 description: >- API follows the [Open Service Broker API V2](https://github.com/openservicebrokerapi/servicebroker). - const: custom description: >- If chosen, `customImplementationStandard` MUST be provided. If chosen, `customImplementationStandardDescription` SHOULD be provided. examples: - sap:ord-document-api:v1 customImplementationStandard: type: string description: >- If the fixed `implementationStandard` values need to be extended, an arbitrary `customImplementationStandard` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `implementationStandard` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.xref:some-api-contract:v1 customImplementationStandardDescription: type: string description: >- Full description of the custom implementation standard, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). MUST only be provided if `implementationStandard` is set to `custom`. SHOULD contain documentation and links that describe the used standard. examples: - >- Implemented as defined in the [S/4HANA Attachment Service documentation](https://api.sap.com/api/API_CV_ATTACHMENT_SRV/overview) compatibleWith: type: array description: >- A reference to the interface (API contract) that this API implements. Serves as a declaration of compatible implementation of API contract, effectively functioning as an "implementationOf" relationship. MUST be a valid reference to an (usually external) [API Resource](#api-resource) ORD ID. All APIs that share the same `compatibleWith` value MAY be treated the same or similar by a consumer client. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ examples: - - sap.s4com:apiResource:SomeSharedContract:v1 responsible: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 x-introduced-in-version: 1.8.0 description: >- Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components. examples: - sap:ach:CIC-DP-CO supportedUseCases: type: array description: >- List of use cases (types) how the resource is meant to be used for. 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. x-introduced-in-version: 1.8.0 x-feature-status: beta items: type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: data-federation description: >- Resources are designed to support [data federation](https://en.wikipedia.org/wiki/Federated_database_system). This goes beyond plain queries, but typically allowing connections on the data base level, in the context of a business user. As consumers will directly access data, performance of the system must support these use cases. - const: snapshot description: >- Resource can be used to get a snapshot with inherent consistency including potential paging requests. Such a snapshot might be the basis for incremental updates. A snapshot API is typically providing unfiltered, complete mass data access by a technical user. As data is typically replicated, performance of the API is important, but less critical for an end-user experience. - const: incremental description: Resource gives incremental updates on top of snapshots. - const: streaming description: >- Resource can be used to get streaming updates. The difference to 'incremental' is that it doesn't need a snapshot . examples: - - data-federation usage: x-introduced-in-version: 1.8.0 x-feature-status: alpha type: string title: Usage description: Define from where the API resource can be used and accessed oneOf: - const: external description: >- The API entryPoints are accessible external from the application providing it. - const: local description: >- The API is only accessible within the application providing it. Access to (in-app) development tooling is necessary. default: external entityTypeMappings: type: array x-introduced-in-version: 1.6.0 description: >- Describes mappings between the API Models of the described resource to the underlying, conceptual entity types. items: $ref: '#/definitions/EntityTypeMapping' exposedEntityTypes: type: array x-introduced-in-version: 1.11.0 description: >- Optional list of [entity types](#entity-type) that are exposed by the resource. This replaces `entityTypeMappings`. If both is given, the `exposedEntityTypes` wins. MUST be a valid reference to an [EntityType](#entity-type) ORD ID. items: $ref: '#/definitions/ExposedEntityType' examples: - - ordId: sap.odm:entityType:WorkforcePerson:v1 - - ordId: sap.sm:entityType:PurchaseOrderItem:v1 - ordId: sap.sm:entityType:BusinessPartner:v1 apiResourceLinks: type: array description: Links with semantic meaning that are specific to API Resources. items: $ref: '#/definitions/APIEventResourceLink' links: type: array description: >- Generic Links with arbitrary meaning and content. If applicable, `apiResourceLinks` MUST be used instead of generic `links`. items: $ref: '#/definitions/Link' extensible: $ref: '#/definitions/Extensible' countries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). `countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - DE - US lineOfBusiness: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Asset Management - const: Commerce - const: Finance - const: Human Resources - const: Manufacturing - const: Marketing - const: R&D Engineering - const: Sales - const: Service - const: Sourcing and Procurement - const: Strategy, Compliance, and Governance - const: Supply Chain - const: Sustainability - const: Metering - const: Grid Operations and Maintenance - const: Plant Operations and Maintenance - const: Maintenance and Engineering description: >- List of line of business tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Sales industry: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Aerospace and Defense - const: Agribusiness - const: Automotive - const: Banking - const: Chemicals - const: Consumer Industries - const: Consumer Products - const: Defense and Security - const: Discrete Industries - const: Energy and Natural Resources - const: Engineering Construction and Operations - const: Financial Services - const: Future Cities - const: Healthcare - const: High Tech - const: Higher Education and Research - const: Industrial Machinery and Components - const: Insurance - const: Life Sciences - const: Media - const: Mill Products - const: Mining - const: Oil and Gas - const: Professional Services - const: Public Sector - const: Public Services - const: Retail - const: Service Industries - const: Sports and Entertainment - const: Telecommunications - const: Travel and Transportation - const: Utilities - const: Wholesale Distribution description: >- List of industry tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Automotive - - Retail - Public Sector - [] tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' policyLevel: type: string description: > The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with. 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. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: none description: >- No policy level chosen. Only the base rules on how to create correct ORD documents apply. - const: custom description: >- Custom policy level. 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. default: none x-introduced-in-version: 1.3.0 examples: - sap:core:v1 customPolicyLevel: type: string description: >- 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](../index.md#specification-id). pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-introduced-in-version: 1.3.0 examples: - sap.xref:customPolicy:v1 policyLevels: type: array description: >- A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with. For each chosen policy level, additional expectations and validations rules will be applied. Policy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level. A policy level MUST be a valid [Specification ID](../index.md#specification-id). x-introduced-in-version: 1.9.9 items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:core:v1 systemInstanceAware: type: boolean description: >- All resources that are [system instance aware](../index.md#def-system-instance-aware) should now be put together in one ORD document that has `perspective`: `system-instance`. All resources that are [system instance unaware](../index.md#def-system-instance-unaware) should now be put together in one ORD document that has `perspective`: `system-version`. 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**. default: false examples: - true required: - ordId - title - shortDescription - description - version - releaseStatus - apiProtocol - visibility - partOfPackage additionalProperties: false EventResource: type: object title: Event Resource description: >- The event resource provides a high-level description of a collection of related Events. More detailed information, such as the event resource definitions, are provided in links in the table below. 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`](#event-resource_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](#package) that state this the ownership via the `vendor` property. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1 - sap.s4:eventResource:BillofMaterialEvents:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - BusinessEvents_SubscriptionEvents correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.xref:localConcept:SomeLocalId title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - SalesOrder Events - System XYZ Events shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - All events related to the Business Object SalesOrder description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - > This event is raised by the SAP S/4HANA Cloud system when an invoice document is cancelled. partOfPackage: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/Package/ordId' maxLength: 255 description: |- Defines which Package the resource is part of. MUST be a valid reference to a [Package](#package) ORD ID. Every resource MUST be part of one package. examples: - sap.xref:package:SomePackage:v1 partOfGroups: type: array items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ x-association-target: - '#/definitions/Group/groupId' description: >- Defines which groups the resource is assigned to. 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. partOfConsumptionBundles: type: array description: >- List of references to the consumption bundles in this resource belongs to. MUST be a valid reference to a [Consumption Bundle](#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). items: $ref: '#/definitions/ConsumptionBundleReference' examples: - - ordId: sap.xref:consumptionBundle:bundleXYZ:v1 defaultConsumptionBundle: type: string description: >- References the default consumption bundle to use for this resource. MUST be a valid reference to a [Consumption Bundle](#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. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/ConsumptionBundle/ordId' maxLength: 255 examples: - sap.xref:consumptionBundle:bundleXYZ:v1 partOfProducts: type: array description: >- List of products the resources of the package are a part of. MUST be a valid reference to a [Product](#product) ORD ID. `partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains. items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ maxLength: 255 x-association-target: - '#/definitions/Product/ordId' minItems: 0 examples: - - 'sap:product:S4HANA_OD:' version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility states who is allowed to "see" the described resource or capability. oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: string description: >- The `releaseStatus` specifies the stability of the resource and its external contract. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active disabled: type: boolean default: false description: > Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. 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. minSystemVersion: type: string description: >- The resource has been introduced in the given [system version](../index.md#def-system-version). This implies that the resource is only available if the system instance is of at least that system version. deprecationDate: type: string format: date-time description: >- 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 sunset, aka. decommissioned / removed / archived. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2020-12-08T15:47:04+00:00' sunsetDate: type: string format: date-time description: >- The sunset date defines when the resource is scheduled to be decommissioned / removed / archived. 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](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2022-01-08T15:47:04+00:00' successors: type: array description: >- The successor resource(s). 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`. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-association-target: - '#/definitions/EventResource/ordId' examples: - - sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1 changelogEntries: type: array description: >- Contains changelog entries that summarize changes with special regards to version and releaseStatus items: $ref: '#/definitions/ChangelogEntry' resourceDefinitions: type: array description: >- List of available machine-readable definitions, which describe the resource or capability in detail. 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. items: $ref: '#/definitions/EventResourceDefinition' implementationStandard: type: string description: >- 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. anyOf: - type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: >- Any valid [API Resource ORD ID](../index.md#api-resource_ordid). RECOMMENDED to use if the contract is published via ORD and has an ORD ID. - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: >- Any valid [Specification ID](../index.md#specification-id). If chosen, `customImplementationStandardDescription` SHOULD be provided. - const: custom description: >- If chosen, a custom implementation standard MUST be provided via `customImplementationStandard` and SHOULD be described via `customImplementationStandardDescription` examples: - custom customImplementationStandard: type: string description: >- If the fixed `implementationStandard` values need to be extended, an arbitrary `customImplementationStandard` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `implementationStandard` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.xref:some-event-contract:v1 customImplementationStandardDescription: type: string description: >- Full description of the custom implementation standard, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). MUST only be provided if `implementationStandard` is set to `custom`. SHOULD contain documentation and links that describe the used standard. examples: - >- Implemented as defined in [Some Application Documentation](some link). compatibleWith: type: array description: >- Declares this event resource is a compatible implementation of the referenced contract. This is also sometimes known as [Service Provider Interface](https://en.wikipedia.org/wiki/Service_provider_interface). MUST be a valid reference to an (usually external) [Event Resource](#event-resource) ORD ID. All event resources that share the same `compatibleWith` value MAY be treated the same or similar by a consumer client. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ examples: - - sap.s4com:eventResource:SomeSharedContract:v1 responsible: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 x-introduced-in-version: 1.8.0 description: >- Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components. examples: - sap:ach:CIC-DP-CO entityTypeMappings: type: array x-introduced-in-version: 1.6.0 description: >- Describes mappings between the API Models of the described resource to the underlying, conceptual entity types. items: $ref: '#/definitions/EntityTypeMapping' exposedEntityTypes: type: array x-introduced-in-version: 1.11.0 description: >- Optional list of [entity types](#entity-type) that are exposed by the resource. This replaces `entityTypeMappings`. If both is given, the `exposedEntityTypes` wins. MUST be a valid reference to an [EntityType](#entity-type) ORD ID. items: $ref: '#/definitions/ExposedEntityType' examples: - - ordId: sap.odm:entityType:WorkforcePerson:v1 - - ordId: sap.sm:entityType:PurchaseOrderItem:v1 - ordId: sap.sm:entityType:BusinessPartner:v1 eventResourceLinks: type: array x-introduced-in-version: 1.7.1 description: >- Links with semantic meaning that are specific to event resources. If applicable, `eventResourceLinks` MUST be used instead of generic `links`. items: $ref: '#/definitions/APIEventResourceLink' links: type: array description: Generic Links with arbitrary meaning and content. items: $ref: '#/definitions/Link' extensible: $ref: '#/definitions/Extensible' countries: type: array items: type: string pattern: ^[A-Z]{2}$ description: >- List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). `countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - DE - US lineOfBusiness: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Asset Management - const: Commerce - const: Finance - const: Human Resources - const: Manufacturing - const: Marketing - const: R&D Engineering - const: Sales - const: Service - const: Sourcing and Procurement - const: Strategy, Compliance, and Governance - const: Supply Chain - const: Sustainability - const: Metering - const: Grid Operations and Maintenance - const: Plant Operations and Maintenance - const: Maintenance and Engineering description: >- List of line of business tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Sales industry: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Aerospace and Defense - const: Agribusiness - const: Automotive - const: Banking - const: Chemicals - const: Consumer Industries - const: Consumer Products - const: Defense and Security - const: Discrete Industries - const: Energy and Natural Resources - const: Engineering Construction and Operations - const: Financial Services - const: Future Cities - const: Healthcare - const: High Tech - const: Higher Education and Research - const: Industrial Machinery and Components - const: Insurance - const: Life Sciences - const: Media - const: Mill Products - const: Mining - const: Oil and Gas - const: Professional Services - const: Public Sector - const: Public Services - const: Retail - const: Service Industries - const: Sports and Entertainment - const: Telecommunications - const: Travel and Transportation - const: Utilities - const: Wholesale Distribution description: >- List of industry tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Automotive - - Retail - Public Sector - [] tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' policyLevel: type: string description: > The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with. 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. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: none description: >- No policy level chosen. Only the base rules on how to create correct ORD documents apply. - const: custom description: >- Custom policy level. 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. default: none x-introduced-in-version: 1.3.0 examples: - sap:core:v1 customPolicyLevel: type: string description: >- 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](../index.md#specification-id). pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-introduced-in-version: 1.3.0 examples: - sap.xref:customPolicy:v1 policyLevels: type: array description: >- A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with. For each chosen policy level, additional expectations and validations rules will be applied. Policy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level. A policy level MUST be a valid [Specification ID](../index.md#specification-id). x-introduced-in-version: 1.9.9 items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:core:v1 systemInstanceAware: type: boolean description: >- All resources that are [system instance aware](../index.md#def-system-instance-aware) should now be put together in one ORD document that has `perspective`: `system-instance`. All resources that are [system instance unaware](../index.md#def-system-instance-unaware) should now be put together in one ORD document that has `perspective`: `system-version`. 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**. default: false examples: - true additionalProperties: false required: - ordId - title - shortDescription - description - version - visibility - partOfPackage - releaseStatus x-recommended: - lastUpdate EntityType: type: object title: Entity Type description: >- An [**Entity Type**](../concepts/grouping-and-bundling#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](../concepts/grouping-and-bundling#entity-type). x-introduced-in-version: 1.8.0 properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.odm:entityType:BusinessPartner:v1 - sap.odm:entityType:CostCenter:v1 - sap.odm:entityType:WorkforcePerson:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - BusinessPartner - CostCenter - WorkforcePerson correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.s4:sot:BusinessPartner - - sap.s4:sot:CostCenter - - sap.s4:sot:WorkforcePerson title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - Business Partner - Cost Center - Workforce Person shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- A business partner is a person, an organization, or a group of persons or organizations in which a company has a business interest. - >- A cost center is an organizational center where costs are incurred and for which costs are recorded separately. - >- A workforce person is a natural person with a work agreement or relationship in form of a work assignment; it can be an employee or a contingent worker. description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - > A business partner is a person, an organization, or a group of persons or organizations in which a company has a business interest. - > 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. partOfPackage: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/Package/ordId' maxLength: 255 description: |- Defines which Package the resource is part of. MUST be a valid reference to a [Package](#package) ORD ID. Every resource MUST be part of one package. examples: - sap.xref:package:SomePackage:v1 partOfGroups: type: array items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ x-association-target: - '#/definitions/Group/groupId' description: >- Defines which groups the resource is assigned to. 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. partOfProducts: type: array description: >- List of products the resources of the package are a part of. MUST be a valid reference to a [Product](#product) ORD ID. `partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains. items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ maxLength: 255 x-association-target: - '#/definitions/Product/ordId' minItems: 0 examples: - - 'sap:product:S4HANA_OD:' version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility states who is allowed to "see" the described resource or capability. oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: string description: >- The `releaseStatus` specifies the stability of the resource and its external contract. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active deprecationDate: type: string format: date-time description: >- The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the `sunsetDate` which defines when the resource will be actually sunset, aka. decommissioned / removed / archived. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2020-12-08T15:47:04+00:00' sunsetDate: type: string format: date-time description: >- The sunset date defines when the resource is scheduled to be decommissioned / removed / archived. 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](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2022-01-08T15:47:04+00:00' successors: type: array description: >- The successor resource(s). 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`. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/EntityType/ordId' maxLength: 255 examples: - - sap.odm:entityType:BusinessPartner:v2 - - sap.odm:entityType:CostCenter:v2 - - sap.odm:entityType:WorkforcePerson:v2 changelogEntries: type: array description: >- Contains changelog entries that summarize changes with special regards to version and releaseStatus items: $ref: '#/definitions/ChangelogEntry' level: type: string description: >- Defining the abstraction level of the entity type using the DDD terminology. 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](https://martinfowler.com/bliki/DDD_Aggregate.html) oneOf: - const: aggregate description: >- An aggregate is the combined tree of entity types (combined via composition). The root entity gives the aggregate its identity and ID. The inner structure of an aggregate (sub entities, field, etc.) could be described in the entity type definition. - const: root-entity description: >- Represents only the root entity (aka DDD aggregate root). Potential composite sub-entities are NOT included (unlike with `aggregate`). - const: sub-entity description: >- Represents an individual sub entity (aka composite entity). Describing it in ORD may be necessary if the sub-entities need a dedicated ORD ID. However, we recommend not to expose the internal structure of aggregate if possible. examples: - aggregate relatedEntityTypes: type: array x-introduced-in-version: 1.9.0 description: >- States that this Entity Type is related to another Entity Type. Usually this happens if there are similar conceptual entity types across different namespaces. items: $ref: '#/definitions/RelatedEntityType' examples: - - ordId: sap.odm:entityType:WorkforcePerson:v1 links: type: array description: Generic Links with arbitrary meaning and content. items: $ref: '#/definitions/Link' extensible: $ref: '#/definitions/Extensible' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' policyLevel: type: string description: > The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with. 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. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: none description: >- No policy level chosen. Only the base rules on how to create correct ORD documents apply. - const: custom description: >- Custom policy level. 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. default: none x-introduced-in-version: 1.3.0 examples: - sap:core:v1 customPolicyLevel: type: string description: >- 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](../index.md#specification-id). pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-introduced-in-version: 1.3.0 examples: - sap.xref:customPolicy:v1 policyLevels: type: array description: >- A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with. For each chosen policy level, additional expectations and validations rules will be applied. Policy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level. A policy level MUST be a valid [Specification ID](../index.md#specification-id). x-introduced-in-version: 1.9.9 items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:core:v1 systemInstanceAware: type: boolean description: >- All resources that are [system instance aware](../index.md#def-system-instance-aware) should now be put together in one ORD document that has `perspective`: `system-instance`. All resources that are [system instance unaware](../index.md#def-system-instance-unaware) should now be put together in one ORD document that has `perspective`: `system-version`. 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**. default: false examples: - true additionalProperties: false required: - ordId - localId - level - title - version - visibility - partOfPackage - releaseStatus x-recommended: - lastUpdate DataProduct: type: object title: Data Product x-introduced-in-version: 1.8.0 description: >- A [Data Product](../concepts/data-product) is a data set exposed for consumption outside the boundaries of the producing application via APIs and described by high quality metadata that can be accessed through the [ORD Aggregator](../../spec-v1/#ord-aggregator). Please note that this concept is in beta, see [Data Product - Beta Status](../concepts/data-product#beta-status). properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.foo.bar:dataProduct:CustomerOrder:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - CustomerOrder correlationIds: x-feature-status: beta type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.s4:communicationScenario:SAP_COM_0008 title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - Customer Order shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- Offering access to all online and offline orders submitted by customers description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - >- The data product Customer Order offers access to all online and offline orders submitted by customers. It provides a customer view on the orders. For fulfillment-specific aspects please refer to the data product Fulfillment Order. partOfPackage: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/Package/ordId' maxLength: 255 description: |- Defines which Package the resource is part of. MUST be a valid reference to a [Package](#package) ORD ID. Every resource MUST be part of one package. examples: - sap.xref:package:SomePackage:v1 partOfGroups: type: array items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ x-association-target: - '#/definitions/Group/groupId' description: >- Defines which groups the resource is assigned to. 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. x-feature-status: beta partOfProducts: type: array description: >- List of products this Data Product is a part of or is related to, its e.g. data source systems. MUST be a valid reference to a [Product](#product) ORD ID. `partOfProducts` that are assigned to a `Package` are inherited to all of the ORD resources it contains. items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ maxLength: 255 x-association-target: - '#/definitions/Product/ordId' minItems: 0 examples: - - 'sap:product:S4HANA_OD:' version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility/exposure of the data product. A public data product might have private APIs for trusted consumers therefore the having the property on data product oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: string description: >- 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`. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active disabled: x-feature-status: beta type: boolean default: false description: > Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. 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. minSystemVersion: type: string description: >- The resource has been introduced in the given [system version](../index.md#def-system-version). This implies that the resource is only available if the system instance is of at least that system version. lifecycleStatus: type: string description: >- 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. oneOf: - const: inactive description: The data product is currently inactive, but can be provisioned. - const: provisioning description: >- The data product is currently being provisioned / installed and is not yet ready to be used. This includes acquiring data from input ports, potentially necessary transformation and making the data available in the output ports. - const: active description: >- 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. - const: deprovisioning description: >- 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. - const: active-with-errors description: >- 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. - const: provisioning-error description: The provisioning of the data product failed with error(s). - const: deprovisioning-error description: >- The deprovisioning of the data product failed with error(s). Consistent usage of the data product is not guaranteed until all errors are resolved. examples: - active deprecationDate: x-feature-status: beta type: string format: date-time description: >- The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the `sunsetDate` which defines when the resource will be actually sunset, aka. decommissioned / removed / archived. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2020-12-08T15:47:04+00:00' sunsetDate: x-feature-status: beta type: string format: date-time description: >- The sunset date defines when the resource is scheduled to be decommissioned / removed / archived. 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](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2022-01-08T15:47:04+00:00' successors: x-feature-status: beta type: array description: >- The successor resource(s). 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`. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-association-target: - '#/definitions/DataProduct/ordId' examples: - - sap.foo.bar:dataProduct:CustomerOrder:v1 changelogEntries: x-feature-status: beta type: array description: >- Contains changelog entries that summarize changes with special regards to version and releaseStatus items: $ref: '#/definitions/ChangelogEntry' type: description: >- Type of the data product. Based on the type some properties of a data product may become optional/mandatory. type: string oneOf: - const: primary description: >- A producer aligned data product, aka primary data product. Such a data product will be typically served directly from an application and might not have input ports. - const: derived description: >- A data product that typically aggregates and combines data from multiple sources to provider value added data sets on top. 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. examples: - primary category: description: >- Category of the data-set within data product. Based on its definition, a data product is a "data set" - which can include on the values below. 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. type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: business-object description: 'Business Objects: master data, transaction data' - const: analytical description: Analytical data, including cubes, KPIs and metrics - const: other description: 'Other objects, eg: config data, mixed or just unspecified' examples: - business-object entityTypes: x-feature-status: beta type: array description: >- Aggregated list of entity types that are at least partially exposed by the data product. Detailed mapping can be found on the output port schema level. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-association-target: - '#/definitions/EntityType/ordId' examples: - - sap.odm:entityType:CustomerOrder:v1 - sap.odm:entityType:BusinessPartner:v1 inputPorts: x-feature-status: beta type: array description: >- The input ports of a data product indicate the data inputs for lineage purposes. 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. minItems: 0 items: $ref: '#/definitions/DataProductInputPort' examples: - - ordId: sap.xref:integrationDependency:CustomerOrder:v1 outputPorts: type: array description: >- Output ports are the interface (APIs and Events) through which the data of the data product can be accessed. 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. minItems: 1 items: $ref: '#/definitions/DataProductOutputPort' examples: - - ordId: sap.cic:apiResource:RetailTransactionOData:v1 - ordId: sap.cic:eventResource:RawCustomerOrder:v2 responsible: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 x-introduced-in-version: 1.8.0 description: >- Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components. examples: - sap:ach:CIC-DP-CO dataProductLinks: x-feature-status: beta type: array description: >- Links with semantic meaning that are specific to Data Product Resources. items: $ref: '#/definitions/DataProductLink' links: x-feature-status: beta type: array description: Generic Links with arbitrary meaning and content. items: $ref: '#/definitions/Link' industry: x-feature-status: beta type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Aerospace and Defense - const: Agribusiness - const: Automotive - const: Banking - const: Chemicals - const: Consumer Industries - const: Consumer Products - const: Defense and Security - const: Discrete Industries - const: Energy and Natural Resources - const: Engineering Construction and Operations - const: Financial Services - const: Future Cities - const: Healthcare - const: High Tech - const: Higher Education and Research - const: Industrial Machinery and Components - const: Insurance - const: Life Sciences - const: Media - const: Mill Products - const: Mining - const: Oil and Gas - const: Professional Services - const: Public Sector - const: Public Services - const: Retail - const: Service Industries - const: Sports and Entertainment - const: Telecommunications - const: Travel and Transportation - const: Utilities - const: Wholesale Distribution description: >- List of industry tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `industry` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Automotive - - Retail - Public Sector - [] lineOfBusiness: x-feature-status: beta type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/& ]*$ minLength: 1 anyOf: - type: string - const: Asset Management - const: Commerce - const: Finance - const: Human Resources - const: Manufacturing - const: Marketing - const: R&D Engineering - const: Sales - const: Service - const: Sourcing and Procurement - const: Strategy, Compliance, and Governance - const: Supply Chain - const: Sustainability - const: Metering - const: Grid Operations and Maintenance - const: Plant Operations and Maintenance - const: Maintenance and Engineering description: >- List of line of business tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. `lineOfBusiness` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - Sales countries: x-feature-status: beta type: array items: type: string pattern: ^[A-Z]{2}$ description: >- List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to [IES ISO-3166 ALPHA-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). `countries` that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - DE - US tags: x-feature-status: beta type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: x-feature-status: beta $ref: '#/definitions/Labels' documentationLabels: x-feature-status: beta $ref: '#/definitions/DocumentationLabels' policyLevel: x-feature-status: beta type: string description: > The [policy level](../../spec-extensions/policy-levels/) (aka. compliance level) that the described resources need to be compliant with. 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. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: none description: >- No policy level chosen. Only the base rules on how to create correct ORD documents apply. - const: custom description: >- Custom policy level. 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. default: none x-introduced-in-version: 1.3.0 examples: - sap:core:v1 customPolicyLevel: x-feature-status: beta type: string description: >- If the fixed `policyLevel` values need to be extended, an arbitrary `customPolicyLevel` can be provided. 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](../index.md#specification-id). pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-introduced-in-version: 1.3.0 examples: - sap.xref:customPolicy:v1 policyLevels: type: array description: >- A list of [policy levels](../../spec-extensions/policy-levels/) that the described resources need to be compliant with. For each chosen policy level, additional expectations and validations rules will be applied. Policy levels can be defined on ORD Document level, but also be overwritten on an individual package or resource level. A policy level MUST be a valid [Specification ID](../index.md#specification-id). x-introduced-in-version: 1.9.9 items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:core:v1 systemInstanceAware: x-feature-status: beta type: boolean description: >- All resources that are [system instance aware](../index.md#def-system-instance-aware) should now be put together in one ORD document that has `perspective`: `system-instance`. All resources that are [system instance unaware](../index.md#def-system-instance-unaware) should now be put together in one ORD document that has `perspective`: `system-version`. 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**. default: false examples: - true additionalProperties: false required: - ordId - type - category - title - shortDescription - description - version - releaseStatus - visibility - partOfPackage - responsible - outputPorts x-recommended: - lastUpdate DataProductInputPort: type: object title: Data Product Input Port description: >- An input port of a data product states where it retrieves its data inputs from. It is described as via an ORD Integration Dependency. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.foo.bar:integrationDependency:CustomerOrder:v1 x-association-target: - '#/definitions/IntegrationDependency/ordId' additionalProperties: false required: - ordId DataProductOutputPort: type: object title: Data Product Output Port description: >- 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. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource|eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.cic:apiResource:RetailTransactionOData:v1 - sap.cic:eventResource:RawCustomerOrder:v2 x-association-target: - '#/definitions/ApiResource/ordId' - '#/definitions/EventResource/ordId' additionalProperties: false required: - ordId ApiResourceDefinition: type: object title: Api Resource Definition description: |- Link and categorization of a machine-readable API definition. For example, OpenAPI definition, OData Metadata, etc. properties: type: description: |- Type of the API Resource Definition If "custom" is chosen, a customType MUST be provided type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: openapi-v2 description: >- [OpenAPI 2 / Swagger 2](https://spec.openapis.org/oas/v2.0.html) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs. The `mediaType` MUST be be set to either `application/json` or `text/yaml`. - const: openapi-v3 description: >- [OpenAPI 3.0.x](https://spec.openapis.org/oas/v3.0.4.html) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs. The `mediaType` MUST be be set to either `application/json` or `text/yaml`. For OpenAPI 3.1+, `openapi-v3.1+` MUST be used instead, as it's not backward compatible with OpenAPI 3.0. - const: openapi-v3.1+ description: >- [OpenAPI 3.1+](https://spec.openapis.org/oas/v3.1.1.html) (3.1 or greater, but below 4.x) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs. The `mediaType` MUST be be set to either `application/json` or `text/yaml`. - const: raml-v1 description: >- [RAML](https://raml.org/) API Definition for [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) APIs. The `mediaType` MUST be be set to `text/yaml`. - const: edmx description: >- [OData](https://www.odata.org/documentation/) APIs can be described via edmx XML files. For OData V2 APIs, this is standardized through the [Common Schema Definition Language (CSDL) V2](https://www.odata.org/documentation/odata-version-2-0/overview/#ServiceMetadataDocument). For OData V4 APIs, this is standardized through the [CSDL XML Representation](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html) The `mediaType` MUST be be set to `application/xml`. The `apiProtocol` MUST be set to `odata-v2` or `odata-v4`. - const: csdl-json description: >- [OData](https://www.odata.org/documentation/) V4 APIs can also be described via the [OData Common Schema Definition Language (CSDL) JSON Representation](https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html). The `mediaType` MUST be be set to `application/json`. The `apiProtocol` MUST be set to `odata-v2` or `odata-v4`. - const: graphql-sdl description: >- [GraphQL](https://graphql.org/) APIs can be described via the [GraphQL Schema Definition Language](https://graphql.org/learn/schema/). See also: [GraphQL Specification > Type System](https://spec.graphql.org/October2021/#sec-Type-System). The `mediaType` MUST be be set to `text/plain`. The `apiProtocol` MUST be set to `graphql`. - const: wsdl-v1 description: >- [WSDL 1](https://www.w3.org/TR/wsdl.html) API Definition for [SOAP](https://en.wikipedia.org/wiki/SOAP) APIs. The `mediaType` MUST be be set to `application/xml`. The `apiProtocol` MUST be set to `soap-inbound` or `soap-outbound`. - const: wsdl-v2 description: >- [WSDL 2](https://www.w3.org/TR/2007/REC-wsdl20-20070626/) API Definition for [SOAP](https://en.wikipedia.org/wiki/SOAP) APIs. The `mediaType` MUST be be set to `application/xml`. The `apiProtocol` MUST be set to `soap-inbound` or `soap-outbound`. - const: a2a-agent-card description: >- [A2A Agent Card](https://a2a-protocol.org/topics/agent-discovery/) is a machine-readable description of an A2A Agent. The `mediaType` MUST be be set to `application/json`. The `apiProtocol` MUST be set to `a2a`. x-introduced-in-version: 1.12.2 - const: sap-rfc-metadata-v1 description: >- Proprietary metadata description format for [SAP RFC](https://help.sap.com/viewer/753088fc00704d0a80e7fbd6803c8adb/202009.000/en-US/4888068ad9134076e10000000a42189d.html). The `mediaType` MUST be be set to `application/xml`. - const: sap-sql-api-definition-v1 description: >- Metadata description format for SAP SQL API, following the [SQL interface specification for SAP ecosystem](https://github.com/SAP/sql-interface-specification). The `mediaType` MUST be be set to `application/json`. The `apiProtocol` MUST be set to `sap-sql-api-v1`. x-introduced-in-version: 1.9.4 - const: sap-csn-interop-effective-v1 description: >- [CSN Interop Effective](https://sap.github.io/csn-interop-specification/) is a standardized and interoperable [CSN](https://cap.cloud.sap/docs/cds/csn) export, used to describe [CDS](https://cap.cloud.sap/docs/cds/) models. The `mediaType` MUST be be set to `application/json`. x-introduced-in-version: 1.9.4 - const: custom description: If chosen, `customType` MUST be provided. examples: - openapi-v3 customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:custom-definition-format:v1 mediaType: description: > The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format. 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. type: string oneOf: - const: application/json - const: application/xml - const: text/yaml - const: text/plain description: >- For a plain-text format where no other serialization Media Type fits - const: application/octet-stream description: For a binary format where no other serialization Media Type fits examples: - application/json url: type: string format: uri-reference description: >- [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). examples: - /api/openApi.yaml - https://example.com/api/API_RFQ_PROCESS_SRV/$metadata accessStrategies: type: array description: >- 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. items: $ref: '#/definitions/AccessStrategy' minItems: 1 examples: - - type: open additionalProperties: false required: - type - mediaType - url EventResourceDefinition: type: object title: Event Resource Definition description: |- Link and categorization of a machine-readable API definition. For example, AsyncAPI or OpenAPI with callbacks, etc. properties: type: description: Type of the event resource definition type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: asyncapi-v2 description: >- [AsyncAPI 2](https://www.asyncapi.com/docs/specifications/2.0.0) API definition for events. The SAP Event Catalog Specification also falls under this category, as it is a valid AsyncAPI definition. - const: sap-csn-interop-effective-v1 description: >- [CSN Interop Effective](https://sap.github.io/csn-interop-specification/) is a standardized and interoperable flavor of [CSN](https://cap.cloud.sap/docs/cds/csn). CSN is a notation for compact representations of [CDS](https://cap.cloud.sap/docs/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`. - const: custom description: If chosen, `customType` MUST be provided. examples: - asyncapi-v2 customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:custom-definition-format:v1 mediaType: description: > The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format. 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. type: string oneOf: - const: application/json - const: application/xml - const: text/yaml - const: text/plain description: >- For a plain-text format where no other serialization Media Type fits - const: application/octet-stream description: For a binary format where no other serialization Media Type fits examples: - application/json url: type: string format: uri-reference description: >- [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). examples: - /some/url/events/eventCatalog.json accessStrategies: type: array description: >- List of supported access strategies for retrieving metadata from the ORD provider. 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. items: $ref: '#/definitions/AccessStrategy' minItems: 1 examples: - - type: open additionalProperties: false required: - type - mediaType - url Product: type: object title: Product description: >- 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. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ maxLength: 255 examples: - 'sap:product:S4HANA_OD:' correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.xref:product:ABC title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - SAP S/4HANA Cloud shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- The next generation digital core designed to help you run simple in a digital economy. description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: [] vendor: type: string description: |- Vendor / organization that is responsible for the Product. MUST be a valid reference to a [Vendor](#vendor) ORD ID. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ maxLength: 256 x-association-target: - '#/definitions/Vendor/ordId' examples: - 'sap:vendor:SAP:' - 'customer:vendor:Customer:' - 'microsoft:vendor:Microsoft:' parent: type: string description: >- Optional product parent ORD ID, if a hierarchical product structure needs to be expressed. MUST be a valid reference to a [Product](#product) ORD ID. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ x-association-target: - '#/definitions/Product/ordId' examples: - 'sap:product:S4HANA_OD:' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' additionalProperties: false required: - ordId - title - shortDescription - vendor Capability: type: object title: Capability x-introduced-in-version: 1.4.0 description: >- Capabilities can be used to describe use case specific capabilities, most notably supported features or additional information (like configuration) that needs to be understood from outside. 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. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(capability):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.foo.bar:capability:fieldExtensibility:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - SuccessFactorsRecruiting - 91cd9972-c05d-4d29-8b6e-dbef2a2d48e9 correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.s4:communicationScenario:SAP_COM_0008 type: description: Type of the Capability type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: sap.mdo:mdi-capability:v1 description: >- Capability for SAP Master Data Integration (MDI). For the capability definitions: `type` MUST ONLY be set to `sap.mdo:mdi-capability-definition:v1`. - const: custom description: If chosen, `customType` MUST be provided. examples: - custom customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:custom-definition-format:v1 title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - MDI Capability shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing. description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - | SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing, acts as a digital core, connecting your enterprise with people, business networks, the Internet of Things, Big Data, and more. partOfPackage: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/Package/ordId' maxLength: 255 description: |- Defines which Package the resource is part of. MUST be a valid reference to a [Package](#package) ORD ID. Every resource MUST be part of one package. examples: - sap.xref:package:SomePackage:v1 partOfGroups: type: array items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ x-association-target: - '#/definitions/Group/groupId' description: >- Defines which groups the resource is assigned to. 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. version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility states who is allowed to "see" the described resource or capability. oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: string description: >- The `releaseStatus` specifies the stability of the resource and its external contract. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active disabled: type: boolean default: false description: > Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. 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. minSystemVersion: type: string description: >- The resource has been introduced in the given [system version](../index.md#def-system-version). This implies that the resource is only available if the system instance is of at least that system version. relatedEntityTypes: type: array description: >- Optional list of related EntityType Resources. MUST be a valid reference to an [EntityType Resource](#entity-type) ORD ID. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/EntityType/ordId' examples: - - sap.odm:entityType:WorkforcePerson:v1 definitions: type: array description: >- 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. items: $ref: '#/definitions/CapabilityDefinition' links: type: array description: Generic Links with arbitrary meaning and content. items: $ref: '#/definitions/Link' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' systemInstanceAware: type: boolean description: >- All resources that are [system instance aware](../index.md#def-system-instance-aware) should now be put together in one ORD document that has `perspective`: `system-instance`. All resources that are [system instance unaware](../index.md#def-system-instance-unaware) should now be put together in one ORD document that has `perspective`: `system-version`. 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**. default: false examples: - true additionalProperties: false required: - ordId - type - title - version - releaseStatus - visibility - partOfPackage x-recommended: - lastUpdate CapabilityDefinition: type: object title: Capability Definition x-introduced-in-version: 1.4.0 description: Link and categorization of a machine-readable capability definition. properties: type: description: Type of the capability resource definition type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: sap.mdo:mdi-capability-definition:v1 description: >- Specification for describing master data integration capabilities for Master Data Orchestration (MDO). The `mediaType` MUST be set to `application/json`. The capability `type` MUST be set to `sap.mdo:mdi-capability:v1`. - const: custom description: If chosen, a custom type MUST be provided via `customType` examples: - custom customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:custom-definition-format:v1 mediaType: description: > The [Media Type](https://www.iana.org/assignments/media-types/media-types.xhtml) of the definition serialization format. 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. type: string oneOf: - const: application/json - const: application/xml - const: text/yaml - const: text/plain description: >- For a plain-text format where no other serialization Media Type fits - const: application/octet-stream description: For a binary format where no other serialization Media Type fits examples: - application/json url: type: string format: uri-reference description: >- [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). examples: - /capabilities/someCapability/someDocument.json accessStrategies: type: array description: >- List of supported access strategies for retrieving metadata from the ORD provider. 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. items: $ref: '#/definitions/AccessStrategy' minItems: 1 examples: - - type: open additionalProperties: false required: - type - mediaType - url IntegrationDependency: type: object title: Integration Dependency x-introduced-in-version: 1.7.0 description: >- An [Integration Dependency](../concepts/integration-dependency) states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose. 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](../concepts/integration-dependency). properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.foo.bar:integrationDependency:CustomerOrder:v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: - SuccessFactorsRecruiting - 91cd9972-c05d-4d29-8b6e-dbef2a2d48e9 correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.s4:communicationScenario:SAP_COM_0008 title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - Integration Dependency to realize Customer Order data product shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - >- SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing. description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - | SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing, acts as a digital core, connecting your enterprise with people, business networks, the Internet of Things, Big Data, and more. partOfPackage: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/Package/ordId' maxLength: 255 description: |- Defines which Package the resource is part of. MUST be a valid reference to a [Package](#package) ORD ID. Every resource MUST be part of one package. examples: - sap.xref:package:SomePackage:v1 partOfGroups: type: array items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ x-association-target: - '#/definitions/Group/groupId' description: >- Defines which groups the resource is assigned to. 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. version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility states who is allowed to "see" the described resource or capability. oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: string description: >- The `releaseStatus` specifies the stability of the resource and its external contract. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active sunsetDate: type: string format: date-time description: >- The sunset date defines when the resource is scheduled to be decommissioned / removed / archived. 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](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2022-01-08T15:47:04+00:00' successors: type: array description: >- The successor resource(s). 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`. items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 x-association-target: - '#/definitions/IntegrationDependency/ordId' examples: - - sap.foo.bar:integrationDependency:CustomerOrder:v2 mandatory: type: boolean description: >- If true, the Integration Dependency is mandatory for the described system to function. aspects: type: array description: |- List of integration aspects that make up the Integration Dependency. Each aspect listed is a dedicated, constituent part (AND condition). items: $ref: '#/definitions/IntegrationAspect' relatedIntegrationDependencies: type: array description: >- If an Integration Dependency conceptually belongs or related to another Integration Dependency, this can be indicated here. One situation would be where two systems each have an Integration Dependency to describe a two-sided integration from each side. items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/IntegrationDependency/ordId' examples: - - sap.foo.bar:integrationDependency:SomethingRelated:v1 links: type: array description: Generic Links with arbitrary meaning and content. items: $ref: '#/definitions/Link' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' additionalProperties: false required: - ordId - title - version - releaseStatus - visibility - partOfPackage - mandatory IntegrationAspect: type: object title: Aspect x-introduced-in-version: 1.7.0 description: >- 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. properties: title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - Integration Aspect to get Customer Order data description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - | SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing, acts as a digital core, connecting your enterprise with people, business networks, the Internet of Things, Big Data, and more. mandatory: type: boolean description: >- If true, the aspect is mandatory to realize the Integration Dependency it contains. supportMultipleProviders: type: boolean description: >- If true, the references resources can be provided by multiple system instances. If not, only one integration target is supported. apiResources: type: array description: List of API Resource Dependencies. items: $ref: '#/definitions/ApiResourceIntegrationAspect' eventResources: type: array description: List of Event Resource Dependencies. items: $ref: '#/definitions/EventResourceIntegrationAspect' additionalProperties: false required: - title - mandatory ApiResourceIntegrationAspect: type: object title: Api Resource Integration Aspect x-introduced-in-version: 1.7.0 description: API resource related integration aspect properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.s4:apiResource:API_BILL_OF_MATERIAL_SRV:v1 minVersion: type: string description: > Minimum version of the references resource that the integration requires. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 additionalProperties: false required: - ordId EventResourceIntegrationAspect: type: object title: Event Resource Integration Aspect x-introduced-in-version: 1.7.0 description: Event resource related integration aspect properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.billing.sb:eventResource:BusinessEvents_SubscriptionEvents:v1 minVersion: type: string description: > Minimum version of the references resource that the integration requires. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 subset: type: array description: >- List of individual events or messages that are sufficient to achieve the aspect. items: $ref: '#/definitions/EventResourceIntegrationAspectSubset' systemTypeRestriction: type: array description: >- In case that the event subscriptions are limited to known [system types](../index.md#def-system-type), they can be listed here as [system namespaces](../index.md#system-namespace). 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. items: type: string description: | Valid [system namespace](../index.md#system-namespace). pattern: ^[a-z0-9]+(?:[.][a-z0-9]+){1}$ minItems: 1 examples: - - sap.s4 additionalProperties: false required: - ordId EventResourceIntegrationAspectSubset: type: object title: Event Resource Integration Aspect Subset x-introduced-in-version: 1.7.0 description: >- 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. properties: eventType: type: string description: >- 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](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#type) can be used. examples: - sap.cic.Order.OrderTransferred.v1 additionalProperties: false required: - eventType Vendor: type: object title: Vendor description: >- 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](../index.md#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:`. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: ^([a-z0-9]+):(vendor):([a-zA-Z0-9._\-]+):()$ maxLength: 255 examples: - 'sap:vendor:SAP:' - 'customer:vendor:Customer:' - 'microsoft:vendor:Microsoft:' title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: - SAP partners: type: array description: >- Optional list of partner vendors, referenced through their ORD ID. MUST be a valid reference to a [Vendor](#vendor) ORD ID. This property can be used to indicate partnership relations between vendors. items: type: string pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ x-association-target: - '#/definitions/Vendor/ordId' examples: - - 'microsoft:vendor:Microsoft:' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' additionalProperties: false required: - ordId - title ChangelogEntry: type: object title: Changelog Entry description: |- A changelog entry can be used to indicate changes. Usually they lead to a change of the version number or the release status. properties: version: type: string minLength: 1 description: >- Full version number that corresponds to the `version` that is described by the changelog entry. Ideally it follows the [Semantic Versioning 2.0.0](https://semver.org/) standard, but since it should reflect the actual version string / scheme used, this is not a mandatory requirement. examples: - 1.2.3 releaseStatus: type: string description: >- The `releaseStatus` specifies the stability of the resource and its external contract. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active date: type: string format: date description: >- Date of change, without time or timezone information. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2020-04-29' description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - |- ## Changelog ... url: type: string format: uri description: >- Optional [URL](https://tools.ietf.org/html/rfc3986) that links to a more detailed changelog entry. The link target MUST be absolute and SHOULD be openly accessible. additionalProperties: false required: - version - releaseStatus - date Link: type: object title: Link description: > Link that can be attached to packages or Open Resource Discovery resources. properties: title: type: string minLength: 1 description: |- Human readable title of the link. MUST be unique within the collection of links provided. examples: - APIs for SAP S/4HANA url: type: string format: uri description: |- [URL](https://tools.ietf.org/html/rfc3986) of the link. The link target MUST be absolute and SHOULD be openly accessible. examples: - >- https://blogs.sap.com/2018/04/11/testing-of-s4hana-inventory-management-odata-apis-via-sap-api-hub/ description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown) examples: - > This gives you an overview on where to find which kind of APIs in SAP S/4HANA. required: - title - url examples: - url: >- https://blogs.sap.com/2018/04/11/testing-of-s4hana-inventory-management-odata-apis-via-sap-api-hub/ title: APIs for SAP S/4HANA description: >- This gives you an overview on where to find which kind of APIs in SAP S/4HANA. PackageLink: type: object title: Package Link description: >- Links with specific semantic meaning that are related to `Package`. If a generic [Link](#link) can also be expressed via a Package Link, the latter MUST be chosen. properties: type: type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: terms-of-service description: Link to human-readable terms of service / use documentation. - const: license description: Link to human-readable license documentation - const: client-registration description: Links to a resource where a client may register to use the package - const: payment description: Links to a resource detailing pricing details of the package - const: sandbox description: Links to a sandbox environment - const: service-level-agreement description: >- Links to a resource detailing the Service Level Agreement relating to the package. This may be machine- or human-readable. - const: support description: >- Links to a resource where a client may obtain support for the package - const: custom description: If chosen, `customType` MUST be provided. examples: - terms-of-service customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:custom-definition-format:v1 url: type: string format: uri description: |- [URL](https://tools.ietf.org/html/rfc3986) to the PackageLink. The link target MUST be absolute and SHOULD be openly accessible. examples: - >- https://accounts.sap.com/ui/public/showRegisterForm?spName=https://netweaver.ondemand.com&targetUrl=https://cloudintegration.hana.ondemand.com required: - type - url examples: - type: terms-of-service url: https://www.sap.com/corporate/en/legal/terms-of-use.html APIEventResourceLink: type: object title: Api and Event Resource Link description: >- Links with specific semantic meaning that are related to API or event resources. If a generic [Link](#link) can also be expressed via an API / Event Resource Link, the latter MUST be chosen. properties: type: type: string description: >- See also: [WADG0001 WebAPI type extension](https://webapi-discovery.github.io/rfcs/rfc0001.html#webapiactions) anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: api-documentation description: >- Link to human-readable documentation describing the API or event resource in more detail. - const: authentication description: >- Links to a resource detailing authentication requirements. Note that this is a human-readable resource, not an authentication endpoint. - const: client-registration description: >- Links to a resource where a client may register to use the API or event resource. - const: console description: >- Links to an interactive console where API calls or events may be tested. - const: payment description: >- Links to a resource detailing pricing details of the API or event resource. - const: service-level-agreement description: >- Links to a resource detailing the Service Level Agreement relating to the API or event resource. This may be machine- or human-readable. - const: support description: >- Links to a resource where a client may obtain support for the API or event resource. - const: custom description: If chosen, `customType` MUST be provided. examples: - console customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:custom-definition-format:v1 url: type: string format: uri-reference description: >- [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the API or Event Resource Link. The link target SHOULD be absolute and SHOULD be openly accessible. If a relative link is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl). examples: - https://example.com/some/absolute/url - /some/relative/url additionalProperties: false required: - url - type examples: - type: api-documentation url: https://api.sap.com/api/API_OPLACCTGDOCITEMCUBE_SRV/resource DataProductLink: type: object title: Data Product Link description: >- Links with specific semantic meaning that are related to Data Product resources. If a generic [Link](#link) can also be expressed via Data Product Link, the latter MUST be chosen. properties: type: type: string anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: Any valid [Specification ID](../index.md#specification-id). - const: payment description: Links to a resource detailing pricing details of the data product. - const: terms-of-use description: >- Set of legal guidelines or contractual agreement that outline how a user can access, utilize, and share data provided through a specific data product, essentially defining the permitted and prohibited actions when interacting with, processing or storing data, often including details about privacy, security, and potential limitations on data usage depending on the specific data product and its intended purposes. - const: service-level-agreement description: >- Links to a resource detailing the Service Level Agreement relating to the data product. This may be machine- or human-readable. - const: support description: >- Links to a resource where a client may obtain support for the data product. - const: custom description: If chosen, `customType` MUST be provided. examples: - support customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap:custom-definition-format:v1 url: type: string format: uri-reference description: >- [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the Data Product Link. The link target SHOULD be absolute and SHOULD be openly accessible. If a relative link is given, it is relative to the [`describedSystemInstance.baseUrl`](#system-instance_baseurl). examples: - https://example.com/some/absolute/url additionalProperties: false required: - url - type examples: - type: support url: https://support.sap.com/CIC_DP_RT/issue/ SystemInstance: type: object title: System Instance description: >- A [system instance](../index.md#def-system-instance) is a concrete, running instance of a system type. In a multi-tenant system, it corresponds to a tenant. In a single-tenant system, it corresponds to the [system installation](../index.md#def-system-deployment) itself. properties: baseUrl: type: string format: uri-reference description: >- Optional [base URL](../index.md#def-base-url) of the **system instance**. By providing the base URL, relative URLs in the document are resolved relative to it. The `baseUrl` MUST not contain a leading slash. MUST be provided if the base URL is not known to the ORD aggregators. MUST be provided when the document needs to be fully self contained, e.g. when used for manual imports. pattern: ^http[s]?:\/\/[^:\/\s]+\.[^:\/\s\.]+(:\d+)?(\/[a-zA-Z0-9-\._~]+)*$ examples: - https://example-sap-system.com - https://sub.foo.bar.com - https://sub.foo.bar.com/api/v1 localId: type: string x-introduced-in-version: 1.2.1 description: >- Optional local ID for the system instance, as known by the described system. In case of multi-tenant systems, it is equivalent to the local tenant id. maxLength: 255 examples: - LocalTenantId123 correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.cld:tenant:741234567 labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability additionalProperties: false SystemType: type: object title: System Type description: >- A [system type](../index.md#def-system-type) is the abstract type of an application or service, from operational perspective. properties: systemNamespace: type: string description: >- The [system namespace](../index.md#system-namespace) is a unique identifier for the system type. It is used to reference the system type in the ORD. pattern: ^[a-z0-9]+(?:[.][a-z0-9]+){1}$ maxLength: 32 examples: - sap.s4 - sap.c4c - sap.cld correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - - sap.cld:systemRole:S4_PC labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability additionalProperties: false SystemVersion: type: object title: System Version description: >- A [system version](../index.md#def-system-version) states the design-time version / release of a [system instance](../index.md#def-system-instance). It provides versioning for operational purposes for the [system type](../index.md#def-system-type). properties: version: type: string description: >- The version of the system instance (run-time) or the version of the described system-version perspective. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. MUST be provided if the ORD document is `perspective`: `system-version`. For continuous-delivery systems, the version MAY be fixed to the same value, e.g. `1.0.0`, but be aware that phased rollouts may benefit from a more precise versioning like adding a build number. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 2024.8.0 title: type: string description: Human-readable title of the system version. minLength: 1 maxLength: 255 examples: - SAP S/4HANA Cloud 2408 correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: [] labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability additionalProperties: false AccessStrategy: type: object title: Metadata Definition Access Strategy description: >- Defines the [access strategy](../../spec-extensions/access-strategies/) for accessing the resource definitions. properties: type: type: string description: >- Defines the authentication/authorization strategy through which the referenced `resourceDefinitions` are accessible. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: |- Any valid [Specification ID](../index.md#specification-id). If chosen, `customDescription` SHOULD be provided. - const: open description: >- The resource definitions are openly accessible and not protected via authentication or authorization. Please find a more detailed documentation [here](../../spec-extensions/access-strategies/open). - const: basic-auth description: >- The resource definitions are protected via generic basic auth. Please find a more detailed documentation [here](../../spec-extensions/access-strategies/basic-auth). x-introduced-in-version: 1.12.1 - const: custom description: |- If chosen, `customType` MUST be provided. If chosen, `customDescription` SHOULD be provided. examples: - open customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.xref:open-local-tenant-id:v1 customDescription: type: string minLength: 1 description: >- Human-readable description about how the access is set up, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). MUST only be provided if `type` is set to `custom`. examples: - >- To set up the access to OData APIs, please refer to the [SAP Cloud for Customer OData API](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US) help pages." additionalProperties: false required: - type examples: - type: open - type: custom customType: sap.xref:open-local-tenant-id:v1 customDescription: Custom description how to use custom access strategy CredentialExchangeStrategy: type: object title: Credential Exchange Strategy x-feature-status: alpha description: >- 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. properties: type: type: string description: The type of credential exchange strategy. anyOf: - type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ description: |- Any valid [Specification ID](../index.md#specification-id). If chosen, `customDescription` SHOULD be provided. - const: custom description: |- If chosen, `customType` MUST be provided. If chosen, `customDescription` SHOULD be provided. customType: type: string description: >- If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided. MUST be a valid [Specification ID](../index.md#specification-id). MUST only be provided if `type` is set to `custom`. pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.xref:credential-exchange:v1 customDescription: type: string minLength: 1 description: >- Human-readable description about how the credential exchange is achieved, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). MUST only be provided if `type` is set to `custom`. examples: [] callbackUrl: type: string format: uri description: >- [URL reference](https://tools.ietf.org/html/rfc3986#section-4.1) (URL or relative reference) to the credential exchange callback endpoint. 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. examples: - https://system-instance-1.com/credentials?scenario=SAP_COM_008 additionalProperties: false required: - type Labels: title: Labels type: object description: >- 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. patternProperties: ^[a-zA-Z0-9-_.]*$: type: array items: type: string minLength: 1 examples: - label-key-1: - label-value-1 - label-value-2 GroupType: title: Group Type type: object description: >- A Group Type defines the semantics of [group assignments](#group). 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](../concepts/grouping-and-bundling#Groups). x-introduced-in-version: 1.9.0 properties: groupTypeId: type: string pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ description: >- GroupType ID, which MUST be a valid [Concept ID](../../spec-v1/#concept-id). examples: - sap.foo:domain - sap.cap:service title: type: string description: Human readable title of the group type. minLength: 1 maxLength: 255 examples: - SAP S/4HANA Cloud description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - | SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing, acts as a digital core, connecting your enterprise with people, business networks, the Internet of Things, Big Data, and more. required: - groupTypeId - title examples: - groupTypeId: sap.cds:service title: CAP Service description: >- Description of the CDS Service concept and how its correctly used for grouping... Group: title: Group type: object description: >- 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](../concepts/grouping-and-bundling#Groups). x-introduced-in-version: 1.9.0 properties: groupId: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ description: >- The Group ID consists of two [Concept IDs](../../spec-v1/#concept-id) separated by a `:`. The first two fragments MUST be equal to the used Group Type ID (`groupTypeId`). The last two fragments MUST be a valid [Concept ID](../../spec-v1/#concept-id), indicating the group instance assignment. The ID concept is a bit unusual, but it ensures globally unique and conflict free group assignments. examples: - sap.foo:domain:sap.foo:DomainName groupTypeId: type: string pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ description: |- Group Type ID. MUST match with the first two fragments of the own `groupId`. examples: - sap.foo:domain - sap.cap:service x-association-target: - '#/definitions/GroupType/groupTypeId' title: type: string description: Human readable title of the group assignment (for UI). minLength: 1 maxLength: 255 examples: - SAP S/4HANA Cloud description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: - | SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing, acts as a digital core, connecting your enterprise with people, business networks, the Internet of Things, Big Data, and more. required: - groupId - groupTypeId - title examples: - groupId: sap.cap:service:customer.incidents:incidents.IncidentsService groupTypeId: sap.cap:service title: Incidents Service DocumentationLabels: title: Documentation Labels type: object description: >- Generic documentation labels that can be applied to most ORD information. They are defined as an object that may have arbitrary keys. The value of a key is an array of [CommonMark](https://spec.commonmark.org/) (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](https://spec.commonmark.org/) (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. x-introduced-in-version: 1.1.0 patternProperties: ^.*$: type: array items: type: string minLength: 1 examples: - Scope Items: - >- [Basic Bank Account Management (BFA)](https://rapid.sap.com/bp/#/scopeitems/BFA \" Link To BP \") Extensible: title: Extensible type: object description: >- Contains information about the extensibility of this resource. If applicable, a description and further resources about extending this resource are provided. properties: supported: type: string enum: - 'no' - manual - automatic description: >- This property defines whether the resource is extensible. **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. description: type: string minLength: 1 description: >- A description about the extensibility capabilities of this API, notated in [CommonMark](https://spec.commonmark.org/) (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`. examples: - Please find the extensibility documentation [here](#here) additionalProperties: false required: - supported examples: - supported: manual description: "API can be extended by custom fields on the following business contexts (field usage for this API needs to be selected):\r\n* Procurement: Purchasing Document (MM_PURDOC_HEADER)\r\n* Procurement: Purchasing Document Item (MM_PURDOC_ITEM)\r\n\r\n[How to add an extension field to an API](https://help.sap.com/viewer/9a281eac983f4f688d0deedc96b3c61c/latest/en-US/57909455bf7c4fdd8bcf48d76c1eae33.html)" EntityTypeMapping: title: Entity Type Mapping type: object x-introduced-in-version: 1.6.0 description: >- 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](../../#/v1/README?id=correlation-id) or to an [ORD ID](../../spec-v1/#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 navigate-able for customers. properties: apiModelSelectors: type: array description: >- 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. items: anyOf: - $ref: '#/definitions/ApiModelSelectorOData' - $ref: '#/definitions/ApiModelSelectorJsonPointer' entityTypeTargets: type: array description: >- 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](../../spec-v1/#ord-id) or a [Correlation ID](../../spec-v1/#correlation-id). items: anyOf: - $ref: '#/definitions/EntityTypeOrdIdTarget' - $ref: '#/definitions/EntityTypeCorrelationIdTarget' minItems: 1 additionalProperties: false required: - entityTypeTargets ApiModelSelectorOData: title: Api Model Selector (Odata) x-introduced-in-version: 1.6.0 type: object description: >- 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`. properties: type: type: string description: The type for OData selectors is fixed to `odata`. enum: - odata entitySetName: type: string description: |- OData entity set name. As defined in the EDMX, e.g. ``. minLength: 1 examples: - AttachmentContent additionalProperties: false required: - type - entitySetName examples: - type: odata entitySetName: AttachmentContent ApiModelSelectorJsonPointer: title: Api Model Selector (Json Pointer) x-introduced-in-version: 1.6.0 type: object description: >- Generic API Model Selector for JSON / YAML based resource definitions. It uses a [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901) 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`. properties: type: type: string description: >- The type for generic JSON Pointer selectors is fixed to `json-pointer`. enum: - json-pointer jsonPointer: type: string description: >- JSON Pointer to the entity type schema / description within the resource definition format. MUST be a valid JSON Pointer according to [RFC6901](https://datatracker.ietf.org/doc/html/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). minLength: 1 examples: - '#/objects/schemas/' - '#/components/schemas/sap.odm.sales.CustomerOrder.Placed.v0' - '#/objects/schemas//table-oriented/' additionalProperties: false required: - type - jsonPointer examples: - type: json-pointer jsonPointer: '#/objects/schemas/AttachmentContent' EntityTypeOrdIdTarget: title: Entity Type Target (Ord Id) x-introduced-in-version: 1.6.0 type: object description: >- Define which entity type is the target of an entity type mapping Entity types can be referenced using a [ORD ID](../../spec-v1/#ord-id) of an entity type. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.odm:entityType:BusinessPartner:v1 x-association-target: - '#/definitions/EntityType/ordId' required: - ordId additionalProperties: false EntityTypeCorrelationIdTarget: title: Entity Type Target (Correlation Id) type: object description: >- Define which entity type is the target of an entity type mapping Entity types can be referenced using a [Correlation ID](../../spec-v1/#correlation-id). x-introduced-in-version: 1.6.0 properties: correlationId: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: - sap.csnexposure:entity:Attachment required: - correlationId additionalProperties: false RelatedEntityType: title: Related Entity Type x-introduced-in-version: 1.9.0 type: object description: Defines the relation between Entity Types (via its ORD ID). properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.odm:entityType:BusinessPartner:v1 x-association-target: - '#/definitions/EntityType/ordId' relationType: type: string description: >- Optional type of the relationship, which defines a stricter semantic what the relationship implies. If not provided, the relationship type has no semantics, it's "related somehow". x-introduced-in-version: 1.12.0 x-feature-status: beta oneOf: - const: part-of description: >- The described entity type is a composite part of the referenced entity type. E.g. a `SalesOrderItem` is part of a `SalesOrder`. - const: can-share-identity description: >- The related entity types can potentially share the same identity in their instance data / be ID mapped. E.g. a `BusinessPartner` can share the same identity as a `NaturalPerson`. examples: - can-share-identity required: - ordId additionalProperties: false ExposedEntityType: title: Exposed Entity Type type: object description: Defines which Entity Type is exposed through (via its ORD ID). x-introduced-in-version: 1.11.0 properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ maxLength: 255 examples: - sap.s4.sot:entityType:BusinessPartner:v1 x-association-target: - '#/definitions/EntityType/ordId' required: - ordId additionalProperties: false Tombstone: type: object title: Tombstone description: >- A tombstone indicates that a previously published ORD resource or taxonomy has been removed / decommissioned / archived. 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. The tombstone MUST be kept sufficiently long (at least 31 days) so that all ORD aggregators can learn about the tombstone. properties: ordId: type: string description: >- [ORD ID](../index.md#ord-id) of the ORD resource/taxonomy that has been removed. pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package|consumptionBundle|product|vendor|apiResource|eventResource|capability|entityType|integrationDependency|dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*|)?$ maxLength: 255 examples: - sap.xref:package:SomePackage:v1 x-association-target: - '#/definitions/Package/ordId' - '#/definitions/ConsumptionBundle/ordId' - '#/definitions/Product/ordId' - '#/definitions/Vendor/ordId' - '#/definitions/ApiResource/ordId' - '#/definitions/EventResource/ordId' - '#/definitions/Capability/ordId' - '#/definitions/EntityType/ordId' - '#/definitions/IntegrationDependency/ordId' - '#/definitions/DataProduct/ordId' groupId: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ description: Group ID of the group that has been removed. examples: - sap.foo:domain:sap.foo:DomainName x-association-target: - '#/definitions/Group/groupId' groupTypeId: type: string pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ description: Group Type ID of the group type that has been removed. examples: - sap.foo:domain - sap.cap:service x-association-target: - '#/definitions/GroupType/groupTypeId' removalDate: type: string format: date-time description: >- The date when the ORD resource/taxonomy was removed. 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](https://tools.ietf.org/html/rfc3339#section-5.6). examples: - '2020-12-02T14:12:59Z' description: type: string minLength: 1 description: >- Optional description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description of a Tombstone MAY be added to the changelog of the removed resource by an ORD aggregator. examples: - | SAP S/4HANA Cloud, our next generation cloud ERP suite designed for in-memory computing, acts as a digital core, connecting your enterprise with people, business networks, the Internet of Things, Big Data, and more. required: - removalDate examples: - ordId: sap.s4:apiResource:API_RFQ_PROCESS_SRV:v2 removalDate: '2020-12-02T14:12:59Z' - groupId: sap.foo:domain:sap.foo:DomainName removalDate: '2020-12-02T14:12:59Z' OrdResource: type: object title: Ord Resource (abstract) description: Abstract definition of shared properties across ORD Resources. properties: ordId: type: string description: >- The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid [ORD ID](../index.md#ord-id) of the appropriate ORD type. pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(apiResource|eventResource|capability|dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*|)$ maxLength: 255 examples: [] localId: type: string x-introduced-in-version: 1.2.1 description: >- The locally unique ID under which this resource can be looked up / resolved in the described system itself. Unlike the ORD ID it's not globally unique, but it may be useful to document the original ID / technical name. It MAY also be used as the `` fragment in the ORD ID, IF it can fulfill the charset and length limitations within the ORD ID. But since this is not always possible, no assumptions MUST be made about the local ID being the same as the `` fragment in the ORD ID. maxLength: 255 examples: [] correlationIds: type: array description: >- Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). 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](../index.md#correlation-id). items: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ maxLength: 255 examples: [] title: type: string description: |- Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: [] shortDescription: type: string description: |- Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. minLength: 1 maxLength: 255 examples: [] description: type: string minLength: 1 description: >- Full description, notated in [CommonMark](https://spec.commonmark.org/) (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. examples: [] partOfPackage: type: string pattern: >- ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ x-association-target: - '#/definitions/Package/ordId' maxLength: 255 description: |- Defines which Package the resource is part of. MUST be a valid reference to a [Package](#package) ORD ID. Every resource MUST be part of one package. examples: [] partOfGroups: type: array items: type: string pattern: >- ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ x-association-target: - '#/definitions/Group/groupId' description: >- Defines which groups the resource is assigned to. 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. examples: [] version: type: string description: >- The complete [SemVer](https://semver.org/) version string. It MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the `version` major version changes, the [ORD ID](../index.md#ord-id) `` fragment MUST be updated to be identical. In case that a resource definition file also contains a version number (e.g. [OpenAPI `info`.`version`](https://spec.openapis.org/oas/v3.1.1.html#info-object)), it MUST be equal with the resource `version` to avoid inconsistencies. If the resource has been extended by the user, the change MUST be indicated via `lastUpdate`. The `version` MUST not be bumped for changes in extensions. The general [Version and Lifecycle](../index.md#version-and-lifecycle) flow MUST be followed. 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. pattern: >- ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ examples: - 1.2.3 - 1.0.0-alpha.1 lastUpdate: type: string format: date-time x-introduced-in-version: 1.4.0 description: >- Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). When retrieved from an ORD aggregator, `lastUpdate` will be reliable there and reflect either the provider based update time or the aggregator processing time. Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the `version` or `lastUpdate` property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again. Together with `perspectives`, this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators. examples: - '2022-12-19T15:47:04+00:00' visibility: type: string description: >- The visibility states who is allowed to "see" the described resource or capability. oneOf: - const: public description: >- Resources are publicly visible to customers and 3rd parties. Usually this includes an contract on the API stability, e.g. the [SAP API Deprecation Policy](https://help.sap.com/viewer/84b35b9c39b247e3ba2a31f02beee46d/Cloud/en-US/5cbfda5a9efe4e97a3e24ddaf7ec5c16.html). - const: internal description: >- Resources are visible to other applications within the same [vendor](#vendor). 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. - const: private description: >- Resources that are exclusive 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: type: string description: >- The `releaseStatus` specifies the stability of the resource and its external contract. oneOf: - const: beta description: >- The contract for the resource is beta and may not be meant for productive use. Resources of `beta` status MAY be changed or deleted at the providers discretion. - const: active description: >- Resource is meant for productive use and provides a stable API contract. - const: deprecated description: >- Resource has been deprecated. If the `releaseStatus` is set to `deprecated`, the `deprecationDate` SHOULD be provided. If successor resources exist, they MUST be referenced through `successors`. A deprecated resource MAY be sunset (aka. decommissioned / removed) in the future, through setting a `Tombstone`. Once the resource is sunset, its description MAY be removed from ORD, but could also be kept with `releaseStatus` set to `sunset`. - const: sunset description: >- Resource has been sunset, but is still described. If the status is set to `sunset`, a `Tombstone` MUST be set as well and a `sunsetDate` MUST be provided. examples: - active links: type: array description: |- Generic links with arbitrary meaning and content. `packageLinks` MUST be preferred if applicable. items: $ref: '#/definitions/Link' tags: type: array items: type: string pattern: ^[a-zA-Z0-9-_.\/ ]*$ minLength: 1 description: >- List of free text style tags. No special characters are allowed except `-`, `_`, `.`, `/` and ` `. Tags that are assigned to a `Package` are inherited to all of the ORD resources it contains. examples: - - storage - high-availability labels: $ref: '#/definitions/Labels' documentationLabels: $ref: '#/definitions/DocumentationLabels' required: - ordId - title - description - version - visibility - releaseStatus - partOfPackage additionalProperties: true