Open Resource Discovery Specification 1.17

Open Resource Discovery (ORD) is an open protocol that enables applications and services to publish a machine-readable description of their resources and capabilities. This document defines the normative information model, provider interfaces, and aggregation behavior for ORD 1.17.

If you are new to ORD, start with the ORD Introduction or use the visual presentation for a guided walkthrough. The presentation source is available on GitHub.

Specification Overview

The specification is organized around four questions. Use this map to go directly to the normative section you need.

Applying the Specification

The most common way to apply ORD is to describe the resources and capabilities of an application or service. Start with static metadata, then decide whether publishing a runtime-specific view provides additional value.

1. Identify what the application exposes and requires. Describe its APIs, Events, Data Products, Capabilities, Agents, and Integration Dependencies, and link their native resource definitions where applicable.
2. Publish a static description first. Choose the appropriate system-type or system-version perspective, then expose the ORD configuration, ORD documents, and referenced definitions by following Implementing ORD Natively.
3. Evaluate whether a system-instance view adds value. Add system-instance publishing when resources or metadata differ at runtime because of tenant configuration, feature activation, extensions, user-created resources, or dynamic endpoints. A published system-instance perspective is a complete description of that instance, not a patch over the static baseline.
4. Add structure and lifecycle guidance as needed. Use the System Landscape Model, Grouping and Bundling, Shared Taxonomy, Resources and Contracts, and Versioning, Compatibility, and Lifecycle to refine the description.

The normative requirements remain in the specification sections and the generated interfaces and schemas.

Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

ORD Roles

The ORD specification consists of several parts. Depending on the role of the adopter, only some parts of the specification are relevant and need to be implemented.

Please note that ORD roles are not exclusive. A system type can implement multiple roles, e.g. an ORD Consumer MAY also be an ORD Provider.

Publish

Provider

Describes an application or service.

ORD Provider APIORD documentsDefinitions

Metadata

Connect

Aggregator

Collects, validates, resolves, and serves metadata.

Effective viewsHosted definitionsDiscovery API · own contract

Discovery API

Use

Consumer

Finds and uses resources across systems.

CatalogsDeveloper toolsAutomation & AI

Arrows show metadata delivery. Roles can overlap; consumers may also read a provider directly.

ORD Provider

An ORD provider is a system instance (of an application or service) that exposes ORD information for self-description. The provider role applies to business applications/services that want to describe themselves (described system instance).

Described System Instance

A described system instance is a system instance that is being described by an ORD provider.

ℹ In theory, it is also possible to describe other system instances "on behalf". In this case, the ORD provider system instance is not necessarily identical to the described system instances (see describedSystemInstance property). For example, an ORD Provider could pre-aggregate information from multiple system instances and then describe them in one place via multiple ORD documents. Whether this is supported, depends on the ORD aggregator.

An ORD provider MUST implement the ORD Provider API, which entails providing an ORD configuration endpoint and ORD document(s). An ORD provider MUST use one of the standardized ORD transport modes for the ORD documents. Depending on the overall architecture, it MUST integrate with specific ORD aggregators.

📖 See also: How To Adopt ORD as a Provider.

Protocols and formats shown are examples; ORD supports more.

ORD Aggregator

An ORD aggregator is a system that collects, aggregates, and proxies the ORD information from multiple ORD providers. It reflects the combined information on the ORD providers that it aggregates. The aggregator itself MAY represent a static perspective or a dynamic perspective, or both.

The ORD information MUST be made available to ORD Consumers through a higher-quality API, for example via an ORD Discovery API that allows for more advanced consumption patterns. Consumers MUST NOT be required to understand how an ORD provider distributes metadata across perspectives. The aggregator MUST expose an effective view by selecting a complete system-instance perspective or by composing the applicable static layers by ORD ID.

An ORD aggregator MUST ensure that information that has visibility of private or internal is not made available to consumers that don't have the corresponding permissions to get such information (e.g. external consumers). If ORD consumers get private or internal information, they inherit the responsibility of protecting it.

There are aggregation rules and validation rules that an ORD aggregator MUST implement and ORD Consumers MAY hold to.

It MUST support all ORD transport modes that are used by the systems it aggregates.

When serving static perspective requests (system-type or system-version), the aggregator MUST follow the static perspective resolution algorithm.

In case of an ORD aggregator that supports the dynamic perspective:

• the aggregator MUST support system-instance-aware information and MAY support further system instance grouping concepts, such as accounts etc.
• If it needs to reflect system-instance-aware information it MUST be system-instance-aware itself.
• In the ORD Discovery API for accessing system-instance perspective information, the aggregator MUST determine whether a system-instance perspective is published for the tenant before filtering for an ORD ID.
  • When a complete system-instance perspective is published, it replaces the effective static view and an omitted resource MUST NOT be inherited from static metadata.
  • If the system-instance perspective omits the requested ORD ID, the resource is not available on that tenant.
  • Only when no system-instance perspective is published may the aggregator fall back to the effective static view.
  • The aggregator performs this resolution so consumers do not have to query and compose perspectives themselves.
• See chapter on perspectives and the perspectives concept page for details.
• It SHOULD support the proposed optimizations for the transport modes, e.g. make use of perspectives (replaces deprecated systemInstanceAware), lastUpdate properties and support the proposed HTTP cache mechanisms. This has the potential to significantly reduce overall TCO.

ORD Consumer

An ORD consumer is an actor or a system that needs to retrieve ORD information.

ORD can either be consumed from a single ORD provider (a system instance) or from an ORD aggregator. The latter is RECOMMENDED, because it provides more information and a higher quality of access.

If the consumer gets the information from an ORD aggregator, it will be provided through an ORD Discovery API.

