ORD Document
How to read this documentation
- The root schema of the document is ORD Document
Technical information
- Example files can be found here.
- Visual diagrams can be found here: ORD Document Class Diagram.
- The interface is described as JSON Schema here: /spec-v1/interfaces/Document.schema.json.
- A high-level overview can also be exported as Excel and CSV file.
- This documentation is automatically generated from ./spec/v1/Document.schema.yaml.
Schema Definitions
ORD Document
The ORD Document object serves as a wrapper for the ORD resources and ORD taxonomy and adds further top-level information that are specific to the document/the service it describes.
The constraints and considerations on ORD Documents MUST be followed.
Property | Type | Description |
---|---|---|
string | Optional URL to the Open Resource Discovery document schema (defined as a JSON Schema). If provided, this enables code intelligence and validation in supported editors (like VSCode) and tools. JSON Schema Format: uri-reference Recommended Values:
| |
string | Version of the Open Resource Discovery specification that is used to describe this document. Allowed Values:
Example Values:
| |
string | Optional description of the ORD document itself. Please note that this information is NOT further processed or considered by an ORD aggregator. Notated in CommonMark (Markdown). Minimum Length: 1 Example Values:
| |
Information on the system instance that this ORD document describes. This information is optional, but RECOMMENDED to add, as it makes the ORD document self contained. | ||
string | The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values:
Introduced in Version: 1.3.0 Example Values:
| |
string | If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided.The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom .MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<API Resource> | Array of all API Resources that are described in this ORD document. | |
Array<Event Resource> | Array of all event resources that are described in this ORD document. | |
Array<Entity Type> | Array of all entity types that are described in this ORD document. Introduced in Version: 1.6.0 | |
Array<Capability> | Array of all capabilities that are described in this ORD document. Introduced in Version: 1.4.0 | |
Array<Data Product> | Array of all data products that are described in this ORD document. Introduced in Version: 1.8.0 | |
Array<Integration Dependency> | Array of all integration dependencies that are described in this ORD document. Introduced in Version: 1.7.0 | |
Array<Vendor> | Array of all Vendors that are described in this ORD document. | |
Array<Product> | Array of all Products that are described in this ORD document. | |
Array<Package> | Array of all Packages that are described in this ORD document. | |
Array<Consumption Bundle> | Array of all Consumption Bundles that are described in this ORD document. | |
Array<Group> | Array of all Groups that are described in this ORD document. | |
Array<Group Type> | Array of all Group Types that are described in this ORD document. | |
Array<Tombstone> | List of ORD information (resources or taxonomy) that have been "tombstoned"/removed. This MUST be indicated explicitly, so that ORD aggregators and consumers can learn about the removal. A tombstone entry MAY be removed after a grace period of 31 days. |
API Resource
The API Resource provides a high-level description of an exposed API. You can find more information, such as the API resource definitions, in the links in the table below.
An API Resource bundles multiple endpoints and resources together. They share the same API namespace and lifecycle (API major version). However, the exact granularity of this is up to the implementer of the API. As a consequence, an API resource MUST NOT bundle together endpoints from different API versions or namespaces.
A common practice is to bundle endpoints that are based on the same domain or Business Object.
Please note that APIs can be described, but still be disabled
.
If the API is not created or owned by the user of the system or by third parties (like partners), it MUST be assigned to dedicated Packages that state this the ownership via the vendor
property.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead.All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ | |
Array<Consumption Bundle Reference> | List of references to the consumption bundles in this resource belongs to. MUST be a valid reference to a Consumption Bundle ORD ID. An API resource SHOULD be associated to one or multiple consumption bundles, if it is of direction inbound or mixed .Some ORD consumer use cases MAY depend on an association to a consumption bundle. If none is given, the resource may not appear as it's unknown how it can be consumed. If a resource has no direct incoming consumption characteristics: - MUST NOT assign consumption bundle to API or Event resources with direction : outbound (no inbound consumption)- MUST NOT assign consumption bundle if resource is not accessible directly, but only via intermediaries like event brokers or gateways. - In this case the intermediary SHOULD describe the consumption bundle instead (potentially also re-describing the resources as well). Example Values:
| |
string | References the default consumption bundle to use for this resource. MUST be a valid reference to a Consumption Bundle ORD ID. Can be used by clients to make a deterministic and preferred choice when multiple options are available. The value MUST be an existing option in the corresponding partOfConsumptionBundles array.Association Target: Consumption Bundle.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values:
| |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
string | Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time.Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.Together with systemInstanceAware , this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values:
| |
string | The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values:
| |
string | The releaseStatus specifies the stability of the resource and its external contract.Allowed Values:
Example Values:
| |
boolean | Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. This can happen either because it has not been setup for use or disabled by an admin / user. If the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance aware perspective. This property can only reflect the knowledge of the described system instance itself. Outside factors for availability can't need to be considered (e.g. network connectivity, middlewares). A disabled resource MAY skip describing its resource definitions. | |
string | The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed.If the releaseStatus is set to deprecated , the deprecationDate SHOULD be provided.The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
string | The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated , the sunsetDate SHOULD be provided (if already known).Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
Array<string> | The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated , successors MUST be provided if one exists.If successors is given, the described resource SHOULD set its releaseStatus to deprecated .Array Item Association Target: API Resource.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
Array<Changelog Entry> | Contains changelog entries that summarize changes with special regards to version and releaseStatus | |
Array<string> | List of URL reference (URL or relative reference) to the target host. If the API resource can be accessed through an entry point, it MUST be described here. The list of entry points MUST not include duplicates. If multiple entry points are provided they MUST be arbitrarily exchangeable without effects. This means that the URLs are just an alias to each other and the resourceDefinitions apply to all entry points equally.In case of multiple entry points it is RECOMMENDED to provide a defaultEntryPoint through partOfConsumptionBundles .The entry point URLs SHOULD match with the target host(s) in the resource definition files (e.g. OpenAPI servers ).If there is no match, the information in ORD takes precedence. Provider View: If the URL is relative to the system that describes the ORD information, it is RECOMMENDED to use relative references and (if known) to provide the describedSystemInstance .baseUrl .If the URL is not relative to the described system instance base URL, a full URL MUST be provided. Consumer View: When fetching the information from an ORD Aggregator, the consumer MAY rely on receiving full URLs. Array Item Format: uri-reference Example Values:
| |
string | Direction of the API Resource consumption. If not provided, "inbound" is assumed. In case of SOAP APIs, the direction is already indicated through the apiProtocol , making this property redundant and optional. But if it is provided, it MUST not be in contradiction with the apiProtocol direction.Default Value: "inbound" Allowed Values:
| |
string | API Protocol including the protocol version if applicable Allowed Values:
Example Values:
| |
Array<API Resource Definition> | List of available machine-readable definitions, which describe the resource or capability in detail. Each definition is to be understood as an alternative description format, describing the same resource / capability. As a consequence the same definition type MUST NOT be provided more than once. It is RECOMMENDED to provide the definitions as they enable machine-readable use cases. If the definitions are added or changed, the version MUST be incremented.An ORD aggregator MAY only (re)fetch the definitions again when the version was incremented. | |
string | Declares this API to be a valid implementation of an externally standardized API contract, sub-protocol or protocol variant. All APIs that share the same implementation standard MAY be treated the same or similar by a consumer client. Allowed Values:
Example Values:
| |
string | If the fixed implementationStandard values need to be extended, an arbitrary customImplementationStandard can be provided.MUST be a valid Specification ID. MUST only be provided if implementationStandard is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | Full description of the custom implementation standard, notated in CommonMark (Markdown). MUST only be provided if implementationStandard is set to custom .SHOULD contain documentation and links that describe the used standard. Example Values:
| |
string | Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Introduced in Version: 1.8.0 Example Values:
| |
Array<string> | List of use cases (types) how the resource is meant to be used for. This helps consumers better to understand which use cases had been in mind by the provider and are therefore explicitly supported. This is obviously described from a provider perspective, but stating what consumer use cases it potentially supports. As it's not possible to create a list of options that are mutually exclusive, all options that apply should be provided. If no array is defined, it is assumed that this information is not provided. Array Item Allowed Values:
Introduced in Version: 1.8.0 Example Values:
| |
string | Usage Define from where the API resource can be used and accessed Default Value: "external" Allowed Values:
Introduced in Version: 1.8.0 | |
Array<Entity Type Mapping> | Describes mappings between the API Models of the described resource to the underlying, conceptual entity types. Introduced in Version: 1.6.0 | |
Array<API and Event Resource Link> | Links with semantic meaning that are specific to API Resources. | |
Array<Link> | Generic Links with arbitrary meaning and content. If applicable, apiResourceLinks MUST be used instead of generic links . | |
Describes extensibility (by customers or partners) of this resource. Extensibility usually happens at run-time by the end-users. Extensions can be field or entity extensions that come on top of the baseline contract. Changes in extensions do not lead to an increase in the version , but MUST lead to an updated lastUpdate date.Since the extensions are managed by the customer or a partner, whether those changes are compatible or not is not guaranteed by the base contract of the resource. | ||
Array<string> | List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to IES ISO-3166 ALPHA-2. countries that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[A-Z]2$ Example Values:
| |
Array<string> | List of line of business tags. No special characters are allowed except - , _ , . , / and .lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
Array<string> | List of industry tags. No special characters are allowed except - , _ , . , / and .industry that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. | ||
string | The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values:
Introduced in Version: 1.3.0 Example Values:
| |
string | If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided.The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom .MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
boolean | Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true.An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values:
|
Event Resource
The event resource provides a high-level description of a collection of related Events. More detailed information, such as the event resource definitions, are provided in links in the table below.
Which events are considered "related" is up to the implementer. A common practice is to bundle events that are based on the same resource/Business Object. It is also an option to bundle all available events into a single event resource/event catalog.
Please note that event resources can be described, but still be disabled
.
If the event resource is not created or owned by the user / customer of the system or by partners / third parties, it MUST be assigned to dedicated Packages that state this the ownership via the vendor
property.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead.All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ | |
Array<Consumption Bundle Reference> | List of references to the consumption bundles in this resource belongs to. MUST be a valid reference to a Consumption Bundle ORD ID. An API resource SHOULD be associated to one or multiple consumption bundles, if it is of direction inbound or mixed .Some ORD consumer use cases MAY depend on an association to a consumption bundle. If none is given, the resource may not appear as it's unknown how it can be consumed. If a resource has no direct incoming consumption characteristics: - MUST NOT assign consumption bundle to API or Event resources with direction : outbound (no inbound consumption)- MUST NOT assign consumption bundle if resource is not accessible directly, but only via intermediaries like event brokers or gateways. - In this case the intermediary SHOULD describe the consumption bundle instead (potentially also re-describing the resources as well). Example Values:
| |
string | References the default consumption bundle to use for this resource. MUST be a valid reference to a Consumption Bundle ORD ID. Can be used by clients to make a deterministic and preferred choice when multiple options are available. The value MUST be an existing option in the corresponding partOfConsumptionBundles array.Association Target: Consumption Bundle.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values:
| |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
string | Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time.Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.Together with systemInstanceAware , this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values:
| |
string | The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values:
| |
string | The releaseStatus specifies the stability of the resource and its external contract.Allowed Values:
Example Values:
| |
boolean | Indicates that this resource is currently not available for consumption at runtime, but could be configured to be so. This can happen either because it has not been setup for use or disabled by an admin / user. If the resource is not available in principle for a particular system instance, e.g. due to lack of entitlement, it MUST not be described in the system-instance aware perspective. This property can only reflect the knowledge of the described system instance itself. Outside factors for availability can't need to be considered (e.g. network connectivity, middlewares). A disabled resource MAY skip describing its resource definitions. | |
string | The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed.If the releaseStatus is set to deprecated , the deprecationDate SHOULD be provided.The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
string | The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated , the sunsetDate SHOULD be provided (if already known).Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
Array<string> | The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated , successors MUST be provided if one exists.If successors is given, the described resource SHOULD set its releaseStatus to deprecated .Array Item Association Target: Event Resource.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
Array<Changelog Entry> | Contains changelog entries that summarize changes with special regards to version and releaseStatus | |
Array<Event Resource Definition> | List of available machine-readable definitions, which describe the resource or capability in detail. Each definition is to be understood as an alternative description format, describing the same resource / capability. As a consequence the same definition type MUST NOT be provided more than once. It is RECOMMENDED to provide the definitions as they enable machine-readable use cases. If the definitions are added or changed, the version MUST be incremented.An ORD aggregator MAY only (re)fetch the definitions again when the version was incremented. | |
string | Declares this EventResource to be a valid implementation of a standardized or shared contract. All implementations of the same implementation standard MAY be treated the same by a consumer. However, there MAY be differences in the access strategy, and compatible customizations by the implementer. The implementation standard MAY define the role of the implementor (producer, consumer, both) and how it is determined. As of now, only custom implementation standards are supported. Allowed Values:
Example Values:
| |
string | If the fixed implementationStandard values need to be extended, an arbitrary customImplementationStandard can be provided.MUST be a valid Specification ID. MUST only be provided if implementationStandard is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | Full description of the custom implementation standard, notated in CommonMark (Markdown). MUST only be provided if implementationStandard is set to custom .SHOULD contain documentation and links that describe the used standard. Example Values:
| |
string | Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Introduced in Version: 1.8.0 Example Values:
| |
Array<Entity Type Mapping> | Describes mappings between the API Models of the described resource to the underlying, conceptual entity types. Introduced in Version: 1.6.0 | |
Array<API and Event Resource Link> | Links with semantic meaning that are specific to event resources. If applicable, eventResourceLinks MUST be used instead of generic links .Introduced in Version: 1.7.1 | |
Array<Link> | Generic Links with arbitrary meaning and content. | |
Describes extensibility (by customers or partners) of this resource. Extensibility usually happens at run-time by the end-users. Extensions can be field or entity extensions that come on top of the baseline contract. Changes in extensions do not lead to an increase in the version , but MUST lead to an updated lastUpdate date.Since the extensions are managed by the customer or a partner, whether those changes are compatible or not is not guaranteed by the base contract of the resource. | ||
Array<string> | List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to IES ISO-3166 ALPHA-2. countries that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[A-Z]2$ Example Values:
| |
Array<string> | List of line of business tags. No special characters are allowed except - , _ , . , / and .lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
Array<string> | List of industry tags. No special characters are allowed except - , _ , . , / and .industry that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. | ||
string | The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values:
Introduced in Version: 1.3.0 Example Values:
| |
string | If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided.The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom .MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
boolean | Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true.An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values:
|
Entity Type
An Entity Type describes either a business concept / term or an underlying conceptual model. The same entity type can be exposed through one or multiple API and events resources.
To learn more about the concept, see Entity Type.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead.All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ | |
Array<string> | List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values:
| |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
string | Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time.Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.Together with systemInstanceAware , this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values:
| |
string | The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values:
| |
string | The releaseStatus specifies the stability of the resource and its external contract.Allowed Values:
Example Values:
| |
string | The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed.If the releaseStatus is set to deprecated , the deprecationDate SHOULD be provided.The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
string | The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated , the sunsetDate SHOULD be provided (if already known).Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
Array<string> | The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated , successors MUST be provided if one exists.If successors is given, the described resource SHOULD set its releaseStatus to deprecated .Array Item Association Target: Entity Type.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
Array<Changelog Entry> | Contains changelog entries that summarize changes with special regards to version and releaseStatus | |
string | Defining the abstraction level of the entity type using the DDD terminology. In Domain-Driven Design, there is a concept of entities and aggregates. There are root entities which may contain further sub entities by composition. The complete “package” is then called an aggregate, which gets its name and identity from the root entity. An aggregate is a cluster of domain objects that can be treated as a single unit. The root is the entity that is referenced from outside the aggregate. There must be only one root per aggregate. The root ensures the integrity of the aggregate. A sub entity is any other non-root entity in the aggregate. Source, see Martin Fowler on DDD Aggregate For now, we decided to only cover the aggregate level, which is described in the enum value. Allowed Values:
Example Values:
| |
Array<Related Entity Type> | States that this Entity Type is related to another Entity Type. Usually this happens if there are similar conceptual entity types across different namespaces. Introduced in Version: 1.9.0 | |
Array<Link> | Generic Links with arbitrary meaning and content. | |
Describes extensibility (by customers or partners) of this resource. Extensibility usually happens at run-time by the end-users. Extensions can be field or entity extensions that come on top of the baseline contract. Changes in extensions do not lead to an increase in the version , but MUST lead to an updated lastUpdate date.Since the extensions are managed by the customer or a partner, whether those changes are compatible or not is not guaranteed by the base contract of the resource. | ||
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. | ||
string | The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values:
Introduced in Version: 1.3.0 Example Values:
| |
string | If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided.The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom .MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
boolean | Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true.An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values:
|
Capability
Capabilities can be used to describe use case specific capabilities, most notably supported features or additional information (like configuration) that needs to be understood from outside. This is a generic ORD concept that aims to cover many different capability discovery use cases that would otherwise need be implemented as individual service provider interfaces (SPIs).
If a capability needs to expose more information than possible with generic capability properties, a custom capability definition can be defined and referenced in ORD. This is the same idea and mechanism as with API resources and their resource definition formats.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(capability):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Type of the Capability Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead.All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ | |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
string | Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time.Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.Together with systemInstanceAware , this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values:
| |
string | The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values:
| |
string | The releaseStatus specifies the stability of the resource and its external contract.Allowed Values:
Example Values:
| |
Array<string> | Optional list of related EntityType Resources. MUST be a valid reference to an EntityType Resource ORD ID. Array Item Association Target: Entity Type.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
Array<Capability Definition> | List of available machine-readable definitions, which describe the resource or capability in detail. Each definition is to be understood as an alternative description format, describing the same resource / capability. As a consequence the same definition type MUST NOT be provided more than once. It is RECOMMENDED to provide the definitions as they enable machine-readable use cases. If the definitions are added or changed, the version MUST be incremented.An ORD aggregator MAY only (re)fetch the definitions again when the version was incremented. | |
Array<Link> | Generic Links with arbitrary meaning and content. | |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. | ||
boolean | Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true.An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values:
|
Data Product
A Data Product is a data set exposed for consumption outside the boundaries of the producing application via APIs and described by high quality metadata that can be accessed through the ORD Aggregator.
Please note that this concept is in beta, see Data Product - Beta Status.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead.All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ | |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
string | Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time.Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.Together with systemInstanceAware , this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values:
| |
string | The visibility/exposure of the data product. A public data product might have private APIs for trusted consumers therefore the having the property on data product Allowed Values:
| |
string | The releaseStatus specifies the stability towards incompatible changes in the future.In the context of data products, it it covers only properties on the data product level. APIs that are part of the input and output ports have their own independent releaseStatus and version .Allowed Values:
Example Values:
| |
string | Lifecycle status of the Data Product as a whole. MUST be provided when describing the system-instance aware (run-time) perspective. SHOULD NOT be provided in static (design-time) perspective. Static aggregators MUST ignore this property. Allowed Values:
Example Values:
| |
string | The deprecation date defines when the resource has been set as deprecated. This is not to be confused with the sunsetDate which defines when the resource will be actually decommissioned / removed.If the releaseStatus is set to deprecated , the deprecationDate SHOULD be provided.The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
string | The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated , the sunsetDate SHOULD be provided (if already known).Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
Array<string> | The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated , successors MUST be provided if one exists.If successors is given, the described resource SHOULD set its releaseStatus to deprecated .Array Item Association Target: Data Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
Array<Changelog Entry> | Contains changelog entries that summarize changes with special regards to version and releaseStatus | |
string | Type of the data product. Based on the type some properties of a data product may become optional/mandatory. Allowed Values:
Example Values:
| |
string | Category of the data-set within data product. Based on its definition, a data product is a “data set” - which can include on the values below. Based on the type some properties of a data product may become optional/mandatory. Consumers might still do analytics on business object like data products. Allowed Values:
Example Values:
| |
Array<string> | 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. Array Item Association Target: Entity Type.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
Array<Data Product Input Port> | The input ports of a data product indicate the data inputs for lineage purposes. It is a list of Integration Dependencies, whose aspects will form the actual input ports. Input ports can also be understood as the public interface to ingest data into the data product. Data products of type derived consume data through the input ports. Different input ports allowing ingestion of different sub-sets building up the data-set for the data product.Data products of type base might not have any input ports. Their data sets are typically based directly on the applications / services own data.Example Values:
| |
Array<Data Product Output Port> | Output ports are the interface (APIs and Events) through which the data of the data product can be accessed. Output ports of the same data product might produce different facets of the data set with different qualities. A data set can also be made available via different protocols, which also results in different ports. As long as different output ports are accessing the same model beneath, they should belong to the same data product. If the above criteria cannot be reasonably met, consider splitting the data product into multiple smaller data products. Array Constraint: MUST have at least 1 items Example Values:
| |
string | Contains typically the organization that is responsible in the sense of RACI matrix for this ORD resource. This includes support and feature requests. It is maintained as correlation id to for example support components. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Introduced in Version: 1.8.0 Example Values:
| |
Array<Data Product Link> | Links with semantic meaning that are specific to Data Product Resources. | |
Array<Link> | Generic Links with arbitrary meaning and content. | |
Array<string> | List of industry tags. No special characters are allowed except - , _ , . , / and .industry that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
Array<string> | List of line of business tags. No special characters are allowed except - , _ , . , / and .lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. | ||
string | The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values:
Introduced in Version: 1.3.0 Example Values:
| |
string | If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided.The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom .MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
boolean | Defines whether this ORD resource is system instance aware. This is the case (and relevant) when the referenced resource definitions are potentially different between system instances. If this behavior applies, systemInstanceAware MUST be set to true.An ORD aggregator that represents a system instance aware perspective MUST fetch the referenced resource definitions, not just once per system type, but once per system instance. Example Values:
|
Integration Dependency
An Integration Dependency states that the described system (self) can integrate with external systems (integration target) to achieve an integration purpose. The purpose could be to enable a certain feature or integration scenario, but it could also be a mandatory prerequisite for the described system to work.
The integration dependency includes a list of individual aspects that the integration consists of. Aspects are an "ingredient" for the integration scenario (and are logically combined with AND condition). Each aspect can express alternatives (OR condition) on what API and event resources can be used to achieve the same outcome.
The direction of connection establishment, data flow is not directly implied and needs to be inferred from the referenced resources.
It is not in scope for the Integration Dependency to describe scenarios that external consumers have with the own exposed resources. This would overstep the boundary of self-description.
If an integration scenario consists of two sides integration with each other, each need to describe its own part in it as an Integration Dependency. Therefore, if an integration with multiple types of systems need to be setup, this SHOULD be separated into distinct Integration Dependencies.
An integration dependency is also not meant to describe a bigger process. Instead it focuses on the technical necessaries to create an integration for one particular purpose.
To learn more about the concept, see Integration Dependency.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | Defines which Package the resource is part of. MUST be a valid reference to a Package ORD ID. Every resource MUST be part of one package. Association Target: Package.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<string> | Defines which groups the resource is assigned to. The property is optional, but if given the value MUST be an array of valid Group IDs. Groups are a lightweight custom taxonomy concept. They express a "part of" relationship to the chosen group concept. If an "identity / equals" relationship needs to be expressed, use the correlationIds instead.All resources that share the same group ID assignment are effectively grouped together. Array Item Association Target: Group.groupId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ | |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
string | Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time.Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.Together with systemInstanceAware , this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values:
| |
string | The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values:
| |
string | The releaseStatus specifies the stability of the resource and its external contract.Allowed Values:
Example Values:
| |
string | The sunset date defines when the resource is scheduled to be decommissioned/removed. If the releaseStatus is set to deprecated , the sunsetDate SHOULD be provided (if already known).Once the sunset date is known and ready to be communicated externally, it MUST be provided here. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
Array<string> | The successor resource(s). MUST be a valid reference to an ORD ID. If the releaseStatus is set to deprecated , successors MUST be provided if one exists.If successors is given, the described resource SHOULD set its releaseStatus to deprecated .Array Item Association Target: Integration Dependency.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
boolean | If true, the Integration Dependency is mandatory for the described system to function. | |
Array<Aspect> | List of integration aspects that make up the Integration Dependency. Each aspect listed is a dedicated, constituent part (AND condition). | |
Array<string> | If an Integration Dependency conceptually belongs or related to another Integration Dependency, this can be indicated here. One situation would be where two systems each have an Integration Dependency to describe a two-sided integration from each side. Array Item Association Target: Integration Dependency.ordId Array Item Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Example Values:
| |
Array<Link> | Generic Links with arbitrary meaning and content. | |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. |
Vendor
The vendor of a product or a package, usually a corporation or a customer / user.
The vendor of a Package
is the owner or creator of the content of the package.
The vendor of a Product
is the owner of the product.
If the resources are created by the customer / user of the described system, customer:vendor:Customer:
MUST be used as vendor.
Both have already a vendor namespace within their ORD ID.
The Vendor
entity is giving more details on the vendor namespace.
For one vendor namespace there MUST only be exactly one Vendor
ORD entity describing it.
For example: The only correct value for a SAP vendor reference is sap:vendor:SAP:
.
Property | Type | Description |
---|---|---|
string | ||
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
Array<string> | Optional list of partner vendors, referenced through their ORD ID. MUST be a valid reference to a Vendor ORD ID. This property can be used to indicate partnership relations between vendors. Array Item Association Target: Vendor.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ Example Values:
| |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. |
Product
A product in ORD is understood as a commercial product or service.
It is a high-level entity for structuring the software portfolio from a sales / software logistics perspective. While system type is a technical concept, product covers the commercial and marketing view.
Please note that the ORD concept of a product is very simple on purpose. There is no distinction between products and services and concepts like product versions, variants, etc.
ORD assumes that this is handled by specialized systems and that ORD only provides the means to correlate to them.
Property | Type | Description |
---|---|---|
string | ||
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values: | |
string | Vendor / organization that is responsible for the Product. MUST be a valid reference to a Vendor ORD ID. Association Target: Vendor.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ Maximum Length: 256 Example Values:
| |
string | ||
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. |
Package
A Package organizes a set of related resources together, by publishing and catalog presentation concerns.
The Package can also be used to indicate which products or vendors provided the packaged resources.
For partner or customer content, the package can indicate this via the vendor
and partOfProducts
assignments.
In any case, the Package ordID
namespace MUST reflect the namespace of the providing application (which hosts the resource), not the resource definition owner, which could be a customer or partner.
A package SHOULD contain at least one resource. Avoid empty packages.
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.
Property | Type | Description |
---|---|---|
string | ||
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
string | The policy level (aka. compliance level) that the described resources need to be compliant with. Depending on the chosen policy level, additional expectations and validations rules will be applied. The policy level can be defined on ORD Document level, but also be overwritten on an individual package or resource level. Default Value: "none" Allowed Values:
Introduced in Version: 1.3.0 Example Values:
| |
string | If the fixed policyLevel values need to be extended, an arbitrary customPolicyLevel can be provided.The policy level is inherited from packages to resources they contain, but can be overwritten at resource level. MUST only be provided if policyLevel is set to custom .MUST be a valid Specification ID. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
Array<Package Link> | Links with semantic meaning that are specific to packages. | |
Array<Link> | Generic links with arbitrary meaning and content. packageLinks MUST be preferred if applicable. | |
string | ||
string | Optional information that should be provided when creating a support ticket for the resources bundled in this package. This can for example be a "component" name that needs to be chosen in the support portal. Notated in CommonMark (Markdown). Please also note that if you want to provide link(s) where you can find support information, you can use packageLinks with a link of type support .Minimum Length: 1 Introduced in Version: 1.1.0 | |
string | Vendor / organization that is the creator (or responsible party) of the resources that are part of the Package .MUST be a valid reference to a Vendor ORD ID. MUST be set to customer:vendor:Customer: if the contents of the package are created by the customer / user.MUST be set to a registered partner vendor, if the contents of the package are created by a partner / third party. Association Target: Vendor.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(vendor):([a-zA-Z0-9._\-]+):()$ Maximum Length: 256 Example Values:
| |
Array<string> | List of products this resource is a part of. MUST be a valid reference to a Product ORD ID. partOfProducts that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Association Target: Product.ordId Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(product):([a-zA-Z0-9._\-]+):()$ Example Values:
| |
Array<string> | List of countries that the package resources are applicable to. MUST be expressed as an array of country codes according to IES ISO-3166 ALPHA-2. countries that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[A-Z]2$ Example Values:
| |
Array<string> | List of line of business tags. No special characters are allowed except - , _ , . , / and .lineOfBusiness that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
Array<string> | List of industry tags. No special characters are allowed except - , _ , . , / and .industry that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/& ]*$ Array Item Recommended Values:
Example Values:
| |
string | Runtime Restriction If provided, all resources that are part of this package can only run on the listed runtime. Allowed Values:
Introduced in Version: 1.8.0 | |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. |
Consumption Bundle
A Consumption Bundle groups APIs and Events together that can be consumed with the credentials and auth mechanism. Ideally it also includes instructions and details how to request access and credentials for resources.
For more documentation and guidance how to correctly this correctly, see Consumption Bundle details.
A consumption bundle SHOULD have at least one association with a resource (0..n). Avoid empty consumption bundles. A consumption bundle MUST NOT contain APIs and Events that are NOT defined in the ORD document(s) returned by the system instance that defines the consumption bundle.
Please note that some ORD consumer use cases MAY depend on consumption bundle assignments to work with the resources.
To learn more about the concept, see Consumption Bundle.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Local ID, as known by the described system. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Plain text short description. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string | The complete SemVer version string. It MUST follow the Semantic Versioning 2.0.0 standard. It SHOULD be changed if the ORD information or referenced resource definitions changed. It SHOULD express minor and patch changes that don't lead to incompatible changes. When the version major version changes, the ORD ID <majorVersion> fragment MUST be updated to be identical.In case that a resource definition file also contains a version number (e.g. OpenAPI info .version ), it MUST be equal with the resource version to avoid inconsistencies.If the resource has been extended by the user, the change MUST be indicated via lastUpdate .The version MUST not be bumped for changes in extensions.The general Version and Lifecycle flow MUST be followed. Note: A change is only relevant for a version increment, if it affects the ORD resource or ORD taxonomy directly. For example: If a resource within a Package changes, but the package itself did not, the package version does not need to be incremented.Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Introduced in Version: 1.2.1 Example Values:
| |
string | Optional, but RECOMMENDED indicator when (date-time) the last change to the resource (including its definitions) happened. The date format MUST comply with RFC 3339, section 5.6. When retrieved from an ORD aggregator, lastUpdate will be reliable there and reflect either the provider based update time or the aggregator processing time.Therefore consumers MAY rely on it to detect changes to the metadata and the attached resource definition files. If the resource has attached definitions, either the version or lastUpdate property MUST be defined and updated to let the ORD aggregator know that they need to be fetched again.Together with systemInstanceAware , this property SHOULD be used to optimize the metadata crawling process of the ORD aggregators.JSON Schema Format: date-time Introduced in Version: 1.4.0 Example Values:
| |
string | The visibility/exposure of the described resource or capability. This indicates who is allowed to see (and implicitly also access) this. Allowed Values:
| |
Array<Credential Exchange Strategy> | Defines the supported strategies for how the consumption credentials can be exchanged. Ideally, the system type supports a strategy that can automate the exchange. | |
Array<Link> | Generic links with arbitrary meaning and content. | |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. |
Group
Group (instance) that resources can be assigned to.
Groups are a lightweight custom taxonomy concept.
They express a "part of" relationship to the chosen group concept.
If an "identity / equals" relationship needs to be expressed, use the correlationIds
instead.
To learn more about the concept, see Group Concept Documentation.
Property | Type | Description |
---|---|---|
string | The Group ID consists of two Concept IDs separated by a : .The first two fragments MUST be equal to the used Group Type ID ( groupTypeId ).The last two fragments MUST be a valid Concept ID, indicating the group instance assignment. The ID concept is a bit unusual, but it ensures globally unique and conflict free group assignments. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Group Type ID. MUST match with the first two fragments of the own groupId .Association Target: Group Type.groupTypeId Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human readable title of the group assignment (for UI). Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
|
Group Examples
{
"groupId": "sap.cap:service:customer.incidents:incidents.IncidentsService",
"groupTypeId": "sap.cap:service",
"title": "Incidents Service"
}
Group Type
A Group Type defines the semantics of group assignments.
What the Group Type means and how it is to be used correctly SHOULD be described in the description
(which may include markdown links).
Group Types can be defined centrally (ownership by authority namespace) or decentrally (defined by application / service itself).
To learn more about the concept, see Group Concept Documentation.
Property | Type | Description |
---|---|---|
string | GroupType ID, which MUST be a valid Concept ID. Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | Human readable title of the group type. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
|
Group Type Examples
{
"groupTypeId": "sap.cds:service",
"title": "CAP Service",
"description": "Description of the CDS Service concept and how its correctly used for grouping..."
}
Tombstone
A tombstone indicates that a previously published ORD resource or taxonomy has been removed / decommissioned. This MUST be indicated explicitly, so ORD aggregators and consumers can learn about the removal.
Exactly one of the IDs MUST be provided to state which ORD resource or taxonomy item the Tombstone addresses.
It MUST be kept sufficiently long so that all ORD aggregators can learn about the tombstone. After that it MAY be removed.
Property | Type | Description |
---|---|---|
string | ORD ID of the ORD resource/taxonomy that has been removed. Association Target: Package.ordId | Consumption Bundle.ordId | Product.ordId | Vendor.ordId | API Resource.ordId | Event Resource.ordId | Capability.ordId | Entity Type.ordId | Integration Dependency.ordId | Data Product.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(package|consumptionBundle|product|vendor|apiResource|eventResource|capability|entityType|integrationDependency|dataProduct):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*|)?$ Maximum Length: 255 Example Values:
| |
string | ||
string | Group Type ID of the group type that has been removed. Association Target: Group Type.groupTypeId Regex Pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
string | The date when the ORD resource/taxonomy was removed. This is related to the sunsetDate that can be set to announce a resource as deprecated before the removal and setting of a tombstone.The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date-time Example Values:
| |
string | Optional description, notated in CommonMark (Markdown). The description of a Tombstone MAY be added to the changelog of the removed resource by an ORD aggregator. Minimum Length: 1 Example Values:
|
Tombstone Examples
{
"ordId": "sap.s4:apiResource:API_RFQ_PROCESS_SRV:v2",
"removalDate": "2020-12-02T14:12:59Z"
}
{
"groupId": "sap.foo:domain:sap.foo:DomainName",
"removalDate": "2020-12-02T14:12:59Z"
}
Consumption Bundle Reference
Reference to a Consumption bundle.
This is a complex object to allow additional properties / selections to be attached.
Property | Type | Description |
---|---|---|
string | The consumption bundle ORD ID ( ConsumptionBundle.ordId ) this reference points to.Association Target: Consumption Bundle.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(consumptionBundle):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | In case that an API Resource has multiple entry points, this will indicate which entry point should be used by default when discovering this resource from the context of the referenced Consumption Bundle. MUST NOT be provided for Event Resources, as they don't have entry points. MUST only be provided if the resource has more than one entry point. MUST be in the list of entryPoints of the affected resource.JSON Schema Format: uri-reference |
Data Product Input Port
An input port of a data product states where it retrieves its data inputs from.
It is described as via an ORD Integration Dependency.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: Integration Dependency.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(integrationDependency):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
|
Data Product Output Port
A data product output port references the APIs or Events that can be used to access the data-set. It MAY provide full access to the complete data set, but can also just expose a subset of it - if other output ports cover the missing parts.
Referenced API or Event ORD resources don't need to be provided within the same ORD document. If a data product is built against a specific API contract of another application or data product, this API resource should be referred to. In this case the other application is responsible for the lifecycle of the API contract and will update its ORD description independently.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: API Resource.ordId | Event Resource.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource|eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
|
API Resource Definition
Link and categorization of a machine-readable API definition. For example, OpenAPI definition, OData Metadata, etc.
Property | Type | Description |
---|---|---|
string | Type of the API Resource Definition If "custom" is chosen, a customType MUST be provided Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | The Media Type of the definition serialization format. A consuming application can use this information to know which file format parser it needs to use. For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON. If no Media Type is registered for the referenced file, text/plain MAY be used for arbitrary plain-text and application/octet-stream for arbitrary binary data.Allowed Values:
Example Values:
| |
string | URL reference (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). JSON Schema Format: uri-reference Example Values:
| |
Array<Access Strategy> | List of supported access strategies for retrieving metadata from the ORD provider. An ORD Consumer/ORD Aggregator MAY choose any of the strategies. The access strategies only apply to the metadata access and not the actual API access. The actual access to the APIs for clients is described via Consumption Bundles. If this property is not provided, the definition URL will be available through the same access strategy as this ORD document. It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process. Array Constraint: MUST have at least 1 items Example Values:
|
Event Resource Definition
Link and categorization of a machine-readable API definition. For example, AsyncAPI or OpenAPI with callbacks, etc.
Property | Type | Description |
---|---|---|
string | Type of the event resource definition Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | The Media Type of the definition serialization format. A consuming application can use this information to know which file format parser it needs to use. For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON. If no Media Type is registered for the referenced file, text/plain MAY be used for arbitrary plain-text and application/octet-stream for arbitrary binary data.Allowed Values:
Example Values:
| |
string | URL reference (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). JSON Schema Format: uri-reference Example Values:
| |
Array<Access Strategy> | List of supported access strategies for retrieving metadata from the ORD provider. An ORD Consumer/ORD Aggregator MAY choose any of the strategies. The access strategies only apply to the metadata access and not the actual API access. The actual access to the APIs for clients is described via Consumption Bundles. If this property is not provided, the definition URL will be available through the same access strategy as this ORD document. It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process. Array Constraint: MUST have at least 1 items Example Values:
|
Capability Definition
Link and categorization of a machine-readable capability definition.
Property | Type | Description |
---|---|---|
string | Type of the capability resource definition Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | The Media Type of the definition serialization format. A consuming application can use this information to know which file format parser it needs to use. For example, for OpenAPI 3, it's valid to express the same definition in both YAML and JSON. If no Media Type is registered for the referenced file, text/plain MAY be used for arbitrary plain-text and application/octet-stream for arbitrary binary data.Allowed Values:
Example Values:
| |
string | URL reference (URL or relative reference) to the resource definition file. It is RECOMMENDED to provide a relative URL (to base URL). JSON Schema Format: uri-reference Example Values:
| |
Array<Access Strategy> | List of supported access strategies for retrieving metadata from the ORD provider. An ORD Consumer/ORD Aggregator MAY choose any of the strategies. The access strategies only apply to the metadata access and not the actual API access. The actual access to the APIs for clients is described via Consumption Bundles. If this property is not provided, the definition URL will be available through the same access strategy as this ORD document. It is RECOMMENDED anyway that the attached metadata definitions are available with the same access strategies, to simplify the aggregator crawling process. Array Constraint: MUST have at least 1 items Example Values:
|
Aspect
An (integration) aspect is the constituent part that makes up an Integration Dependency.
Each aspect can list references to resources, which could be owned and defined by the integration target or by the described system itself. In case the reference links to own resources, it is implied that they are to be used by the integration target to fulfill the Integration Dependency.
If multiple resources are given within an aspect, they are considered alternatives to each other (OR condition). In case an AND condition is needed, multiple aspects need to be added to the Integration Dependency.
Property | Type | Description |
---|---|---|
string | Human-readable title. MUST NOT exceed 255 chars. MUST NOT contain line breaks. Minimum Length: 1 Maximum Length: 255 Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
boolean | If true, the aspect is mandatory to realize the Integration Dependency it contains. | |
boolean | If true, the references resources can be provided by multiple system instances. If not, only one integration target is supported. | |
List of API Resource Dependencies. | ||
List of Event Resource Dependencies. |
API Resource Integration Aspect
API resource related integration aspect
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(apiResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Minimum version of the references resource that the integration requires. Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
|
Event Resource Integration Aspect
Event resource related integration aspect
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(eventResource):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
| |
string | Minimum version of the references resource that the integration requires. Regex Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ Example Values:
| |
List of individual events or messages that are sufficient to achieve the aspect. | ||
Array<string> | In case that the event subscriptions are limited to known system types, they can be listed here as system namespaces. If given, only system types of the defined namespaces are supported as integration partners. If not given, there is no restriction which system type provides the events. Array Constraint: MUST have at least 1 items Array Item Regex Pattern: ^[a-z0-9]+(?:[.][a-z0-9]+)1$ Example Values:
|
Event Resource Integration Aspect Subset
Defines that Event Resource Integration Aspect only requires a subset of the referenced contract.
For events, this could be a list of the events that need to be subscribed in order to make the integration work. This information helps to narrow down what is really necessary and can help optimize the integration, e.g. by only publishing the events that are really needed.
Property | Type | Description |
---|---|---|
string | The type ID of the individual event or message. This MUST be an ID that is understood by the used protocol and resource definition format. E.g. for CloudEvents, the type can be used. Example Values:
|
Changelog Entry
A changelog entry can be used to indicate changes. Usually they lead to a change of the version number or the release status.
Property | Type | Description |
---|---|---|
string | Full version number that corresponds to the version that is described by the changelog entry.Ideally it follows the Semantic Versioning 2.0.0 standard, but since it should reflect the actual version string / scheme used, this is not a mandatory requirement. Minimum Length: 1 Example Values:
| |
string | The releaseStatus specifies the stability of the resource and its external contract.Allowed Values:
Example Values:
| |
string | Date of change, without time or timezone information. The date format MUST comply with RFC 3339, section 5.6. JSON Schema Format: date Example Values:
| |
string | Full description, notated in CommonMark (Markdown). The description SHOULD not be excessive in length and is not meant to provide full documentation. Detailed documentation SHOULD be attached as (typed) links. Minimum Length: 1 Example Values:
| |
string |
Link
Link that can be attached to packages or Open Resource Discovery resources.
Property | Type | Description |
---|---|---|
string | Human readable title of the link. MUST be unique within the collection of links provided. Minimum Length: 1 Example Values:
| |
string | URL of the link. JSON Schema Format: uri Example Values:
| |
string | Full description, notated in CommonMark (Markdown) Minimum Length: 1 Example Values:
|
Link Examples
{
"url": "https://blogs.sap.com/2018/04/11/testing-of-s4hana-inventory-management-odata-apis-via-sap-api-hub/",
"title": "APIs for SAP S/4HANA",
"description": "This gives you an overview on where to find which kind of APIs in SAP S/4HANA."
}
Package Link
Links with specific semantic meaning that are related to Package
.
If a generic Link
can also be expressed via PackageLink
, the latter MUST be chosen.
Property | Type | Description |
---|---|---|
string | Package link type Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | URL to the PackageLink. For more information, see type .JSON Schema Format: uri Example Values:
|
Package Link Examples
{
"type": "terms-of-service",
"url": "https://www.sap.com/corporate/en/legal/terms-of-use.html"
}
API and Event Resource Link
Links with specific semantic meaning that are related to API or event resources.
If a generic Link
can also be expressed via an APIEventResourceLink
, the latter MUST be chosen.
Property | Type | Description |
---|---|---|
string | See also: WADG0001 WebAPI type extension Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | URL reference (URL or relative reference) to the endpoint or UI for the action. If the link is relative to base URL, it is RECOMMENDED to provide a relative URL. JSON Schema Format: uri-reference Example Values:
|
API and Event Resource Link Examples
{
"type": "api-documentation",
"url": "https://api.sap.com/api/API_OPLACCTGDOCITEMCUBE_SRV/resource"
}
Data Product Link
Links with specific semantic meaning that are related to Data Product resources.
If a generic Link
can also be expressed via DataProductLink
, the latter MUST be chosen.
Property | Type | Description |
---|---|---|
string | API action type. See also: WADG0001 WebAPI type extension Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | URL reference (URL or relative reference) to the endpoint or UI for the action. If the link is relative to base URL, it is RECOMMENDED to provide a relative URL. JSON Schema Format: uri-reference Example Values:
|
Data Product Link Examples
{
"type": "support",
"url": "https://support.sap.com/CIC_DP_RT/issue/"
}
System Instance
A system instance is a concrete, running instance of a system type. In a multi-tenant system, this corresponds to a tenant.
Property | Type | Description |
---|---|---|
string | Optional base URL of the system instance. By providing the base URL, all relative references in the document are resolved relative to it. The baseUrl MUST not contain a leading slash.MUST be provided if the base URL is not known to the ORD aggregators. MUST be provided when the document needs to be fully self contained, e.g. when used for manual imports. JSON Schema Format: uri Regex Pattern: ^http[s]?:\/\/[^:\/\s]+\.[^:\/\s\.]+(:\d+)?(\/[a-zA-Z0-9-\._~]+)*$ Example Values:
| |
string | Optional local ID for the system instance, as known by the described system. In the context of a system instance, this is usually the local tenant id. Maximum Length: 255 Introduced in Version: 1.2.1 Example Values:
| |
Array<string> | Correlation IDs can be used to create a reference to related data in other repositories (especially to the system of record). They express an "identity" / "equals" / "mappable" relationship to the target ID. If a "part of" relationship needs to be expressed, use the partOfGroups assignment instead.MUST be a valid Correlation ID. Array Item Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Example Values:
| |
Array<string> | List of free text style tags. No special characters are allowed except - , _ , . , / and .Tags that are assigned to a Package are inherited to all of the ORD resources it contains.Array Item Regex Pattern: ^[a-zA-Z0-9-_.\/ ]*$ Example Values:
| |
Generic labels that can be applied to most ORD information. | ||
Generic documentation labels that can be applied to most ORD information. |
Access Strategy
Defines the access strategy for accessing the resource definitions.
Property | Type | Description |
---|---|---|
string | Defines the authentication/authorization strategy through which the referenced resourceDefinitions are accessible.Allowed Values:
Example Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | Human-readable description about how the access is set up, notated in CommonMark (Markdown). MUST only be provided if type is set to custom .Minimum Length: 1 Example Values:
|
Access Strategy Examples
{
"type": "open"
}
{
"type": "custom",
"customType": "sap.xref:open-local-tenant-id:v1",
"customDescription": "Custom description how to use custom access strategy"
}
Credential Exchange Strategy
ALPHAThe credential exchange strategy specifies how a set of credentials for a particular usage of the APIs in the consumption bundle can be obtained. Until a SAP-wide strategy for obtaining such credentials exists and is agreed upon, both LoBs and aggregators (namely Unified Customer Landscape) can define their own strategy specifications.
While the actual flow in term of API calls can differ between the different strategies, the end goal would always be the possibility for automatically obtaining credentials for each client that would like to use the APIs from a particular bundle.
Property | Type | Description |
---|---|---|
string | The type of credential exchange strategy. Allowed Values:
| |
string | If the fixed type enum values need to be extended, an arbitrary customType can be provided.MUST be a valid Specification ID. MUST only be provided if type is set to custom .Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$ Maximum Length: 255 Example Values:
| |
string | Human-readable description about how the credential exchange is achieved, notated in CommonMark (Markdown). MUST only be provided if type is set to custom .Minimum Length: 1 Example Values: | |
string | URL reference (URL or relative reference) to the credential exchange callback endpoint. This allows requesting a set of credentials that can be used for consuming all the APIs and Events that are part of the bundle. The interface contract/protocol is dependent and defined by the chosen type .Whenever a client wants to consume a resource within a particular bundle, this endpoint can be called to obtain the credentials that this client can use. The returned credentials MUST be valid for all resources that are part of the respective bundle. The endpoint SHOULD return a different set of credentials on each invocation. JSON Schema Format: uri Example Values:
|
Labels
Generic labels that can be applied to most ORD information. They are defined as an object that may have arbitrary keys. The value of a key is an array of strings.
Labels can be used to attach technical information that cannot be expressed natively in ORD. An ORD aggregator should allow to categorize and query information based on the labels provided.
If multiple parties rely on the existence of certain label information, standardization through ORD SHOULD be preferred.
All labels attached to a Package
will be inherited to the resources they contain.
Duplicate labels will be merged by the ORD aggregator according to the following rules:
- Values of the same label key will be merged.
- Duplicate values of the same label key will be removed.
Property | Type | Description |
---|---|---|
^[a-zA-Z0-9-_.]*$ | array<string> | Additional properties with a key name pattern "^[a-zA-Z0-9-_.]*$" MAY be added. |
Labels Examples
{
"label-key-1": [
"label-value-1",
"label-value-2"
]
}
Documentation Labels
Generic documentation labels that can be applied to most ORD information. They are defined as an object that may have arbitrary keys. The value of a key is an array of CommonMark (Markdown) text.
Documentation Labels can be used to attach human readable documentation that cannot be expressed natively in ORD. A documentation tool (like an API Catalog) can use the documentation labels to provide generic documentation "snippets". Due to the given structure they can be displayed e.g. as tables.
The key of the documentation Label is plain-text (MUST not contain line breaks) and denotes the subject matter that is described. The values (multiple can be provided for the same key) are CommonMark (Markdown) text which describes the subject matter or lists options for the key.
In contrast to regular labels, documentation labels are not meant to be used to categorize or query information.
Property | Type | Description |
---|---|---|
^.*$ | array<string> | Additional properties with a key name pattern "^.*$" MAY be added. |
Documentation Labels Examples
{
"Scope Items": [
"[Basic Bank Account Management (BFA)](https://rapid.sap.com/bp/#/scopeitems/BFA \\\" Link To BP \\\")"
]
}
Extensible
Contains information about the extensibility of this resource.
If applicable, a description and further resources about extending this resource are provided.
Property | Type | Description |
---|---|---|
string | This property defines whether the resource is extensible. Not extensible means that the data model of the resource (i.e. API or event) cannot be extended with custom fields. Manually extensible means that in addition to defining a custom field, manual activities to include the field in the data model of the resource (i.e. API or event) are required. E.g. using a specific mapping tool or by selecting the resource in the data model extension tool. Automatically extensible means that after defining a custom field in the local domain model, the resource (i.e. API or event) is automatically extended as part of the default extension field definition. Allowed Values:
| |
string | A description about the extensibility capabilities of this API, notated in CommonMark (Markdown). This description may contain detailed steps on how to extend the API. Links to external resources can be provided within the description as markdown links. This description MUST be provided if supported is set to manual or automatic .Minimum Length: 1 Example Values:
|
Extensible Examples
{
"supported": "manual",
"description": "API can be extended by custom fields on the following business contexts (field usage for this API needs to be selected):\r\n* Procurement: Purchasing Document (MM_PURDOC_HEADER)\r\n* Procurement: Purchasing Document Item (MM_PURDOC_ITEM)\r\n\r\n[How to add an extension field to an API](https://help.sap.com/viewer/9a281eac983f4f688d0deedc96b3c61c/latest/en-US/57909455bf7c4fdd8bcf48d76c1eae33.html)"
}
Entity Type Mapping
An API or Event resource may optionally define its entityTypeMappings
.
This is used to map and correlate the API models to the underlying, conceptual entity types.
If the mapping from API resource to entity types is not defined, certain use-cases that rely on this explicit connection will not be possible.
This mapping is meant to be rather fine granular. Therefore, the mapping needs to be done on basis of one of the referenced resource definitions, as only there we know the details and the actual contents of the API Model of the API resource.
For the various resource definition formats the selection of API models may need to be expressed differently. As a consequence, there are different types of selectors that are specialized toward certain resource definition formats.
The target of the mapping is a correlation to an entity type via a Correlation ID
or to an [ORD ID] of an entity type.
It is assumed that the entity types are described in more detail or on a different abstraction level via metadata.
When the correlation ID is used, an ORD consumer may need to know how to access the entity type metadata through conventions.
This can be determined either by the namespace of the correlation ID,
or through a defined and known implementationStandard
that can resolve the localId
fragment of the correlation ID .
At SAP, the metadata about entity types could be retrieved via the CSN_EXPOSURE service.
To indicate this, the service needs to be implemented and described in ORD with implementationStandard
set to sap:csn-exposure:v1
).
ODM 2.0 relies on the entity type mappings and uses the the mapping to express the relationship of an API to the corresponding ODM entity. ORD consumers like SAP Business Accelerator Hub consume the mapping to make the relationships navigatable for customers.
Property | Type | Description |
---|---|---|
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. | ||
List of entity types the ORD resource maps to. If apiModelSelectors are given, the mapping is more precise by also pointing to the specific model in the API.If multiple entity types are defined as the mapping target, all of them can be at least partially mapped to the source API model(s). Entity types can be referenced using either using an ORD ID or a Correlation ID. Array Constraint: MUST have at least 1 items |
API Model Selector (OData)
API Model Selector for OData, using entity set names for the selection.
MUST only be used if the API Resource provides an API Resource Definition of type edmx
.
Property | Type | Description |
---|---|---|
string | The type for OData selectors is fixed to odata .Allowed Values:
| |
string | OData entity set name. As defined in the EDMX, e.g. <EntitySet Name="AttachmentContent"> .Minimum Length: 1 Example Values:
|
API Model Selector (OData) Examples
{
"type": "odata",
"entitySetName": "AttachmentContent"
}
API Model Selector (JSON Pointer)
Generic API Model Selector for JSON / YAML based resource definitions. It uses a JSON Pointer that points to the entity type description within the resource definition.
The JSON Pointer always to refer to the structure of the document as originally provided, before further post-processing like resolving $ref properties.
MUST only be used if the API Resource provides an API Resource Definition of media type application/json
or text/yaml
.
Property | Type | Description |
---|---|---|
string | The type for generic JSON Pointer selectors is fixed to json-pointer .Allowed Values:
| |
string | JSON Pointer to the entity type schema / description within the resource definition format. MUST be a valid JSON Pointer according to RFC6901. The JSON pointers MUST point to each instance of the mapped entity type in the resource definition file, BEFORE $ref JSON Schema References are resolved (dereferenced).Minimum Length: 1 Example Values:
|
API Model Selector (JSON Pointer) Examples
{
"type": "json-pointer",
"jsonPointer": "#/objects/schemas/AttachmentContent"
}
Related Entity Type
Defines which Entity Type is related (via its ORD ID). In the future, this could include stating the relationship type, too.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: Entity Type.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
|
Entity Type Target (ORD ID)
Define which entity type is the target of an entity type mapping
Entity types can be referenced using a ORD ID of an entity type.
Property | Type | Description |
---|---|---|
string | The ORD ID is a stable, globally unique ID for ORD resources or taxonomy. It MUST be a valid ORD ID of the appropriate ORD type. Association Target: Entity Type.ordId Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):(entityType):([a-zA-Z0-9._\-]+):(v0|v[1-9][0-9]*)$ Maximum Length: 255 Example Values:
|
Entity Type Target (Correlation ID)
Define which entity type is the target of an entity type mapping
Entity types can be referenced using a Correlation ID.
Property | Type | Description |
---|---|---|
string | Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-\/]+):([a-zA-Z0-9._\-\/]+)$ Maximum Length: 255 Example Values:
|