{
  "description": "⚠️ ALPHA: This specification is in alpha and subject to change.\n\nThe ORD Overlay is an optional ORD model extension that allows patching referenced resource definition files\n(e.g. OpenAPI, AsyncAPI, OData CSDL, MCP/A2A Agent Cards) without modifying the original source files.\n\nOverlays use concept-level [selectors](#overlay-selector) that are independent of the target format's\ninternal structure, making them resilient to format changes.\nA `jsonPath` selector is available as a generic fallback.\n\nOverlay files can be provided through the\n[ORD Configuration endpoint](../../spec-v1/index.md#ord-configuration-endpoint),\nor attached as `resourceDefinitions` entries on API or Event resources with type `ord:overlay:v1`.",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://open-resource-discovery.org/spec-v1/interfaces/OrdOverlay.schema.json#",
  "title": "ORD Overlay",
  "x-feature-status": "alpha",
  "x-introduced-in-version": "1.15.0",
  "x-ums-type": "root",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string",
      "format": "uri-reference",
      "description": "Optional [URL](https://tools.ietf.org/html/rfc3986) to the ORD Overlay schema (defined as a JSON Schema).\nIf provided, this enables code intelligence and validation in supported editors (like VSCode) and tools.",
      "anyOf": [
        {
          "type": "string",
          "format": "uri-reference"
        },
        {
          "const": "https://open-resource-discovery.org/spec-v1/interfaces/OrdOverlay.schema.json#"
        }
      ]
    },
    "ordOverlay": {
      "type": "string",
      "description": "Version of the ORD Overlay specification.",
      "enum": [
        "0.1"
      ],
      "examples": [
        "0.1"
      ]
    },
    "ordId": {
      "type": "string",
      "maxLength": 255,
      "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):(overlay):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
      "description": "Optional ORD ID of this overlay document.",
      "examples": [
        "sap.foo:overlay:astronomy-api-openapi:v1"
      ]
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "Optional description of the overlay document itself.\n\nNotated in [CommonMark](https://spec.commonmark.org/) (Markdown).",
      "examples": [
        "This overlay adds descriptive metadata for AI use-cases\nwithout modifying the original resource definition.\n"
      ]
    },
    "perspective": {
      "description": "Overlay-specific [perspective](../../spec-v1/index.md#perspectives) that scopes where this overlay should be applied.\n\nUse this together with `describedSystemType`, `describedSystemVersion`, and `describedSystemInstance`\nto describe whether the overlay applies broadly to a system type, to one released system version,\nor only to a specific system instance.",
      "type": "string",
      "title": "Overlay Perspective",
      "x-ums-type": "ignore",
      "oneOf": [
        {
          "const": "system-type",
          "description": "Applies the overlay at system-type level.\n\nUse this when the overlay should patch the same targeted resource across versions and instances\nof the same system type, typically for the same ORD resource major version.\n`describedSystemType` SHOULD be provided as the identifying context."
        },
        {
          "const": "system-version",
          "description": "Applies the overlay to one concrete system version.\n\nUse this when metadata differs between released versions and the patch should only affect\na specific version of the target resource.\n`describedSystemVersion` SHOULD be provided, and `describedSystemType` SHOULD also be provided as parent context."
        },
        {
          "const": "system-instance",
          "description": "Applies the overlay to one concrete system instance / tenant.\n\nUse this when the patch reflects tenant-specific configuration, extensions, or runtime differences\nin the target metadata.\n`describedSystemInstance` SHOULD be provided."
        }
      ],
      "examples": [
        "system-type",
        "system-version",
        "system-instance"
      ]
    },
    "describedSystemType": {
      "$ref": "#/definitions/OverlaySystemType",
      "description": "Information on the [system type](../../spec-v1/index.md#system-type) this overlay describes.\nThis object is identical to the ORD Document `describedSystemType` object; see [System Type](../../spec-v1/interfaces/Document.md#system-type).\n\nIts purpose is to link the overlay to the same system landscape model as ORD resources, if needed.\nThis is the primary context object for `perspective: system-type`, and also the parent context\nfor more specific `system-version` and `system-instance` overlays.\n\nUsually this is not necessary for static overlays if the patched resource is already selected via ORD ID."
    },
    "describedSystemVersion": {
      "$ref": "#/definitions/OverlaySystemVersion",
      "description": "Information on the [system version](../../spec-v1/index.md#system-version) this overlay describes.\nThis object is identical to the ORD Document `describedSystemVersion` object; see [System Version](../../spec-v1/interfaces/Document.md#system-version).\n\nIts purpose is to link the overlay to the same system landscape model as ORD resources, if needed.\nUse this when the overlay should only patch metadata for one specific released system version.\n\nUsually this is not necessary for static overlays if the patched resource is already selected via ORD ID."
    },
    "describedSystemInstance": {
      "$ref": "#/definitions/OverlaySystemInstance",
      "description": "Information on the [system instance](../../spec-v1/index.md#system-instance) this overlay describes.\nThis object is identical to the ORD Document `describedSystemInstance` object; see [System Instance](../../spec-v1/interfaces/Document.md#system-instance).\n\nIts purpose is to link the overlay to the same system landscape model as ORD resources, if needed.\nUse this when the overlay should only patch metadata for one concrete tenant / runtime instance.\n\nUsually this is not necessary for static overlays if the patched resource is already selected via ORD ID."
    },
    "visibility": {
      "type": "string",
      "title": "Overlay Visibility",
      "x-ums-type": "ignore",
      "description": "Controls which consumers can discover and access this overlay document.\n\nIt does NOT control runtime access to the resources being patched — that is managed separately through authentication and authorization mechanisms.\n\nUse this to prevent exposing internal overlay enrichments to inappropriate consumer audiences.",
      "oneOf": [
        {
          "const": "public",
          "description": "The overlay can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties."
        },
        {
          "const": "internal",
          "description": "The overlay can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor).\nMUST NOT be made available to external parties or vendor customers."
        },
        {
          "const": "private",
          "description": "The overlay should not be discoverable outside the application / service's own deployment scope (e.g., outside of the provider application or the same system namespace / system type)."
        }
      ]
    },
    "target": {
      "description": "Optional target context identifying the resource or definition file being patched.\nSee [Overlay Target](#overlay-target) for details on identifier requirements and disambiguation.",
      "$ref": "#/definitions/OverlayTarget"
    },
    "patches": {
      "type": "array",
      "minItems": 1,
      "description": "Ordered sequence of patches to apply to the targeted resource(s).\nPatches are applied strictly in the order they are listed.\nIf two patches target the same document element, both are applied in sequence —\nthe later patch supersedes the earlier one.",
      "items": {
        "$ref": "#/definitions/OverlayPatch"
      }
    },
    "meta": {
      "$ref": "#/definitions/OverlayMeta",
      "description": "Optional arbitrary metadata associated with this overlay document for use by overlay consumers, tooling, and registries.\nThe contents of this block are **never applied to the target document** — they are strictly out-of-band and ignored by the patch merge process.\n\nUse this to carry document-level information such as provenance, approval status, or processing instructions\nthat apply to the overlay as a whole rather than to individual patches."
    }
  },
  "required": [
    "ordOverlay",
    "patches"
  ],
  "definitions": {
    "OverlayTarget": {
      "type": "object",
      "title": "Overlay Target",
      "x-ums-type": "embedded",
      "description": "Optional context about the target being patched.\nThe target can refer to an ORD resource or to a referenced resource definition file.\n\nWhen this object is present, at least one of `ordId`, `url`, `correlationIds`, or `definitionType`\nMUST be provided so that consumers can identify what is being patched.\n`ordId` identifies the ORD resource whose attached definition file is being patched.\nUse `url` and/or `definitionType` to disambiguate which definition file to target.\n\nExample: one OData API resource can have both `edmx` and `openapi-v3` definitions attached.\nIn such cases, provide `definitionType` and/or `url` to make the concrete patch target explicit.\n\nMultiple identifiers, if provided, are treated as all pointing to the same resource.\n\nUse `systemInstance` to further scope the target to a specific [system instance](../../spec-v1/index.md#system-instance) (tenant).\nThis is relevant when `perspective: system-instance` is set and the same ORD resource exists across multiple tenants.",
      "additionalProperties": false,
      "properties": {
        "ordId": {
          "type": "string",
          "description": "ORD ID of the target being patched (e.g. an API Resource, Event Resource, Data Product).\nMUST be a valid [ORD ID](../../spec-v1/index.md#ord-id).",
          "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-]+):([a-zA-Z0-9._\\-]+):(v0|v[1-9][0-9]*)$",
          "maxLength": 255,
          "examples": [
            "sap.s4:apiResource:OP_API_BUSINESS_PARTNER_SRV:v1"
          ]
        },
        "url": {
          "type": "string",
          "format": "uri-reference",
          "description": "URL or URI pointing directly to the file being patched.\nThis is typically a resource definition file (e.g. OpenAPI, AsyncAPI, OData CSDL),\nbut can also point to any JSON/YAML-based target document.",
          "examples": [
            "https://example.com/api/openapi.json",
            "./openapi.yaml"
          ]
        },
        "correlationIds": {
          "type": "array",
          "minItems": 1,
          "description": "Correlation IDs referencing the target resource in external registries or systems of record.\nReuses the ORD correlation ID format: `namespace:type:localId`.\nAll listed IDs are treated as pointing to the same resource.",
          "items": {
            "type": "string",
            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$",
            "maxLength": 255
          },
          "examples": [
            [
              "sap.s4:communicationScenario:SAP_COM_0008"
            ]
          ]
        },
        "definitionType": {
          "description": "Optional, but RECOMMENDED type of the target definition being patched.\nIf provided, this SHOULD match the `type` of the referenced metadata definition\n(as used in API/Event/Capability resource definitions).\nThis is especially useful when target `ordId` resolves to a resource with multiple attached definitions.\n\nThis can be used to disambiguate how selectors are interpreted for the target.\n\nMUST be either:\n- any valid [Specification ID](../../spec-v1/index.md#specification-id), or\n- one of the pre-defined values reused from:\n  - API Resource Definition `type`\n  - Event Resource Definition `type`\n  - Capability Definition `type`\n\nThe literal value `custom` is deprecated for `definitionType` and MUST NOT be used.\nIn such cases, use a concrete [Specification ID](../../spec-v1/index.md#specification-id) instead.",
          "type": "string",
          "title": "Overlay Definition Type",
          "x-ums-type": "ignore",
          "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](../../spec-v1/index.md#specification-id)."
            },
            {
              "const": "openapi-v2"
            },
            {
              "const": "openapi-v3"
            },
            {
              "const": "openapi-v3.1+"
            },
            {
              "const": "raml-v1"
            },
            {
              "const": "edmx"
            },
            {
              "const": "csdl-json"
            },
            {
              "const": "graphql-sdl"
            },
            {
              "const": "wsdl-v1"
            },
            {
              "const": "wsdl-v2"
            },
            {
              "const": "a2a-agent-card"
            },
            {
              "const": "sap-rfc-metadata-v1"
            },
            {
              "const": "sap-sql-api-definition-v1"
            },
            {
              "const": "sap-csn-interop-effective-v1"
            },
            {
              "const": "asyncapi-v2"
            },
            {
              "const": "sap.mdo:mdi-capability-definition:v1"
            }
          ],
          "examples": [
            "openapi-v3",
            "asyncapi-v2",
            "sap.mdo:mdi-capability-definition:v1"
          ]
        },
        "systemInstance": {
          "$ref": "#/definitions/OverlaySystemInstance",
          "examples": [
            {
              "localId": "LocalTenantId123"
            },
            {
              "correlationIds": [
                "sap.cld:tenant:741234567"
              ]
            }
          ]
        }
      }
    },
    "OverlayPatch": {
      "type": "object",
      "title": "Overlay Patch",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "description": "A single patch action to apply to the element identified by the [Overlay Selector](#overlay-selector).",
      "required": [
        "action",
        "selector"
      ],
      "if": {
        "properties": {
          "action": {
            "enum": [
              "update",
              "merge"
            ]
          }
        }
      },
      "then": {
        "required": [
          "data"
        ]
      },
      "else": {
        "properties": {
          "data": {
            "not": {
              "anyOf": [
                {
                  "type": "object",
                  "maxProperties": 0
                },
                {
                  "type": "array",
                  "maxItems": 0
                },
                {
                  "type": "null"
                }
              ]
            }
          }
        }
      },
      "properties": {
        "description": {
          "type": "string",
          "description": "Optional human-readable note explaining the purpose or rationale of this individual patch.\nThis field is purely informational and has no effect on patch application.\n\nTypical use-cases:\n- Reviewer / audit notes explaining why a particular element is being modified.\n- Commit-message style annotations generated by AI tooling (e.g. \"Enriched summary for GetUser operation\").\n- References to tickets or decisions that motivated the change.\n\nMaps 1:1 to the `actions[].description` field in the\n[OpenAPI Overlay spec](https://spec.openapis.org/overlay/v1.1.0.html), enabling lossless\nround-trip conversion between OpenAPI overlays and ORD overlays.",
          "examples": [
            "Added missing description for the pagination parameters.",
            "Marked as deprecated following platform v3 migration.",
            "JIRA-1234: Corrected return type description."
          ]
        },
        "action": {
          "type": "string",
          "title": "Overlay Patch Action",
          "x-ums-type": "ignore",
          "description": "The patch operation to perform on the selected element.",
          "oneOf": [
            {
              "const": "update",
              "description": "Replace the selected element entirely with `data`."
            },
            {
              "const": "remove",
              "description": "Remove the selected element or specific fields within it.\n\n- When `data` is omitted: remove the selected element from the document entirely.\n- When `data` is provided: remove only the fields or array entries marked by the removal mask.\n  For object masks, properties with `null` values are removed recursively.\n  This uses JSON Merge Patch-style delete semantics where `null` indicates deletion.\n  Nested `null` values remove nested fields as well."
            },
            {
              "const": "merge",
              "description": "Deep-merge `data` into the selected element.\n\n- Objects are deep-merged recursively.\n- Scalar values are overwritten by the value from `data`.\n- Arrays are appended (new array items are added after existing items).\n- Existing object properties not mentioned in `data` are preserved."
            }
          ]
        },
        "selector": {
          "$ref": "#/definitions/OverlaySelector"
        },
        "data": {
          "$ref": "#/definitions/OverlayPatchValue"
        },
        "tags": {
          "type": "array",
          "minItems": 1,
          "description": "String labels associated with the patched element.\nUseful for classification, domain tagging, and filtering in registries or tooling.\n\nThese are purely informational and have no effect on patch application or on the\ntarget document.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "examples": [
            [
              "HR",
              "Employee",
              "Core"
            ],
            [
              "deprecated",
              "migration-v3"
            ]
          ]
        },
        "meta": {
          "$ref": "#/definitions/OverlayMeta"
        }
      }
    },
    "OverlayMeta": {
      "type": "object",
      "title": "Overlay Meta",
      "x-ums-type": "embedded",
      "description": "Optional arbitrary metadata for use by overlay consumers, tooling, and registries.\nThe contents of this block are **never applied to the target document** — they are strictly out-of-band and ignored by the patch merge process.\n\nWhen used at the document level, this carries information about the overlay as a whole (e.g. provenance, approval status, processing instructions).\nWhen used at the patch level, this carries information specific to the patched element (e.g. confidence scores, source references).\n\nThis is an open/extensible object — any properties are allowed.",
      "additionalProperties": true,
      "examples": [
        {
          "sourceSystem": "AI Enrichment Pipeline v2.1",
          "enrichmentDate": "2026-04-01"
        },
        {
          "someMetadataKey": {
            "complex": "object"
          }
        }
      ]
    },
    "OverlaySelector": {
      "type": "object",
      "title": "Overlay Selector",
      "x-ums-type": "embedded",
      "description": "Identifies the element in the target to patch.\nExactly one selector type is used per patch.\n\nPrefer concept-level selectors over generic `jsonPath` where possible,\nas they are resilient to structural changes in the target format.",
      "oneOf": [
        {
          "$ref": "#/definitions/OverlaySelectorByRoot"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByJsonPath"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByOperation"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByEntityType"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByComplexType"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByEnumType"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByPropertyType"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByEntitySet"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByNamespace"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByParameter"
        },
        {
          "$ref": "#/definitions/OverlaySelectorByReturnType"
        }
      ]
    },
    "OverlaySelectorByRoot": {
      "type": "object",
      "title": "Overlay Selector By Root",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "root"
      ],
      "properties": {
        "root": {
          "type": "boolean",
          "const": true,
          "description": "Concept-level selector targeting the root of the document being patched.\nMUST be `true`.\n\nUse this selector to patch top-level properties of any JSON/YAML-based metadata format\nwithout coupling to specific structural paths. This is especially useful for:\n\n- Patching document-level metadata (title, description, version, contact info)\n- Adding or merging top-level sections (e.g. `components`, `tags`, `servers` in OpenAPI)\n- Extending the root object with new properties across format versions\n\nSupported metadata formats and typical use cases:\n\n**OpenAPI** (`openapi-v2`, `openapi-v3`, `openapi-v3.1+`):\n- Patch `info.description`, `info.title`, `info.contact`\n- Add `components.securitySchemes` or `components.schemas`\n- Add `tags`, `servers`, or `externalDocs`\n\n**AsyncAPI** (`asyncapi-v2`):\n- Patch `info` block, `servers`, `channels` at the root\n\n**OData CSDL JSON** (`csdl-json`):\n- Patch root-level `$Version`, `$EntityContainer`, or add namespace objects\n\n**ORD Document** (no specific `definitionType`):\n- Patch root-level ORD document properties\n\n**MCP / A2A** (any Specification ID):\n- Patch top-level metadata or add root-level tool/skill definitions\n\nThe `root` selector is equivalent to `jsonPath: \"$\"` but is preferred because it\nexplicitly communicates intent and is resilient to format differences where `$`\nmight have ambiguous semantics."
        }
      },
      "examples": [
        {
          "root": true
        }
      ]
    },
    "OverlaySelectorByJsonPath": {
      "type": "object",
      "title": "Overlay Selector By JsonPath",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "jsonPath"
      ],
      "properties": {
        "jsonPath": {
          "type": "string",
          "minLength": 1,
          "pattern": "^\\$",
          "description": "JSONPath expression targeting any location in a JSON/YAML-based target document.\nMUST start with `$`.\nThis is the generic structural fallback selector, supported for all JSON/YAML-based formats:\n- `openapi-v2`, `openapi-v3`, `openapi-v3.1+`: targets any node in the OpenAPI document.\n- `a2a-agent-card`: targets any node in the A2A Agent Card JSON document.\n- `csdl-json`: targets any node in the OData CSDL JSON document.\n- MCP (any Specification ID): targets any node in the MCP-compatible JSON/YAML tool metadata.\n\nUse concept-level selectors (`operation`, `entityType`, etc.) when available, as they are\nresilient to structural differences between format versions. Reserve `jsonPath` for cases\nwhere no concept-level selector covers the target location.",
          "examples": [
            "$.info.description",
            "$.paths['/constellations'].get"
          ]
        }
      },
      "examples": [
        {
          "jsonPath": "$.info.description"
        },
        {
          "jsonPath": "$.paths['/constellations'].get"
        }
      ]
    },
    "OverlaySelectorByOperation": {
      "type": "object",
      "title": "Overlay Selector By Operation",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "operation"
      ],
      "properties": {
        "operation": {
          "type": "string",
          "minLength": 1,
          "description": "Concept-level operation identifier.\nSupported mappings by format:\n- OpenAPI (`openapi-v2`, `openapi-v3`, `openapi-v3.1+`): maps to the `operationId` field on\n  an HTTP operation inside `paths.{path}.{method}`.\n- MCP (any Specification ID other than `a2a-agent-card`): maps to `tools[].name`.\n  See: https://modelcontextprotocol.io/specification/2025-11-25/schema#tool-name\n- A2A Agent Card (`a2a-agent-card`): maps to `skills[].id`.\n  See: https://google.github.io/A2A/specification/#agentskill-object\n- OData (`edmx`, `csdl-json`): maps to the Action or Function name at Schema level.\n  MUST use the namespace-qualified name (e.g. `OData.Demo.Approval`) to be unambiguous.\n  For OData v2 `edmx` targets: also searches FunctionImport elements in EntityContainer\n  when no Schema-level Action/Function matches the name.\n  For bound operations overloaded on multiple entity types, use [`jsonPath`](#overlay-selector-by-jsonpath) as a fallback\n  to target the specific overload.\n\nWhen `definitionType` is set on `target`, the format is known and the selector resolves unambiguously.\nWhen `definitionType` is absent, the implementation SHOULD infer the format from the target\ndocument's content (e.g. the `openapi` field, `$schema`, or `$kind` markers).",
          "examples": [
            "getConstellationByAbbreviation",
            "dispute-case-resolution",
            "OData.Demo.Approval",
            "OData.Demo.Rejection",
            "getCompensationHistory"
          ]
        }
      },
      "examples": [
        {
          "operation": "getConstellationByAbbreviation"
        },
        {
          "operation": "OData.Demo.Approval"
        },
        {
          "operation": "dispute-case-resolution"
        }
      ]
    },
    "OverlaySelectorByEntityType": {
      "type": "object",
      "title": "Overlay Selector By Entity Type",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "entityType"
      ],
      "properties": {
        "entityType": {
          "type": "string",
          "minLength": 1,
          "description": "**OData-specific** selector targeting an EntityType element by its namespace-qualified name.\n\nAn EntityType in OData is a structured type with a key that represents a business entity\n(e.g. `Customer`, `Order`, `Employee`). This maps to:\n- `edmx` (OData v2/v4 CSDL XML): targets `<EntityType Name=\"...\">` elements in the Schema.\n- `csdl-json` (OData v4 CSDL JSON): targets elements with `$Kind: \"EntityType\"`.\n\nMUST use the namespace-qualified name (e.g. `OData.Demo.Customer`) for unambiguous resolution.\nFor EntitySet-level patching (Capabilities annotations), use the [`entitySet`](#overlay-selector-by-entity-set) selector instead.\n\nFor CSN Interop targets (`sap-csn-interop-effective-v1`), this selector targets a `definitions`\nentry by its fully qualified key (e.g. `AirlineService.Airline`).\n\nTo target ComplexType or EnumType elements, use the dedicated `complexType` or `enumType` selectors.",
          "examples": [
            "OData.Demo.Customer",
            "OData.Demo.LeaveRequest",
            "AirlineService.Airline"
          ]
        }
      },
      "examples": [
        {
          "entityType": "OData.Demo.Customer"
        },
        {
          "entityType": "AirlineService.Airline"
        }
      ]
    },
    "OverlaySelectorByComplexType": {
      "type": "object",
      "title": "Overlay Selector By Complex Type",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "complexType"
      ],
      "properties": {
        "complexType": {
          "type": "string",
          "minLength": 1,
          "description": "**OData-specific** selector targeting a ComplexType element by its namespace-qualified name.\n\nA ComplexType in OData is a structured type without a key, typically used for reusable\nembedded structures like addresses, coordinates, or measurement values. This maps to:\n- `edmx` (OData v2/v4 CSDL XML): targets `<ComplexType Name=\"...\">` elements in the Schema.\n- `csdl-json` (OData v4 CSDL JSON): targets elements with `$Kind: \"ComplexType\"`.\n\nMUST use the namespace-qualified name (e.g. `OData.Demo.Address`) for unambiguous resolution.\n\nComplexTypes are often shared across multiple EntityTypes, so patching a ComplexType\naffects all usages of that type throughout the service.",
          "examples": [
            "OData.Demo.Address",
            "OData.Demo.GeoLocation",
            "API_BUSINESS_PARTNER.A_AddressEmailAddress"
          ]
        }
      },
      "examples": [
        {
          "complexType": "OData.Demo.Address"
        }
      ]
    },
    "OverlaySelectorByEnumType": {
      "type": "object",
      "title": "Overlay Selector By Enum Type",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "enumType"
      ],
      "properties": {
        "enumType": {
          "type": "string",
          "minLength": 1,
          "description": "**OData-specific** selector targeting an EnumType element by its namespace-qualified name.\n\nAn EnumType in OData is an enumeration type with named members representing a fixed set\nof values (e.g. `OrderStatus`, `Priority`, `Gender`). This maps to:\n- `edmx` (OData v2/v4 CSDL XML): targets `<EnumType Name=\"...\">` elements in the Schema.\n- `csdl-json` (OData v4 CSDL JSON): targets elements with `$Kind: \"EnumType\"`.\n\nMUST use the namespace-qualified name (e.g. `OData.Demo.OrderStatus`) for unambiguous resolution.\n\nTo patch individual enum members, use the [`propertyType`](#overlay-selector-by-property-type) selector with this `enumType` as context.",
          "examples": [
            "OData.Demo.OrderStatus",
            "OData.Demo.Priority",
            "SAP.Common.ApprovalStatus"
          ]
        }
      },
      "examples": [
        {
          "enumType": "OData.Demo.OrderStatus"
        }
      ]
    },
    "OverlaySelectorByPropertyType": {
      "type": "object",
      "title": "Overlay Selector By Property Type",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "propertyType"
      ],
      "properties": {
        "propertyType": {
          "type": "string",
          "minLength": 1,
          "description": "Concept-level property, navigation property, or enum member identifier.\n\nUse the unqualified property name (e.g. `BirthDate`, `Street`, `Pending`).\nProperty names are frequently reused across types, so a parent type context\nMUST be provided via exactly one of: `entityType`, `complexType`, or `enumType`.\n\nSupported metadata formats:\n- `edmx` (OData v2/v4 CSDL XML): targets a Property or NavigationProperty on an EntityType\n  or ComplexType; or a Member on an EnumType.\n- `csdl-json` (OData v4 CSDL JSON): targets non-`$`-prefixed keys on the matched type object.\n- `sap-csn-interop-effective-v1` (CSN Interop): targets an entry in the `elements` map of\n  the matched entity definition. Use `entityType` for CSN Interop targets.",
          "examples": [
            "BirthDate",
            "Street",
            "Pending",
            "AirlineID"
          ]
        },
        "entityType": {
          "type": "string",
          "minLength": 1,
          "description": "Parent EntityType context for the property.\nUse this when targeting a property on an EntityType.\nMUST be the namespace-qualified name (e.g. `OData.Demo.Customer`).\nFor CSN Interop: the fully qualified `definitions` key (e.g. `AirlineService.Airline`).\n\nExactly one of `entityType`, `complexType`, or `enumType` MUST be provided.",
          "examples": [
            "OData.Demo.Customer",
            "AirlineService.Airline"
          ]
        },
        "complexType": {
          "type": "string",
          "minLength": 1,
          "description": "**OData-specific** parent ComplexType context for the property.\nUse this when targeting a property on a ComplexType.\nMUST be the namespace-qualified name (e.g. `OData.Demo.Address`).\n\nExactly one of `entityType`, `complexType`, or `enumType` MUST be provided.",
          "examples": [
            "OData.Demo.Address",
            "OData.Demo.GeoLocation"
          ]
        },
        "enumType": {
          "type": "string",
          "minLength": 1,
          "description": "**OData-specific** parent EnumType context for the enum member.\nUse this when targeting a member of an EnumType.\nMUST be the namespace-qualified name (e.g. `OData.Demo.OrderStatus`).\n\nExactly one of `entityType`, `complexType`, or `enumType` MUST be provided.",
          "examples": [
            "OData.Demo.OrderStatus",
            "OData.Demo.Priority"
          ]
        }
      },
      "examples": [
        {
          "propertyType": "BirthDate",
          "entityType": "OData.Demo.Customer"
        },
        {
          "propertyType": "Street",
          "complexType": "OData.Demo.Address"
        },
        {
          "propertyType": "Pending",
          "enumType": "OData.Demo.OrderStatus"
        }
      ]
    },
    "OverlaySelectorByEntitySet": {
      "type": "object",
      "title": "Overlay Selector By Entity Set",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "entitySet"
      ],
      "properties": {
        "entitySet": {
          "type": "string",
          "minLength": 1,
          "description": "Concept-level entity set identifier.\nSupported metadata formats:\n- `edmx` (OData v2/v4 CSDL XML): targets an EntitySet element inside EntityContainer.\n  May use the unqualified name (e.g. `Customers`) or namespace-prefixed name.\n- `csdl-json` (OData v4 CSDL JSON): targets a key with `$Collection: true` inside the\n  EntityContainer object in the namespace.\n\nUse `entitySet` when you need to patch EntityContainer-bound metadata such as\nCapabilities annotations (InsertRestrictions, UpdateRestrictions, etc.).\nFor patching EntityType structure (Properties, NavigationProperties) via deep merge, use `entityType`.\nTo target a specific property for fine-grained patching, prefer `propertyType` (requires `entityType` as context).",
          "examples": [
            "Customers",
            "SalesOrders",
            "EmployeeSet"
          ]
        }
      }
    },
    "OverlaySelectorByNamespace": {
      "type": "object",
      "title": "Overlay Selector By Namespace",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "namespace"
      ],
      "properties": {
        "namespace": {
          "type": "string",
          "minLength": 1,
          "description": "Concept-level OData schema/namespace selector.\nSupported metadata formats:\n- `edmx` (OData v2/v4 CSDL XML): targets the `<Schema Namespace=\"...\">` element.\n  Use the namespace value exactly as declared (e.g. `com.example.OrderService`).\n- `csdl-json` (OData v4 CSDL JSON): targets the namespace-level object (the non-`$`-prefixed\n  key in the CSDL JSON document that matches the namespace value).\n\nUse this selector for service/schema-level annotations such as `@Core.Description` and\n`@Core.LongDescription` on the OData service as a whole.",
          "examples": [
            "com.example.OrderService",
            "SFSF.EC.Compensation",
            "API_BUSINESS_PARTNER"
          ]
        }
      }
    },
    "OverlaySelectorByParameter": {
      "type": "object",
      "title": "Overlay Selector By Parameter",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "parameter",
        "operation"
      ],
      "properties": {
        "parameter": {
          "type": "string",
          "minLength": 1,
          "description": "Concept-level parameter name.\nSupported metadata formats:\n- `edmx` (OData v2/v4 CSDL XML): targets a `<Parameter Name=\"...\">` child element on\n  an Action, Function, or FunctionImport. Use the unqualified parameter name.\n- `csdl-json` (OData v4 CSDL JSON): targets an entry in the `$Parameter` array of an\n  Action/Function overload whose `$Name` matches.\n- OpenAPI (`openapi-v2`, `openapi-v3`, `openapi-v3.1+`): targets an entry in the\n  `parameters` array of the operation identified by `operation` (operationId), matching\n  by the parameter `name` field.\n\n`operation` MUST always accompany this field to unambiguously identify the owning operation.",
          "examples": [
            "employeeId",
            "Count",
            "filter"
          ]
        },
        "operation": {
          "type": "string",
          "minLength": 1,
          "description": "Required operation context for the selected parameter.\n- For OData: the namespace-qualified Action, Function, or FunctionImport name.\n- For OpenAPI: the `operationId` of the HTTP operation.",
          "examples": [
            "com.example.Svc.TerminateEmployee",
            "getConstellationByAbbreviation"
          ]
        }
      }
    },
    "OverlaySelectorByReturnType": {
      "type": "object",
      "title": "Overlay Selector By Return Type",
      "x-ums-type": "embedded",
      "additionalProperties": false,
      "required": [
        "returnType",
        "operation"
      ],
      "properties": {
        "returnType": {
          "type": "boolean",
          "const": true,
          "description": "Flag indicating that the return type of the specified operation is the target.\nMUST be `true`. Use `operation` to identify the owning operation.\nSupported metadata formats:\n- `edmx` (OData v2/v4 CSDL XML): targets the `<ReturnType>` child element of the\n  matched Action or Function element.\n- `csdl-json` (OData v4 CSDL JSON): targets the `$ReturnType` object inside the matched\n  Action/Function overload array entry."
        },
        "operation": {
          "type": "string",
          "minLength": 1,
          "description": "Namespace-qualified Action or Function name whose ReturnType is targeted.\n- For `edmx`: the namespace-qualified name of the Action or Function (e.g. `com.example.Svc.TerminateEmployee`).\n- For `csdl-json`: the namespace-qualified name looked up in the Namespace object.",
          "examples": [
            "com.example.Svc.TerminateEmployee",
            "com.example.Svc.GetDirectReports"
          ]
        }
      }
    },
    "OverlayPatchValue": {
      "type": [
        "object",
        "array",
        "string",
        "number",
        "boolean",
        "null"
      ],
      "title": "Overlay Patch Value",
      "x-ums-type": "embedded",
      "description": "The value used by the patch `action`.\nStructure depends on the target being patched and the action type.\n\nFor OData targets (`edmx`, `csdl-json`), the value MUST be expressed in CSDL JSON\nannotation format. Annotation keys use the `@TermName` convention:\ne.g. `{ \"@Core.Description\": \"...\", \"@Core.Revisions\": [...] }`.\nWhen the target is EDMX XML, the merge implementation converts this to `<Annotation>` elements.\nSee: https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html\n\nFor CSN Interop targets (`sap-csn-interop-effective-v1`), the value is plain CSN JSON\nmerged directly into the matched entity definition or element object.\nUse the CSN `doc` field for human-readable descriptions, and `@AnnotationName` keys\nfor vocabulary annotations (e.g. `@EndUserText.label`, `@Semantics.text`).\nSee: https://sap.github.io/csn-interop-specification/"
    },
    "OverlaySystemInstance": {
      "type": "object",
      "title": "Overlay System Instance",
      "x-ums-type": "ignore",
      "description": "A [system instance](../../spec-v1/index.md#system-instance) is a concrete, running instance of a system type.\nThis object is identical to the ORD Document `describedSystemInstance` object; see [System Instance](../../spec-v1/interfaces/Document.md#system-instance).\n\nIts purpose is to link the overlay to the same system landscape model as ORD resources, if needed.\nUsually this is not necessary for static overlays if the patched resource is already selected via ORD ID.",
      "properties": {
        "baseUrl": {
          "type": "string",
          "format": "uri-reference",
          "description": "Optional [base URL](../../spec-v1/index.md#base-url) of the system instance.\nBy providing the base URL, relative URLs in the overlay are resolved relative to it.",
          "pattern": "^http[s]?:\\/\\/[^:\\/\\s]+\\.[^:\\/\\s\\.]+(:\\d+)?(\\/[a-zA-Z0-9-\\._~]+)*$",
          "examples": [
            "https://example-sap-system.com",
            "https://sub.foo.bar.com/api/v1"
          ]
        },
        "localId": {
          "type": "string",
          "description": "Optional local ID for the system instance (usually tenant ID), as known by the described system.",
          "maxLength": 255,
          "examples": [
            "LocalTenantId123"
          ]
        },
        "correlationIds": {
          "type": "array",
          "description": "Correlation IDs for linking this system instance to external systems of record.",
          "minItems": 1,
          "items": {
            "type": "string",
            "title": "Overlay Correlation ID",
            "x-ums-type": "ignore",
            "description": "Correlation ID identifying related records in external systems of record.\nMUST be a valid [Correlation ID](../../spec-v1/index.md#correlation-id).",
            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$",
            "maxLength": 255
          },
          "examples": [
            [
              "sap.cld:tenant:741234567"
            ]
          ]
        }
      },
      "additionalProperties": false
    },
    "OverlaySystemType": {
      "type": "object",
      "title": "Overlay System Type",
      "x-ums-type": "ignore",
      "description": "A [system type](../../spec-v1/index.md#system-type) is the abstract type of an application or service, from operational perspective.\nThis object is identical to the ORD Document `describedSystemType` object; see [System Type](../../spec-v1/interfaces/Document.md#system-type).\n\nIts purpose is to link the overlay to the same system landscape model as ORD resources, if needed.\nUsually this is not necessary for static overlays if the patched resource is already selected via ORD ID.",
      "properties": {
        "systemNamespace": {
          "type": "string",
          "description": "The [system namespace](../../spec-v1/index.md#system-namespace) is a unique identifier for the system type.",
          "pattern": "^[a-z0-9]+(?:[.][a-z0-9]+){1}$",
          "maxLength": 32,
          "examples": [
            "sap.s4",
            "sap.c4c",
            "sap.cld"
          ]
        },
        "correlationIds": {
          "type": "array",
          "description": "Correlation IDs for linking this system type to external systems of record.",
          "minItems": 1,
          "items": {
            "type": "string",
            "title": "Overlay Correlation ID",
            "x-ums-type": "ignore",
            "description": "Correlation ID identifying related records in external systems of record.\nMUST be a valid [Correlation ID](../../spec-v1/index.md#correlation-id).",
            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$",
            "maxLength": 255
          },
          "examples": [
            [
              "sap.cld:systemRole:S4_PC"
            ]
          ]
        }
      },
      "additionalProperties": false
    },
    "OverlaySystemVersion": {
      "type": "object",
      "title": "Overlay System Version",
      "x-ums-type": "ignore",
      "description": "A [system version](../../spec-v1/index.md#system-version) describes a version/release of the system.\nThis object is identical to the ORD Document `describedSystemVersion` object; see [System Version](../../spec-v1/interfaces/Document.md#system-version).\n\nIts purpose is to link the overlay to the same system landscape model as ORD resources, if needed.\nUsually this is not necessary for static overlays if the patched resource is already selected via ORD ID.",
      "properties": {
        "version": {
          "type": "string",
          "description": "The version of the system instance (run-time) or the version of the described system-version perspective.\n\nIt MUST follow the [Semantic Versioning 2.0.0](https://semver.org/) standard.",
          "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
          "examples": [
            "1.2.3",
            "2024.8.0"
          ]
        },
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "description": "Human-readable title of the system version.",
          "examples": [
            "SAP S/4HANA Cloud 2408"
          ]
        },
        "correlationIds": {
          "type": "array",
          "description": "Correlation IDs for linking this system version to external systems of record.",
          "minItems": 1,
          "items": {
            "type": "string",
            "title": "Overlay Correlation ID",
            "x-ums-type": "ignore",
            "description": "Correlation ID identifying related records in external systems of record.\nMUST be a valid [Correlation ID](../../spec-v1/index.md#correlation-id).",
            "pattern": "^([a-z0-9]+(?:[.][a-z0-9]+)*):([a-zA-Z0-9._\\-\\/]+):([a-zA-Z0-9._\\-\\/]+)$",
            "maxLength": 255
          },
          "examples": [
            [
              "sap.cld:release:2408"
            ]
          ]
        }
      },
      "additionalProperties": false
    }
  }
}