If the consumer gets the information from an ORD provider, it will be received as an ORD document via one of the implemented transport modes.

An ORD consumer that receives information with a visibility of private or internal inherits the responsibility of the ORD aggregator to protect the information. The ORD consumer MUST ensure that private and internal information is not exposed to consumers without the corresponding permissions. If the ORD consumer only needs public information, it SHOULD only request those from the ORD aggregator in the first place.

ORD Transport Modes

The specification makes a distinction between how ORD information is expressed (say, as an ORD document) and how it is transported.

An ORD Provider MUST implement at least one of the defined transport modes. If the ORD information is system-instance-aware, the implementation of the transport mode MUST support providing it per system instance.

Pull Transport

In pull transport mode, ORD information is made available through a simple REST API that exposes ORD documents via GET endpoints.

This is implemented by providing an ORD Provider API.

01Know the systemBase URL or registered endpoint

02Read ORD config/.well-known/open-resource-discovery

03Fetch documentsPerspectives, resources, taxonomy

04Follow definitionsOpenAPI, AsyncAPI, A2A, and more

Repeatable crawlHigh-level context and detailed contracts stay linked

Pull Transport - Pros

• Simple REST implementation
• ORD Provider does not need to know the ORD Aggregators
• Decentralized approach
• Each system provides the ORD information directly

Pull Transport - Cons

• Periodic pulling leads to many requests (efficiency)
• Periodic pulling may result in slow information updates. For some use cases it might be critical to get updates as soon as possible.
• No direct feedback channel for validation errors from an ORD aggregator

Pull Transport Sequence Diagram

Pull transportHTTP GET · honor advertised access strategiesDefinition files may be hosted elsewhere.

Other Modes of Transport

Other modes of transport have not yet been standardized/specified. They are only listed here to outline potential modes that we anticipate.

Import Transport

Import transport transfers ORD metadata as a set of files into an interested system or tool (offline mode). The file set can be a repository or directory tree, a ZIP archive, or another file bundle containing one or more ORD documents and their referenced metadata files. Document-relative URL references resolve as relative file paths within the transferred file set, following the Relative URL Resolution rules.

• The system instances do not need to know each other or be integrated in any way
• The transferred file set contains the metadata needed for this type of consumption
• All URLs in each ORD document MUST be resolvable, for example as document-relative file paths, through the document root baseUrl, through describedSystemInstance.baseUrl, or as full absolute URLs

Push Transport

🚧 Push transport is not part of the released specification. PR #187 is the current proposal to add it.

The Document can be pushed to the interested ORD aggregator, e.g. via a webhook, a known HTTP POST endpoint, or via file upload.

• Every system instance needs to know where the ORD documents need to be pushed to.
• An ORD aggregator might provide a dedicated HTTP POST endpoint for this.
• Changes can be pushed faster and more efficiently compared to the pull transport.

ORD Parts

The ORD specification consists of several parts. Depending on the role of the adopter, only some parts of the specification are relevant and need to be implemented.

ORD Document

Overview

The ORD document is a standardized, technology agnostic and machine-readable document that provides a high-level description of the resources (such as APIs and Events) of a system instance. The document itself is just a wrapper format to transport the actual ORD information. It is notated and distributed in the JSON format and can be transported in various ways.

ORD Document Content

The ORD document MUST be a valid JSON document with UTF-8 encoding. It MUST NOT exceed 2MB in size to ensure efficient transport and processing. If content exceeds this limit, split the information into multiple ORD documents.

The interfaces are described in ORD document interface, including examples.

An ORD document MUST be compliant with the following JSON Schema definition: Document.schema.json.

Internationalization and localization are not supported natively in ORD documents. It is therefore RECOMMENDED to use American English for human-readable titles and descriptions.

ORD Document Data Model (Simplified)

ContextSystem domain

System InstanceSystem VersionSystem Type

What is exposed or requiredResources & Capabilities

APIsEventsData ProductsCapabilitiesAgentsIntegration Dependencies

How it is understoodTaxonomy & access

Vendor & ProductPackageEntity TypeGroup / Group TypeConsumption Bundle

ORD DocumentStable IDs, lifecycle, visibility, definitions, and relationships connect the three parts.

Considerations on the ORD Content

The ORD documents MUST describe the current state of a concrete, running system instance.

All resources that are described within one document MUST describe the same system instance.

An ORD ID MUST NOT be described more than once within or across ORD documents that belong to the same perspective, including documents exposed by different ORD Providers. See Shared Taxonomy, Resources and Contracts for content reused across perspectives or systems.

The validation rules MUST be considered.

If the resources that are described through ORD are system-instance-aware (they differ between system instances), the ORD document MUST reflect this. In that case, one ORD document MUST be provided for each system instance. Only if the information is system-instance-unaware (the system behaves the same for each instance), a single ORD document can represent the system as a whole.

Differences between system instances are possible, for example, when the system has configuration or extensibility capabilities that result in resources being activated, deactivated, added, or modified. This might happen at config time, deploy time, or even at run-time.

For example, a configuration could explicitly disable an API. In this case, the ORD document for this specific system instance MUST not describe the disabled API. Some systems are even extensible in a way that customers can add new APIs or alter existing APIs at run-time. Those changes MUST be documented via ORD. Please note that some changes only affect the referenced resource definitions and not the ORD document itself. However, the change in the resource definition MUST be indicated through a version increment (see Versioning and Lifecycle).

Considerations on the Granularity of ORD Documents

