Skip to main content

ORD Configuration

How to read this documentation

Technical information

Schema Definitions

ORD Configuration

The ORD configuration response will indicate that ORD is available for the given host and how to proceed with the discovery.

Most notably, the ORD configuration will tell an ORD consumer which ORD documents are available and where/how they can be accessed.

The configuration endpoint is a Well-Known URI discovery mechanism.

Type: Object($schema, baseUrl, openResourceDiscoveryV1)

PropertyTypeDescription
$schema
OPTIONAL
string
Optional URL to the ORD Configuration schema (defined as JSON Schema).
If given, this enables code intelligence and validation in supported editors (like VSCode) and tools.

JSON Schema Format: uri-reference
Allowed Values (extensible):
  • Any string of format uri-reference
  • "https://open-resource-discovery.github.io/specification/spec-v1/interfaces/Configuration.schema.json#"
baseUrl
OPTIONAL
string
Optional base URL that can be used to resolve the relative URLs to the ORD Documents.

The baseUrl MUST not contain a leading slash.

If you do not provide this property, the base URL is assumed to be the URL of the config endpoint without /.well-known/open-resource-discovery suffix.
This implies that either a baseUrl or only absolute URLs MUST be provided when no standardized well-known URI is used.
If both a baseUrl and a well-known URI is provided, the explicit baseUrl takes precedence.

JSON Schema Format: uri
Regex Pattern: ^http[s]?:\/\/[^:\/\s]+\.[^:\/\s\.]+(:\d+)?(\/[a-zA-Z0-9-\._~]+)*$
Example Values:
  • "https://example-sap-system.com"
  • "https://sub.foo.bar.com"
  • "https://sub.foo.bar.com/api/v1"
openResourceDiscoveryV1
MANDATORY

ORD V1 Support

The existence of this version indicates that Open Resource Discovery is supported in Version 1.x

Type: Object(documents, capabilities)

PropertyTypeDescription
documents
OPTIONAL
List of all ORD documents that can be retrieved.

While it is possible to describe everything in one big ORD document, for bigger services/use cases it might be preferable to split the information into multiple documents.

For more details how to implement this correctly, please refer to the ORD configuration endpoint section and the considerations on the granularity of ORD documents.
capabilities
OPTIONAL

ORD V1 Document Description

Describes an ORD Document that is available for pull transport consumption.

Type: Object(url, perspective, systemInstanceAware, accessStrategies)

PropertyTypeDescription
url
MANDATORY
string
URL or relative URL to the ORD document (provided by an ORD document endpoint).

It is RECOMMENDED to provide a relative URL (to baseUrl).
If a baseUrl is given, the relative URLs will be resolved with it.

If the URL is not relative to the system providing this information or no well-known URI is used,
either the baseUrl or a full URL to the document MUST be provided.

JSON Schema Format: uri-reference
Example Values:
  • "/open-resource-discovery/v1/documents/example1"
  • "../../documents/example1"
  • "https://example.com/open-resource-discovery/v1/documents/example1"
perspective
OPTIONAL BETA
string
BETA BETA With ORD it's possible to describe a system from a static or a dynamic perspective (for more details, follow the link).

It is strongly RECOMMENDED to mark all static ORD documents with perspective system-version.

It is RECOMMENDED to describe dynamic metadata in both static system-version perspective and additionally describe the system-instance perspective where it diverges from the static metadata.

If not provided, this defaults to system-instance, which is the most precise description but also the most costly to replicate.

Please read the article on perspectives for more explanations.

Default Value: "system-instance"
Allowed Values:
  • "system-version": Describes the static system-version perspective, usually known at deploy-time.

    If chosen, describedSystemVersion.version MUST be provided, too.

    This perspective describes how a system of a particular type and version generally look like.
    The latest system-version MAY also be interpreted as the system-type perspective.

  • "system-instance": Describes the complete dynamic system-instance (tenant) perspective as known at run-time.
    This allows to also reflect tenant specific extensions, customizations and runtime configuration.

    If provided, it will completely override the static system-version perspective when metadata about system instances is requested.

  • "system-independent": Describes content that is independent of system-versions or system-instances.
    This content is always static and has independent visibility and lifecycle from the systems in a particular landscape.
    The "system-independent" content MUST NOT be overridden via system-version or system-instance perspective metadata.

    Examples are: Vendors, products, globally aligned entity types, groups and group types (taxonomy), which are usually shared by multiple systems.


Introduced in Version: 1.12.0
Example Values:
  • "system-instance"
systemInstanceAware
OPTIONAL
DEPRECATED
boolean
DEPRECATED: Please use perspectives instead and split content of different perspectives into different ORD documents.
DEPRECATED: Please use perspectives instead and split content of different perspectives into different ORD documents.
Whether the information in the ORD document is system instance aware.

This is the case when the provided ORD document potentially differs between system instances.
Please note that if a system does not support multi-tenancy, most likely each system instance has its own
URL and different system instances could even be deployed in a different state (version).
If those conditions apply, systemInstanceAware MUST be set to true.

An ORD aggregator that represents a system instance aware perspective MUST fetch a system instance aware ORD document,
not just once per system type but once per system instance.

Please note that you can define system instance awareness also on the level of an ORD resource.
It is even possible and valid to have an ORD document that is NOT system instance aware to contain resources that are.
This can be the case because the resource is described in separate resource definition formats which would change,
while the ORD document itself would not change (the links to the resource definition files stay the same).

If some ORD information is system instance aware and some is not,
we RECOMMEND to split the information into separate documents and mark their system instance awareness accordingly.

Deprecated in Version: 1.12.0
Example Values:
  • true
accessStrategies
MANDATORY
List of supported access strategies for retrieving the metadata from the ORD provider.

An ORD Consumer/ORD Aggregator MAY freely choose any of the listed strategies.

Array Constraint: MUST have at least 1 items

ORD V1 Capabilities

List of capabilities that are supported by the ORD provider.

Type: Object(selector)

PropertyTypeDescription
selector
OPTIONAL
boolean
Whether the ORD provider supports the optional select parameter for retrieving the ORD config and ORD documents.

Access Strategy

Defines the access strategy for accessing the ORD documents from the ORD provider.

Type: Object(type, customType, customDescription)

PropertyTypeDescription
type
MANDATORY
string
Defines the authentication/authorization strategy through which the referenced ORD Documents can be accessed.


Example Values:
  • "open"
customType
OPTIONAL
string
If the fixed type enum values need to be extended, an arbitrary customType can be provided.

MUST be a valid Specification ID.

MUST only be provided if type is set to custom.

Regex Pattern: ^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\-]+):v([0-9]+)$
Maximum Length: 255
Example Values:
  • "sap.xref:open-local-tenant-id:v1"
customDescription
OPTIONAL
string
Human-readable description about how the access is set up, notated in CommonMark (Markdown).

MUST only be provided if type is set to custom.

Minimum Length: 1
Example Values:
  • "To set up the access to OData APIs, please refer to the [SAP Cloud for Customer OData API](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US) help pages.\""

Access Strategy Examples

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