{
  "description": "The ORD configuration response will indicate that ORD is available for the given host and how to proceed with the discovery.\n\nMost notably, the ORD configuration will tell an ORD consumer which ORD documents are available and where/how they can be accessed.\n\nThe configuration endpoint is a [Well-Known URI](https://tools.ietf.org/html/rfc8615#section-3) discovery mechanism.\n\nThis JSON Schema describes the [ORD configuration interface](https://open-resource-discovery.org/spec-v1/interfaces/Configuration) of the [ORD specification](https://open-resource-discovery.org/).",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://open-resource-discovery.org/spec-v1/interfaces/Configuration.schema.json#",
  "title": "Ord Configuration",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri-reference",
      "description": "Optional URL to the ORD Configuration schema (defined as JSON Schema).\nIf given, this enables code intelligence and validation in supported editors (like VSCode) and tools.",
      "anyOf": [
        {
          "type": "string",
          "format": "uri-reference"
        },
        {
          "const": "https://open-resource-discovery.org/spec-v1/interfaces/Configuration.schema.json#"
        }
      ]
    },
    "baseUrl": {
      "type": "string",
      "format": "uri",
      "description": "Optional [base URL](../index.md#base-url) that can be used to resolve the relative URLs to the ORD Documents.\n\nThe `baseUrl` MUST NOT contain a trailing slash.\n\nIf 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.\nThis implies that either a `baseUrl` or only absolute URLs MUST be provided when no standardized well-known URI is used.\nIf both a `baseUrl` and a well-known URI is provided, the explicit `baseUrl` takes precedence.",
      "pattern": "^http[s]?:\\/\\/[^:\\/\\s]+\\.[^:\\/\\s\\.]+(:\\d+)?(\\/[a-zA-Z0-9-\\._~]+)*$",
      "examples": [
        "https://example-sap-system.com",
        "https://sub.foo.bar.com",
        "https://sub.foo.bar.com/api/v1"
      ]
    },
    "openResourceDiscoveryV1": {
      "$ref": "#/definitions/OpenResourceDiscoveryV1"
    }
  },
  "additionalProperties": false,
  "required": [
    "openResourceDiscoveryV1"
  ],
  "definitions": {
    "OpenResourceDiscoveryV1": {
      "type": "object",
      "title": "Ord V1 Support",
      "description": "The existence of this version indicates that Open Resource Discovery is supported in Version 1.x",
      "x-ums-type": "ignore",
      "properties": {
        "documents": {
          "type": "array",
          "description": "List of all ORD documents that can be retrieved.\n\nWhile 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.\n\nFor more details how to implement this correctly, please refer to the [ORD configuration endpoint](../index.md#ord-configuration-endpoint) section and the [considerations on the granularity of ORD documents](../index.md#considerations-on-the-granularity-of-ord-documents).",
          "items": {
            "$ref": "#/definitions/V1DocumentDescription"
          }
        },
        "capabilities": {
          "$ref": "#/definitions/V1Capabilities"
        }
      },
      "additionalProperties": false
    },
    "V1DocumentDescription": {
      "type": "object",
      "title": "Ord V1 Document Description",
      "description": "Describes an [ORD Document](../index.md#ord-document) that is available for pull transport consumption.",
      "x-ums-type": "ignore",
      "properties": {
        "url": {
          "type": "string",
          "format": "uri-reference",
          "description": "URL or relative URL to the ORD document (provided by an ORD document endpoint).\n\nIt is RECOMMENDED to provide a relative URL (to `baseUrl`).\nIf a `baseUrl` is given, the relative URLs will be resolved with it.\n\nIf the URL is not relative to the system providing this information or no well-known URI is used,\neither the baseUrl or a full URL to the document MUST be provided.",
          "examples": [
            "/open-resource-discovery/v1/documents/example1",
            "../../documents/example1",
            "https://example.com/open-resource-discovery/v1/documents/example1"
          ]
        },
        "perspective": {
          "type": "string",
          "x-introduced-in-version": "1.12.0",
          "x-feature-status": "beta",
          "description": "With ORD it's possible to describe a system from a static or a dynamic [perspective](../index.md#perspectives) (for more details, follow the link).\n\nAn ORD provider that describes a system SHOULD publish static metadata using `system-type`, `system-version`, or both.\nStatic ORD documents MUST NOT contain tenant context or tenant-specific customizations.\nProviders SHOULD publish version-independent metadata through `system-type` and metadata that differs between versions through `system-version`.\nDistinct `system-version` values MUST be used when multiple versions of the same application are deployed at the same time in one environment tier, such as production.\nA continuously delivered system MAY instead publish all static metadata through `system-type` or through `system-version` with a fixed `describedSystemVersion.version`.\nWhen using the fixed-version approach, the version MUST remain unchanged so each release replaces the previously published `system-version` perspective.\nEach ORD ID published in a static perspective MUST have a complete representation.\nThe effective static view looks up an ORD ID in the applicable `system-version` layer first and then in `system-type`.\nIf both contain the ORD ID, the complete `system-version` representation takes precedence and properties MUST NOT be merged across the layers.\n\nSystems with dynamic metadata MUST be described in a complete system-instance perspective and SHOULD additionally be described in at least one static perspective.\n\nIf not provided, this defaults to `system-instance`, which is the most precise description but also the most costly to replicate.\n\nPlease read the [article on perspectives](../concepts/perspectives) for more explanations.",
          "oneOf": [
            {
              "const": "system-type",
              "description": "Describes a static [system-type](../index.md#system-type) perspective, which is version independent.\n\nIf a system is not versioned (continuous delivery) or resources are not tied to a system version, the system-type perspective\nimplies that the information applies, no matter which system version or instance."
            },
            {
              "const": "system-version",
              "description": "Describes the static [system-version](../index.md#system-version) perspective, usually known at deploy-time.\n\nIf chosen, `describedSystemVersion`.`version` MUST be provided, too.\n\nThis perspective describes how a system of a particular type and version generally look like.\nWhen no specific version is requested, the greatest published stable system-version MUST be selected (see [static perspective resolution](../concepts/perspectives#static-perspective-resolution)).\nThe selected system-version is the first lookup layer.\nIf it omits an ORD ID, the version-independent `system-type` layer MUST be looked up next.\nIf both contain the ORD ID, the complete system-version representation takes precedence without property merging.\nAutomatic latest selection MUST exclude Semantic Versioning prereleases, which may still be selected for an exact-version lookup, including when it is the known version of a tenant.\nProviders MUST NOT publish multiple system-version perspectives whose versions have equal Semantic Versioning precedence and differ only in build metadata."
            },
            {
              "const": "system-instance",
              "description": "Describes the complete dynamic [system-instance](../index.md#system-instance) (tenant) perspective as known at run-time.\nThis allows to also reflect tenant specific extensions, customizations and runtime configuration.\n\nAll documents published for one tenant MUST collectively form that tenant's complete `system-instance` perspective.\nIf published for a tenant, it completely replaces the effective static view when metadata about that system instance is requested.\nWhether a complete valid perspective is published MUST be determined independently for each tenant.\nA resource omitted from the complete `system-instance` perspective MUST NOT be inherited from a static perspective."
            },
            {
              "const": "system-independent",
              "description": "Describes content that is independent of [system-versions](../index.md#system-version) or [system-instances](../index.md#system-instance).\nThis content is always static and has independent visibility and lifecycle from the systems in a particular landscape.\nIt MUST NOT contain system or tenant context or system-specific or tenant-specific customizations.\nThe \"system-independent\" content MUST NOT be overridden via system-version or system-instance perspective metadata.\n\nExamples are: Vendors, products, globally aligned entity types, groups and group types (taxonomy), which are usually shared by multiple systems.\nFor the distinction between system-independent content and system-scoped shared publications, see [Shared Taxonomy, Resources and Contracts](../concepts/shared-resources)."
            }
          ],
          "default": "system-instance",
          "examples": [
            "system-instance"
          ]
        },
        "systemInstanceAware": {
          "type": "boolean",
          "description": "Whether the information in the ORD document is **system-instance-aware**.\nThis is the case when the provided ORD document potentially differs between **system instances** (e.g. due to multi-tenancy, configuration or extensibility).\n\nIf a document is system-instance-aware, an ORD aggregator MUST fetch it for _each_ **system instance** (tenant), not just once per system type.\n\nThis concept is now **deprecated** in favor of the more explicit `perspective` attribute.\nIt is strongly RECOMMENDED to split metadata into separate documents for the different perspectives (static vs. dynamic).\n\nFor a detailed explanation, see [perspectives concept page](../concepts/perspectives.md) or the [specification section](../index.md#perspectives).",
          "default": false,
          "x-deprecated-in-version": "1.12.0",
          "x-deprecation-text": "Please use `perspective` instead and split content of different perspectives into different ORD documents.",
          "examples": [
            true
          ]
        },
        "accessStrategies": {
          "type": "array",
          "description": "List of supported access strategies for retrieving the metadata from the ORD provider.\n\nAn ORD Consumer/ORD Aggregator MAY freely choose any of the listed strategies.",
          "items": {
            "$ref": "#/definitions/AccessStrategy"
          },
          "minItems": 1
        }
      },
      "additionalProperties": false,
      "required": [
        "url",
        "accessStrategies"
      ]
    },
    "V1Capabilities": {
      "type": "object",
      "title": "Ord V1 Capabilities",
      "description": "List of capabilities that are supported by the ORD provider.",
      "x-ums-type": "ignore",
      "properties": {
        "selector": {
          "type": "boolean",
          "default": false,
          "description": "Whether the ORD provider supports the optional `select` parameter ([select parameter](../index.md#select-parameter)) for retrieving the ORD config and ORD documents."
        }
      }
    },
    "AccessStrategy": {
      "type": "object",
      "title": "Ord V1 Document Access Strategy",
      "description": "Defines the [access strategy](../../spec-extensions/access-strategies/) for accessing the ORD documents from the ORD provider.",
      "x-ums-type": "ignore",
      "properties": {
        "type": {
          "type": "string",
          "description": "Defines the authentication/authorization strategy through which the referenced ORD Documents can be accessed.",
          "anyOf": [
            {
              "type": "string",
              "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
              "description": "Any valid [Specification ID](../index.md#specification-id).\nIf chosen, `customDescription` SHOULD be provided."
            },
            {
              "const": "open",
              "description": "The resource definitions are openly accessible and not protected via authentication or authorization.\nPlease find a more detailed documentation [here](../../spec-extensions/access-strategies/open)."
            },
            {
              "const": "basic-auth",
              "description": "The resource definitions are protected via generic basic auth.\nPlease find a more detailed documentation [here](../../spec-extensions/access-strategies/basic-auth).",
              "x-introduced-in-version": "1.12.1"
            },
            {
              "const": "custom",
              "description": "If chosen, `customType` MUST be provided.\nIf chosen, `customDescription` SHOULD be provided."
            }
          ],
          "examples": [
            "open"
          ]
        },
        "customType": {
          "type": "string",
          "description": "If the fixed `type` enum values need to be extended, an arbitrary `customType` can be provided.\n\nMUST be a valid [Specification ID](../index.md#specification-id).\n\nMUST only be provided if `type` is set to `custom`.",
          "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):v([0-9]+)$",
          "maxLength": 255,
          "examples": [
            "sap.xref:open-local-tenant-id:v1"
          ]
        },
        "customDescription": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable description about how the access is set up, notated in [CommonMark](https://spec.commonmark.org/) (Markdown).\n\nMUST only be provided if `type` is set to `custom`.",
          "examples": [
            "To set up the access to OData APIs, please refer to the [SAP Cloud for Customer OData API](https://help.sap.com/viewer/1364b70b9cbb417ea5e2d80e966d4f49/CLOUD/en-US) help pages."
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "examples": [
        {
          "type": "open"
        },
        {
          "type": "custom",
          "customType": "sap.xref:open-local-tenant-id:v1",
          "customDescription": "Custom description how to use custom access strategy"
        }
      ]
    }
  }
}