• MUST be split if multiple system namespaces or even system instances are described. At least one ORD document MUST be created for each, as the ORD document is scoped to describe a specific system type (static) or instance (dynamic).
• MUST be split if different perspectives are described, as one document can only describe one perspective.
• MUST be split when they become too big in size (MUST not exceed 2 MB).
• MAY be split according to lifecycle and ownership concerns (e.g. all customer or partner created resources together).
• MAY be split according to team autonomy boundaries / bounded contexts / domains.
• MAY be split to optimize retrieval and cache handling.

ORD Information Reuse

To avoid repeating too much information, ORD provides some limited means for information reuse on document level and package level.

Which attributes support information reuse and how it works is described in the ORD Document interface documentation and the ORD Aggregator Content Enrichment and Preservation section.

Document Level Inheritance

Some ORD information is described on the document root level and applies to all information that the ORD Document contains. In some cases (like policyLevels), it is also possible to override the values locally.

Package Level Inheritance

Some ORD information is described on Package level and inherited down to all resources that are assigned to it. The information on Package level is merged into resource level, but can be overridden locally at resource level.

Please note that Package level inheritance might not always have the right granularity, as putting resources into Packages can have a different motivation / cut than the reuse. In this case, the information need to be defined on resource level individually, leading to some information duplication. For ORD 2.0 we consider removing Package level inheritance, potentially replacing it with a more flexible approach.

ORD Document Content Extensions

Some properties only have a fixed set of allowed values. In many cases they allow setting this to custom. The actual value is then provided through an accompanying property, such as customType, which has no restrictions (but also no agreed-upon semantics).

Additional information or categorization can be added through the generic Label concept, which is available for most ORD information.

If such custom values or labels are relied upon by more than one application or team, they SHOULD be standardized through ORD. Please create an issue to request this.

Relative URL Resolution

ORD documents may contain both absolute and relative URLs. ORD aggregators MUST resolve all relative URLs to absolute URLs before exposing them to ORD consumers.

URL Reference Types

ORD recognizes three types of URL references:

Pattern	Type	Resolved against
https://example.com/path	Absolute URL	Used as-is — no resolution needed
/path/file.json	Base-URL-relative (leading slash)	The applicable base URL (see below)
./path/file.json, ../path/file.json, path/file.json	Document-relative	The URL/location of the current document

Base-URL-relative URLs (leading slash) are resolved by appending the reference path to the applicable base URL: baseUrl + "/" + ref_path_without_leading_slash. For example, if baseUrl is https://provider.com/api/v1, then /metadata/schema.json resolves to https://provider.com/api/v1/metadata/schema.json.

If no base URL is known through any other means, it is derived from the ORD configuration endpoint URL by stripping the /.well-known/open-resource-discovery suffix — consistent with how the ORD Configuration's implicit baseUrl is defined. For example, if the config endpoint is https://provider.com/api/v1/.well-known/open-resource-discovery, the derived base URL is https://provider.com/api/v1.

Document-relative URLs (with ./, ../, or bare path without leading slash) are resolved per RFC 3986 Section 5 against the URL from which the current document was retrieved. For example, if a document was fetched from https://provider.com/ord/v1/documents/apis.json, then ./schemas.json resolves to https://provider.com/ord/v1/documents/schemas.json. This pattern is particularly useful for static ORD providers serving files from a file system or git repository, where relative references remain valid regardless of where the directory tree is hosted.

Note: Per RFC 3986, path/file.json (no leading slash, no dot prefix) is equivalent to ./path/file.json — both are document-relative.

Base URL for Base-URL-Relative URLs

The base URL used for resolving base-URL-relative URLs (leading slash) depends on what the URL references, because two different systems may be involved:

URL type	Resolved against	Declared via
Metadata files: resourceDefinitions[].url, overlayDefinitions[].url, File.url, APIEventResourceLink.url, DataProductLink.url	Provider base URL	Document root baseUrl
Entry points: entryPoints[]	Described system base URL	describedSystemInstance.baseUrl

This distinction matters when the ORD provider and the described system differ (e.g., a central aggregator describing multiple systems on its behalf). In the common case where the provider is the described system, both base URLs are identical and the distinction has no practical effect.

Provider Base URL (metadata files)

Metadata files such as resource definitions and document links are physically hosted by the ORD provider — the system that serves the ORD document. Their base-URL-relative URLs are resolved against the provider base URL using the following order (applied by ORD aggregators):

1. Document root baseUrl — takes precedence when explicitly set in the document.
2. Fetch context URL (pull scenarios only) — the URL the ORD document was fetched from.
3. describedSystemInstance.baseUrl — backward-compatibility fallback for documents predating version 1.15 that do not set the document root baseUrl. In the common case where provider and described system are the same, this yields the same result.
4. ORD configuration endpoint URL — if the aggregator knows the provider's /.well-known/open-resource-discovery endpoint, the base URL is derived by stripping that suffix. This ensures consistent fallback behavior with how Configuration.baseUrl is implicitly computed when omitted.

Described System Base URL (entry points)

Entry points are runtime endpoints on the described system — the system being documented. Their base-URL-relative URLs are resolved against the described system base URL:

1. Aggregator-authoritative URL — ORD aggregators that hold authoritative knowledge of the described system's base URL (e.g., from landscape configuration or service discovery) MAY prefer that over the document-provided value. This is an aggregator decision, appropriate when the aggregator has more reliable or up-to-date information than the provider.
2. describedSystemInstance.baseUrl — the value declared in the document.

The asymmetry is intentional. Aggregators commonly have landscape authority over the systems they describe (rule 1 above), but not over the system that merely serves ORD documents. For the described system, deferring to the aggregator's landscape knowledge is appropriate; for the provider, the document is the authoritative source, especially in push scenarios where no fetch context exists.

Resolution Examples

Given:

