{
  "description": "⚠️ BETA: This specification is in beta 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": "beta",
  "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/concepts/identifiers.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/concepts/identifiers.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/concepts/identifiers.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/concepts/identifiers.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"
            },
            {
              "const": "oas-overlay-v1",
              "x-introduced-in-version": "1.17.0"
            },
            {
              "const": "arazzo-v1",
              "x-introduced-in-version": "1.17.0"
            }
          ],
          "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`.\n\nFor CSDL JSON, an update using an OData concept-level selector preserves the selected\nstructural element and replaces its complete annotation set. This exception does not\napply to `root` or `jsonPath`, which retain whole-element replacement semantics.\nFor EDMX, the selected structural element is preserved and `data` replaces its complete\nannotation set."
            },
            {
              "const": "remove",
              "description": "Remove the selected element or specific fields within it.\nIf the selector matches nothing, the action succeeds without changing the document because\nthe requested absence already holds. Tooling SHOULD report a warning.\n\n- When `data` is omitted: remove the selected element from the document entirely.\n  The document root cannot be removed: when the selector resolves to the root\n  (`root`, or `jsonPath: \"$\"`), the patch MUST error. Use `update` to replace the\n  complete document explicitly.\n  For EDMX, the selected structural element is preserved and all annotations on it are removed.\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.\n  A field or array entry that is absent from a matched element is ignored; it does not\n  make the selector unmatched.\n  A removal mask MAY target the document root because it preserves the document itself."
            },
            {
              "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.\n- For OData annotations (keyed `@TermName`, optionally with a qualifier), an annotation\n  with the same term-plus-qualifier identity is replaced rather than duplicated.\n  A target carries at most one annotation per term-plus-qualifier identity."
            }
          ]
        },
        "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.\n\nSelector behavior:\n- All selectors match only structure the target already declares.\n  Overlays patch what exists; they do not synthesize the selected element.\n  This includes `jsonPath`, which MUST NOT create a missing target.\n- A `merge` or `update` patch whose concept-level selector matches nothing MUST error.\n  An unmatched `remove` patch succeeds without changing the document, which makes removal idempotent,\n  and tooling SHOULD report a warning.\n  (`root` always resolves, so this cannot arise for `root`.)\n- A `jsonPath` selector MAY match zero or more elements.\n  When it matches nothing, the patch succeeds without changing the document and tooling SHOULD report\n  a warning, regardless of the patch action.\n  When it matches one or more elements, all locations are identified before mutation and the patch\n  is applied exactly once to every matched location.\n- This is a deliberate limitation of this version: there is no create-on-missing behavior.\n  Errors and warnings surface selector typos and wrong assumptions about the target structure\n  instead of silently authoring unintended content. A future version MAY add a dedicated create\n  action if a concrete use case requires it.",
      "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**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\nJSONPath syntax and evaluation follow [RFC 9535](https://www.rfc-editor.org/rfc/rfc9535).\nEvery conforming toolkit MUST support this portable subset:\n- the root identifier `$`;\n- child-name selectors in dot notation or single-quoted or double-quoted bracket notation;\n- array selectors using non-negative indices;\n- object and array wildcards;\n- selector lists containing distinct member names or distinct non-negative array indices; and\n- array slices whose bounds are omitted or non-negative and whose step is omitted or positive.\n\nA portable ORD Overlay MUST NOT use JSONPath features outside this subset.\nToolkits MAY support additional RFC 9535 features or implementation-specific extensions,\nbut overlays using them are implementation-specific and not portable.\nA toolkit that does not support an expression MUST report an error and MUST NOT treat the\nexpression as matching zero elements.\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",
            "$.servers[*]",
            "$.tags[0,2]",
            "$.items[1:5:2]"
          ]
        }
      },
      "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://a2a-protocol.org/latest/specification/#445-agentskill\n- OData (`edmx`, `csdl-json`): maps to the Action or Function name at Schema level.\n  MUST use either the namespace-qualified name (e.g. `OData.Demo.Approval`) or its\n  namespace-qualified signature (e.g. `OData.Demo.Approval(Edm.Int32,Edm.String)`).\n  For OData v2 `edmx` targets: also searches FunctionImport elements in EntityContainer\n  when a selector without a signature matches no Schema-level Action or Function.\n  A signature selector MUST NOT match a FunctionImport.\n\n  A namespace-qualified name without a signature is sufficient only when it identifies\n  exactly one Action, Function or Function Import.\n  Otherwise, the selector MUST use a signature containing every declared parameter type\n  in declaration order, including the binding parameter of a bound operation.\n  Signature matching uses exact parameter count, order, and types.\n  Empty parentheses select a zero-parameter operation, so `OData.Demo.Ping()` is distinct\n  from the name-only selector `OData.Demo.Ping`.\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",
            "OData.Demo.Approval(Edm.Int32,Edm.String)"
          ]
        }
      },
      "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- `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.).\nYou MAY use an unqualified name if unique (e.g. `Customers`).\nIf not unique a fully-qualified name (e.g. `OData.Demo.Customers`) MUST be used.\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",
            "OData.Demo.Customers"
          ]
        }
      }
    },
    "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: use the same namespace-qualified name or exact signature syntax as the\n  [`operation`](#overlay-selector-by-operation) selector.\n  When the operation is overloaded, the signature MUST identify one overload before\n  `parameter` is resolved.\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 whose return type is targeted.\nUse the same name or exact signature syntax as the\n[`operation`](#overlay-selector-by-operation) selector.\nWhen the operation is overloaded, the signature MUST identify one overload before\nits return type is resolved.",
          "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\": [...] }`.\nFor OData v4 EDMX XML, the merge implementation converts this to `<Annotation>` elements\nand writes them as external targeting (`<Annotations Target=\"Qualified.Name/path\">` blocks at\nthe schema level), reconciling with any annotations already present for the same target so that\na given target's annotations are never split across inline and external locations.\nApplying overlays to OData v2 EDMX XML is out of scope, and tooling MUST report an error.\nAs a workaround, an OData v4 EDMX document MAY describe the model of an OData v2 API and serve\nas the overlay target.\nTarget identifiers use OData CSDL target syntax: `Namespace.Type` for types,\nthe namespace name itself for namespace selectors,\n`Namespace.Type/Member` for properties and enum members,\n`Namespace.Container/Member` for entity sets and FunctionImports,\nand `Namespace.Operation(Type,...)` for Actions and Functions.\nOperation targets always include every declared parameter type, including the binding parameter.\nParameter and return-type targets append `/<parameter-name>` and `/$ReturnType`, respectively.\nSee: https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html\n\nEDMX targets are annotation-only: overlays add, replace, or remove annotations on structure that\nalready exists in the source schema. They cannot create new structural elements (EntityType,\nEntitySet, Property, Function/Action, EnumType, ComplexType), and `jsonPath` is not available for\nEDMX. New structure belongs in the source CSDL/CDS, not in an overlay.\nFor EDMX, `merge` replaces annotations with the same term-plus-qualifier identity and preserves\nall others; `update` replaces the selected target's complete annotation set; and `remove` with\nomitted `data` removes that complete annotation set while preserving the structural target.\n\nFor CSDL JSON, enum-member annotations are carried as sibling keys on the enum type\n(`\"Read@Core.Description\"`), because an enum member is a scalar value that cannot itself hold\nannotation properties.\n`merge` adds or replaces the supplied sibling annotations while preserving the member value and\nother annotations. `update` preserves the member value and replaces that member's complete\nannotation set. `remove` with `data` removes the specified sibling annotations, while `remove`\nwith omitted `data` removes the member and all of its sibling annotations.\n\nFor CSDL JSON, `merge`, `update`, and data-bearing `remove` patches that use an OData\nconcept-level selector (`operation`, `entityType`, `complexType`, `enumType`, `propertyType`,\n`entitySet`, `namespace`, `parameter`, or `returnType`) operate on annotations rather than\nstructural CSDL content.\nTheir data MAY use member names to nest annotation payloads for those members, but MUST NOT use\n`$`-prefixed control properties or other non-annotation values to replace structural content.\nTooling MUST report such structural data as an error rather than silently ignoring it.\n`root` and `jsonPath` selectors retain the generic structural action semantics.\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.\n\nThe `baseUrl` MUST NOT contain a trailing slash.",
          "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"
          ]
        },
        "globalId": {
          "type": "string",
          "x-introduced-in-version": "1.17.0",
          "description": "Optional globally unique and stable ID of the system instance (tenant), assigned by the authority responsible\nfor that tenant identity.\n\nUnlike `localId`, which is only unique within the described system, `globalId` is intended for correlation\nacross participating systems. It is the same identity that can be passed as the `Global-Tenant-Id`\nheader in the [`open`](../../spec-extensions/access-strategies/open.md#global-tenant-id) and\n[`basic-auth`](../../spec-extensions/access-strategies/basic-auth.md#global-tenant-id) access strategies.\n\nThe provider MUST NOT invent this value. It MAY receive the value from an authoritative tenant or landscape\nservice, including through aggregator onboarding, and include it when it can reliably correlate the described\nsystem instance with that authority's record.",
          "maxLength": 255,
          "examples": [
            "c6c80b52-ecc1-47f8-9303-0d55fb67fd41"
          ]
        },
        "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/concepts/identifiers.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/concepts/identifiers.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/concepts/identifiers.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/concepts/identifiers.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
    }
  }
}