• Document root baseUrl: https://provider.com/api/v1
• describedSystemInstance.baseUrl: https://system.com
• Document fetched from: https://provider.com/api/v1/ord/documents/apis.json

Reference in document	Context	Resolves to
https://cdn.example.com/schema.json	Any	https://cdn.example.com/schema.json
/metadata/schema.json	Metadata file	https://provider.com/api/v1/metadata/schema.json
/v1/orders	Entry point	https://system.com/v1/orders
./related/events.json	Any	https://provider.com/api/v1/ord/documents/related/events.json
../shared/types.json	Any	https://provider.com/api/v1/ord/shared/types.json

ORD Provider API

This section details how an ORD Provider exposes one or multiple ORD documents for the pull transport mode.

The ORD Provider MUST implement a RESTful API that provides an ORD configuration endpoint and at least one ORD document endpoint.

The API contract is defined as an OpenAPI 3 Definition. The definition contains the well-known ORD configuration endpoint and one exemplary document endpoint.

ORD Configuration Endpoint

The ORD configuration endpoint is the single entry point for the discovery.

The motivation behind the ORD configuration endpoint is to:

• Define which version(s) and capabilities of the ORD standard are currently supported by the system instance.
• Define where and how the ORD information can be accessed
  • Which transport mode is available (URLs to ORD document(s) indicate the pull transport mode)
  • Which access strategies are available
• Optionally provide discoverable ORD Overlay files via openResourceDiscoveryV1.overlays (see ORD Overlay)

The idea behind the configuration endpoint is inspired by the well-known URI discovery mechanism.

Some applications on the Web require the discovery of information about an origin [RFC6454] (sometimes called "site-wide metadata") before making a request.

https://datatracker.ietf.org/doc/html/rfc8615#section-1

Provider Implementation

The ORD configuration endpoint MUST be implemented by ORD Providers and be accessible via an HTTP GET request.

The response MUST be a valid UTF-8 encoded JSON document that is returned with the application/json;charset=UTF-8 content type and the HTTP Status Code 200.

• The response MUST not contain any sensitive information or leak tenant-specific information.
• It MUST be compliant with the following JSON Schema definition: Configuration.schema.json.
• Please refer to the interface documentation for more details.

All of the common REST characteristics MUST be met. The rules on ORD Provider Cache Handling apply.

It is RECOMMENDED to make this endpoint public.

It is RECOMMENDED use the fixed Well-Known URI /.well-known/open-resource-discovery (as registered here) that is relative to the system instance's base URL.

Since the ORD config does not contain any tenant-specific information, it is RECOMMENDED to only provide one ORD configuration endpoint for one system deployment (same base URL) of a multi-tenant application.

This assumes that the ORD document URLs in the configuration are not different per tenant and the tenant ID is selected as part of the access strategy. If the application is single-tenant or the tenant ID is part of the base URL (for example in the domain name), each tenant / system instance will have their own ORD config endpoint as a consequence.

If the ORD configuration endpoint is either customized or protected, the information where to find and access the ORD config endpoint MUST be made available to all ORD consumers and aggregators and will be a prerequisite for the ORD discovery. This could be implemented either through explicit solutions like a central system registry or through established conventions.

If the ORD configuration endpoint is customized, the ORD configuration response MUST either use absolute URLs or provide the baseUrl.

ORD Document Endpoint

The ORD document endpoint provides an ORD document via pull transport. An ORD Provider MUST implement one ORD document endpoint for each ORD document it exposes.

Provider Implementation

The content of an ORD document MUST be made available via an HTTP GET request and be returned with the application/json;charset=UTF-8 MIME type and the HTTP Status Code 200.

All of the common REST characteristics MUST be met.

If the ORD document is system-instance-aware (different between system instances), the ORD document endpoint MUST ensure that the response describes the correct/chosen instance specifically. This can be implemented, for example, via authentication (multi tenancy) or by having different URLs per system instance. In this case, the ORD documents MUST be provided and fetched for each system instance. For more details, please see the considerations on the ORD content section.

The rules for ORD Provider Cache Handling apply.

Select Parameter

The ORD Provider API MAY implement an optional ?select HTTP query parameter, that the ORD Aggregator can pass to reduce the result set of the ORD Config and ORD Documents requests / aggregation run.

The availability of this feature MUST be announced through the ORD Configuration, via capabilities.selector set to true.

If supported, the ORD Configuration and the ORD Document endpoint gain an optional query parameter ?select=<ORD ID> where the value MUST be a valid ORD ID. When given, the ORD Provider only returns the requested ORD Resource, but MAY also add related ORD information that need to be updated in the same transaction (the decision is on the provider).

The Aggregator will follow the regular ORD crawling run by invoking the ORD Configuration endpoint and from there the ORD documents and attached resource definitions. There is no reason to pass the parameters to the resource definition requests. The aggregator is allowed to send a select request on the config endpoint, but if the select capability is not advertised MUST NOT proceed with select requests on the ORD documents.

GET http://example.com/.well-known/open-resource-discovery?select=sap.foo:dataProduct:astronomy:v1
Content-Type: application/json

The resulting ORD config MUST only return the ORD document(s) that contain the results from the select query (to avoid unnecessary requests). The aggregator will then request each listed document with the same ?select parameter.

The ORD provider MUST return the following error codes (see error handling):

• 500 Internal Server Error if the given ORD ID format is invalid
• 404 Not Found if the ORD ID is valid but no matching resource exists

GET http://example.com/ord/document-1?select=sap.foo:dataProduct:astronomy:v1
Content-Type: application/json

The response contains the requested resource and MAY include related ORD information that need to be updated together, e.g. when a data product is requested, it could also return its output ports API resources. Returning Tombstones is out of scope.

Resource Definitions

ORD resources like APIs and Events reference resource definitions, which are machine-readable documents that describe the resource's interface in detail. These use industry-standard formats such as OpenAPI, AsyncAPI, JSON Schema, or WSDL.

ORD does not aim to replace these standards. Instead, it discovers and transports them alongside shared metadata. The ORD layer adds common properties (like version, visibility, releaseStatus), taxonomy (via Package, Product, etc.), and relationships between resources.

One resource, one definition set

Every ORD resource that carries machine-readable definitions (API Resource, Event Resource, Capability, Entity Type) describes exactly one logical resource. Its definitions list (resourceDefinitions, or definitions on Capability and Entity Type) is NOT a bundling mechanism: multiple distinct resources (different feature areas, endpoint groups, or lifecycles) MUST each be modelled as their own ORD resource, so ORD-level properties like version, visibility, releaseStatus, ownership, and taxonomy stay meaningful.

Within a single resource, the list MAY still hold several entries, but they must all describe the same underlying resource. Additional entries beyond the default exist to carry complementary artifacts (overlays, AI-enriched variants, agent-security-permissions views, …) and, where supported, are distinguished via the purpose property.

The entry without a purpose is the primary / default definition, and there SHOULD be exactly one per (type, visibility) combination. Consumers that don't explicitly ask for a specific purpose MUST fall back to the default entry with the highest visibility they are entitled to see. Values under the ord: namespace are reserved for the ORD specification; custom purposes MUST use their own namespace prefix.

An ORD resource can also reference an ORD Overlay as an additional resourceDefinitions entry with type ord:overlay:v1. The same overlay files can optionally be discovered independently via the ORD configuration endpoint. For details, see ORD Overlay.

For details on how resource definitions are referenced, see the resourceDefinitions property on API Resource and Event Resource in the interface documentation. When consumed via an ORD aggregator, the aggregator may host the resource definitions for easier access.

Consumer Perspective

An ORD consumer MUST first consult the ORD configuration endpoint. The response will indicate the supported version(s) of ORD, the URLs of the exposed ORD documents, and additional information that has implications for accessing the information. The ORD documents may contain links to metadata definitions and how to access them.

The most important rules are:

• The consumer MUST NOT make any fixed assumptions on the ORD document endpoint paths.
• The consumer MUST download the ORD configuration, ORD documents and the referenced metadata definitions via HTTP GET requests.
• It is RECOMMENDED to add Accept: application/json to all request headers when requesting ORD config and documents.
• The rules for ORD Consumer Cache Handling apply.

Cache Handling

ORD Provider Cache Handling

ORD providers SHOULD use the HTTP caching and conditional request mechanisms defined by RFC 9111 and RFC 9110. They SHOULD provide a Cache-Control header and an HTTP validator such as ETag when caching or revalidation is useful. When ORD metadata may be stored but must be revalidated before reuse, providers SHOULD use Cache-Control: no-cache together with an HTTP validator such as an ETag.

If a response depends on the user, system instance / tenant, or other request context, the provider MUST prevent a shared cache from reusing it in a different context. The provider can prohibit shared storage, for example with Cache-Control: private, or deliberately allow it by following the authenticated-response and Vary requirements of RFC 9111. In the latter case, Vary MUST list every request header that selects the representation. If the selection context cannot be represented completely in the shared cache key, the provider MUST prohibit shared caching for that response. Vary: * indicates that a stored response cannot be reused for a subsequent request.

When an ORD resource or any of its referenced resource definitions changes, either the version or the lastUpdate of the affected resource MUST be updated to let the ORD aggregator know that the resource definitions need to be re-fetched (see Versioning). HTTP validators apply to the complete selected representation and are independent of these ORD-level change signals.

ORD Consumer Cache Handling

An arbitrary ORD consumer MAY implement the following cache handling rules to optimize frequent access. An ORD aggregator SHOULD implement the cache handling rules in order to reduce unnecessary load on the ORD providers.

If a provider supplies HTTP caching metadata or validators, the consumer SHOULD process them according to RFC 9110 and RFC 9111.

When determining whether a resource changed, the aggregator SHOULD compare every available change signal, including both version and lastUpdate. Referenced definition files MUST be fetched or revalidated if they have not been retrieved yet or if either signal changed since the last retrieval. The aggregator MAY skip reprocessing and refetching only when none of the available signals changed, but MAY revalidate a definition independently at any time.

Documents and resources published through a system-instance perspective MUST be fetched and cached separately for each system instance / tenant. Documents and resources from static perspectives SHOULD be fetched once per applicable system type or system version scope, while system-independent information SHOULD be fetched once globally.

For its own metadata cache, an aggregator MUST scope entries by the document or resource identity, the authoritative perspective scope, and every part of the request context that selects the representation. For its HTTP cache, it MUST also honor Vary; a response with Vary: * cannot satisfy a subsequent request.

ORD Aggregation

This section covers the aggregation rules and validations for ORD aggregators.

ORD Consumers that retrieve information from an aggregator MAY rely on the outlined rules.

Aggregation Rules

One of the responsibilities of an ORD aggregator is to combine the ORD information from multiple system instances. When information from many different system instances comes together, some situations may arise that need to be resolved through clearly defined rules.

ORD ID Uniqueness and Aggregation

The document perspective applies to every ORD entry, regardless of whether the entry is an ORD resource or taxonomy. ORD documents belong to the same perspective according to their perspective value and the system type, exact system version, or system instance that they describe.

Within the same perspective, an ORD ID MUST be described at most once across all ORD Documents and ORD Providers. A duplicate is a validation error and MUST NOT be resolved by combining properties or selecting a description based on its resource version, publication time or retrieval time. If the descriptions are equivalent, an aggregator MAY retain one as a recovery step, but it MUST still report the duplicate.

The same ORD ID appearing in different perspectives is not a duplicate. Complete descriptions in different perspectives MAY differ. The aggregator MUST preserve each complete description as part of its perspective and MUST NOT combine properties from different perspectives. For system-scoped perspectives, the selection of an effective description follows the perspective resolution rules and replaces complete descriptions without merging their properties. This specification does not mandate a physical storage model. An aggregator MAY normalize information internally only if it preserves every perspective and complete description. For modeling taxonomy or resources that are shared or reused across systems, see Shared Taxonomy, Resources and Contracts.

Content Enrichment and Preservation

Some ORD information may need to be added, modified, inherited or preserved by the ORD aggregator.

An ORD aggregator MUST implement an internal data model/persistence where the additional information can be stored. It MUST apply the outlined inheritance rules internally and expose the ORD information to ORD Consumers with inheritance already applied. This makes it easier for ORD Consumers, as they don't need to understand and apply the outlined rules.

The following rules need to be implemented by ORD aggregators:

• If the aggregator detects a change in a resource (compared to previous state), but the lastUpdate isn't provided or hasn't changed since, the aggregator MUST update the lastUpdate timestamp on aggregator side.
  • This ensures that consumers can rely on lastUpdate to be always available and to understand if a change happened, even if the ORD Provider did not update it at the source
  • Ideally this situation doesn't happen and the ORD Providers update lastUpdate. Then the date can also better reflect the time when the change happened, not when it was detected.
• The aggregator MUST apply all defined inheritances from root document properties to all the ORD information that it contains.
  • policyLevels MUST be inherited to the resource / Package level, with the latter taking precedence.
• The aggregator MUST apply all defined inheritances from Package properties to all the ORD resources that it contains.
  • vendor, partOfProducts, tags, countries, industry, and lineOfBusiness MUST be merged without duplicates.
  • labels MUST be merged without duplicated values.
    • Values of the same label key will be merged.
    • Duplicate values of the same label key will be removed.
• The aggregator MUST rewrite all URLs for hosted resource definitions to point to their own hosted URLs.
• The aggregator MUST convert all relative URLs to absolute URLs. See Relative URL Resolution for the full resolution rules, including the ordering for provider base URL and described system base URL.
• The information on the described system instance SHOULD be added if it is missing.
  • If system instance information is missing, the aggregator SHOULD obtain and enrich the ORD information, for example, via service discovery or trust context.
  • If the ORD aggregator has additional information on a system instance that is not standardized through the ORD interfaces, they MAY be added and exposed through the ORD Discovery API.
• The aggregator MAY keep a history of previous versions (including minor and patch changes) of published resources.

Removal of Resources/Information

The removal of resources is indicated through setting a Tombstone. The ORD Aggregator MUST remove unpublished information that has been tombstoned within a grace period of 31 days.

Hosting Resource Definitions

The ORD aggregator MUST host all files that have been referenced in the ORD resources, most notably the resource definitions. The files MUST be stored, hosted, and made available by the ORD aggregator system itself. The URLs to the hosted files MUST be rewritten accordingly in the ORD Discovery API responses. The aggregator MUST implement caching and error handling according to the common REST characteristics.

The hosting ensures that ORD consumers can retrieve the referenced files directly from the aggregator itself. They don't need to fetch them from the ORD Providers individually. This eliminates the need for authentication and authorization against many different systems. It also ensures that the files have the same high SLA availability that the ORD aggregator has.

Validation Rules

The ORD spec aims to move as many validation rules to the ORD document itself. The aggregator MUST validate the retrieved ORD documents accordingly.

However, there are also validations that can only be done by an aggregator, such as checks for consistency across multiple systems or within a concrete system landscape.

The following validation rules apply specifically for ORD aggregators:

• References SHOULD be checked to not be broken, but MAY be temporally allowed to be "dangling". This happens if the ORD ID points to an ORD resource or ORD taxonomy that is not (yet) known to the ORD aggregator.
  • As resources can be added or removed later, this SHOULD be continually checked. For example, one reference could point to an ORD resource that has been removed lately. Now the reference that was valid when it was created, becomes invalid and the relevant ORD Provider(s) SHOULD be notified.
• Aggregators MUST enforce ORD ID uniqueness within each perspective. During a migration, duplicates MAY be accepted temporarily but MUST still be reported as validation errors.

ORD Discovery API

The ORD Discovery API is a higher quality API, provided by an ORD aggregator that is optimized for easy consumption of ORD information. It MAY support advanced features like pagination, filtering, search, expansion, etc. Such features are deliberately missing at the ORD Provider API to keep the provider interface simple.

The ORD Discovery API MUST be implemented by the ORD aggregator role. It is the RECOMMENDED interface for ORD consumers to retrieve ORD information.

An ORD aggregator MAY expose more information than it received from the ORD providers, for example additional information it acquired through service discovery or other metadata sources.

As long as there is no standardized ORD Discovery API contract, each ORD aggregator MAY implement their own API contract. Ideally this contract is based on the ORD Provider API interfaces with only minor differences and additions.

Perspectives

With ORD it's possible to describe a system both from a static perspective and a dynamic perspective. For a definition, please refer to the terminology section.

⏩ This concept requires some background to understand properly. It is explained in more detail in the perspectives concept page.

This concept deprecates the use of systemInstanceAware

System-independentShared taxonomyProducts · Vendors · global Entity Types and Groups

Static

System type / version

Reusable design-time baseline.

offered APIsversionsdesign-time contracts

Dynamic

System instance

Complete view of one running tenant.

active APIsextensionsendpoints

Aggregator responsibilityResolve the effective view for consumers

There is a perspective attribute, which allows setting the following values:

• system-type: The static perspective that is version independent ("perspective": "system-type"). This perspective describes the current, version-agnostic state of a system type. Use this when the system is not versioned (continuous delivery) or resources are not tied to a specific system version. Exclusively publishing a system-type perspective is adequate when treating every system instance as running the latest effective static view.
• system-version: The static perspective on the granularity of system versions ("perspective": "system-version") for system-instance-unaware information (usually known at deploy-time).
• system-instance: The dynamic perspective on the granularity of system-instances ("perspective": "system-instance"), for system-instance-aware information (only known at run-time).
• system-independent: Describes content that is independent of system versions or system instances and can be shared across multiple systems.

Correct Use of Perspectives

• Static ORD documents (system-type and system-version) MUST NOT contain tenant context or tenant-specific customizations.
• An ORD provider that describes a system SHOULD publish static metadata using system-type, system-version, or both.
• Providers SHOULD publish version-independent metadata through system-type and metadata that differs between versions through system-version.
• Providers MUST use distinct system-version values when multiple versions of the same application are deployed at the same time in one environment tier, such as production.
• A continuously delivered system MAY publish all static metadata through system-type when treating every system instance as running the latest effective static view is sufficient.
• Alternatively, a continuously delivered system MAY publish all static metadata through system-version with a fixed describedSystemVersion.version. When using the fixed-version approach, the version MUST remain unchanged so each release replaces the previously published system-version perspective.
• A system type MAY publish both static perspectives.
• Each ORD ID published in a static perspective MUST have a complete representation.
• The effective static view MUST look up an ORD ID in the applicable system-version layer first and then in system-type. If both layers contain the ORD ID, the complete system-version representation takes precedence and its properties MUST NOT be merged with the system-type representation.
• Systems, which have dynamic metadata MUST use a complete system-instance perspective.
  • They SHOULD also provide at least one applicable static perspective.
  • The static and dynamic perspectives MAY be provided through different technical implementations, for example a static ORD Provider or publishing pipeline for the static perspective and an application-native ORD Provider API for the system-instance perspective. In this case, both perspectives MUST use the same ORD IDs for the same logical resources, and any differences MUST reflect perspective-specific state.
• Whether a complete system-instance perspective is published MUST be determined independently for each tenant.
• A published system-instance perspective fully describes that tenant and MUST NOT inherit resources from static perspectives. Only when no system-instance perspective is published may an aggregator fall back to the effective static view.
• Content that is independent of systems (like Taxonomies, Products, Vendors) SHOULD use the system-independent perspective. A system-independent document MUST NOT contain system or tenant context or system-specific or tenant-specific customizations. It is outside the system-scoped fallback chain.

For a static request, an aggregator MUST first look up the ORD ID in the requested system-version, or in the greatest published stable system-version when no version was requested. If a specifically requested system-version perspective has not been published, the aggregator MUST report that the requested system version does not exist. It MUST NOT continue to system-type or substitute another system version in this case. If the requested version exists but the ORD ID is absent from its layer, the aggregator MUST look it up in system-type. When no version was requested and no stable system-version layer has been published, the aggregator MUST also look up the ORD ID in system-type. The aggregator MUST select one complete representation and MUST NOT merge properties across the two layers. Automatic latest selection MUST exclude Semantic Versioning prereleases. A prerelease system version may be selected for an exact-version lookup, including when it is the known version of a tenant. When resolving a static fallback for a tenant with a known system version, the aggregator MUST select that exact system-version perspective. If it has not been published, the aggregator MUST report that the system version does not exist and MUST NOT continue to system-type or substitute another system version.

⏩ For how aggregators resolve static perspective requests (e.g. which data to return when no version is specified), see the static perspective resolution algorithm on the perspectives concept page.

ID Concepts

ORD uses namespaces, ORD IDs, Correlation IDs, Concept IDs, and Specification IDs for distinct identity and reference purposes. The complete normative construction and usage rules are defined on the Identifiers detail page.

Namespaces

Namespaces establish collision-free ownership boundaries for ORD information. See the complete namespace rules.

ORD ID

An ORD ID is the stable identifier of an ORD resource or taxonomy item. See the complete ORD ID rules.

Correlation ID

A Correlation ID relates ORD information to stable identifiers managed outside ORD. See the complete Correlation ID rules.

Concept ID

A Concept ID identifies a namespaced concept used by extensible ORD fields. See the complete Concept ID rules.

Specification ID

A Specification ID identifies a versioned standard, procedure, or implementation strategy. See the complete Specification ID rules.

Version and Lifecycle

ORD resources carry a version, an ORD ID major-version fragment, and lifecycle information that communicate different aspects of resource evolution. The complete normative rules and practical guidance are defined on the Versioning and Lifecycle detail page.

Common REST Characteristics

Error Handling

If there are internal implementation errors, the REST endpoint MUST return a 500 (Server Error) response as defined in the OpenAPI 3 definition. Additional error details MAY be added.

If a resource has been requested that does not exist or is not implemented, the REST endpoint MUST return a 404 (Not Found) response as defined in the OpenAPI 3 definition. Additional error details MAY be added.

Authentication & Authorization

The ORD document endpoints MAY implement authentication and authorization to protect the ORD information and the resource definitions it references. In case of system-instance-aware information, authentication MAY be a technical necessity.

If authentication/authorization are applied, the endpoints MUST return the corresponding HTTP status codes 401 (Unauthorized) and 403 (Forbidden) as defined in the OpenAPI 3 definition.

The specification makes no hard assumptions about the authorization and authentication mechanism. The strategy/access methodology that was chosen to retrieve the ORD information and the referenced resource definition files is described via Access Strategies (accessStrategies).

Terminology

This specification defines and uses the following terms (for the ORD context):

ORD

ORD is the abbreviation for Open Resource Discovery. It refers to the standard (as defined by the specification) as a whole.

ORD Information

ORD information is the sum of all information that can be expressed through ORD.

ORD information can have different perspectives:

Static Perspective

The static perspective describes how a system generically looks like ("baseline"), without any tenant-specific customizations but with all pre-delivered capabilities fully described. Static ORD documents MUST NOT contain tenant context or tenant-specific customizations. Such static perspectives can be described at design-time or deploy-time. They can be used to describe a system type and system version. This is useful, e.g. to describe potential resources users / customers could use before they actually provision systems.

• This can be explicitly set with perspective: system-type (version independent) or system-version (for specific versions)
• This is also referred to as system-instance-unaware information. They are identical across all system instance of the described system type (and system version when using system-version perspective).

system-instance-unaware

system-instance-unaware information is identical across all system instances of the described system type and system version.

Dynamic Perspective

The dynamic perspective describes a system instance at run-time and can therefore reflect how it is currently configured, customized or extended. This is also referred to as system-instance-aware.

• This can be explicitly set with perspective: system-instance
• This is also referred to as system-instance-aware information. system-instance-aware information is allowed to be different between system instances of the same system type.

system-instance-aware

system-instance-aware information is allowed to be different between system instances of the same system type.

ORD Resource

ORD information can be categorized into resources and taxonomies:

ORD resource information describes application and service resources. Resources are consumable capabilities of the system (e.g. API resources, Event resources, etc.). ORD resource information MAY be system-instance-aware, depending on the implementation of the system type.

ORD Taxonomy

ORD taxonomy is used to categorize and structure resources. Taxonomies span across products and system types.

• Some taxonomies are implemented as dedicated Entities (e.g. Package, Product, Group and GroupType) that can express additional information. They are defined by the ORD providers in a decentralized manner.
• Other taxonomies are provided via fixed enums (code lists) and are defined as part of ORD itself, e.g. tags.
• Taxonomies are not a consumer contract and therefore do not offer the same stability guarantees and lifecycle management as ORD resources.

ORD Behavior

ORD behavior standardizes how ORD information is discovered, transported, and aggregated.

System

A system is sometimes used as a generic, imprecise term when no further distinctions are necessary. In most places, the specification uses more precise terms like system type, system deployment, system version, and system instance.

System Type

A system type is the abstract type of an application or service from an operational perspective. It is also known as system role (SAP CLD). Within the specification it is also referred to as application and service for better readability.

Since system type is an abstract concept, it is not concretely addressable. A system deployment of a specific system version and potentially a system instance needs to be created to have a concrete, addressable system.

Please note that a system type is similar, but not necessarily identical to a product. System type is a technical concept, while product is a term for external communication and sales.

System Deployment

A system deployment is a concrete, addressable deployment of a system type running a specific system version.

A single system type can have multiple deployments, for example one per region or data center. Each deployment has at least one base URL and serves as a container/host for system instances (tenants). If the system type supports tenant isolation (multi-tenancy), a system deployment may host multiple system instances.

System Version

A system version is a particular software version of a system type. It states the design-time version or release of a system and provides versioning for operational purposes. A system deployment always runs a specific system version. All system instances of the same system version could have the same static metadata description.

System Instance

A system instance is a running, isolated instance of a system type, running in a system deployment of a particular system version. It always refers to the most specific instance from a customer, account, and data isolation perspective.

If the system type offers tenant isolation (multi-tenancy), system instance refers to a tenant. If there is no tenant isolation, there are two options: Either the isolation is achieved by having a dedicated system deployment per tenant or system isolation does not matter. In those cases, system instance equals the system deployment.

The term is also known as System (simplified public SAP communication). For internal SAP communication it is referred to as tenant (SAP CLD) if multi-tenancy is supported or system (SAP CLD) if not.

A system instance can act as an ORD Provider.

System Landscape

A system landscape is a set of system instances that are explicitly combined together, for example via a shared zone of trust/connectivity, an account or a namespace concept.

Resource

A resource is provided by or for a system instance for outside consumption and/or communication.

Machine-Readable Resource

A machine-readable resource is a resource that can be used for machine consumption and communication. For example, APIs and events. They are usually described through a resource definition format.

Human-Consumption Resource

A human-consumption resource is a resource that is meant for human consumption, for example documentation.

Resource Definition

A resource definition is a machine-readable, structured document defining the inputs and outputs of a machine-readable resource in a standardized format. It is primarily designed for automated processing, not human consumption. See also definition by the W3 WebAPI Discovery Community Group.

Product

A product is understood as a software product: A non-versioned, high-level entity for structuring the software portfolio from a software logistics perspective. While system type addresses the technical perspective, product is the term to use for customer-facing communication.

Base URL

A base URL is the consistent part of a system deployment or system instance URL. From ORD perspective this is the base URL where the discovery starts and where the ORD config endpoint location is relative to. In most cases the base URL consists of the URL protocol, domain name and (if necessary) the port, for example https://example.com. In rare cases, a relative path (e.g. including a tenant ID) might be included, for example https://example.com/tenantA/.

In ORD, two base URLs can be involved in a single document:

• Provider base URL: the base URL of the system that serves the ORD document and hosts metadata files (e.g., resource definition files). Declared via the document root baseUrl property.
• Described system base URL: the base URL of the system being described (its entry points). Declared via describedSystemInstance.baseUrl.

In the common case where the ORD provider and the described system are the same, both values are identical. See Relative URL Resolution for how these are used to resolve relative URLs.