ORD Overlay

Alpha

This specification is in alpha and subject to change.

The ORD Overlay is an optional ORD model extension that allows patching referenced resource definition files (e.g. OpenAPI, AsyncAPI, OData CSDL, MCP/A2A Agent Cards) without modifying the original source files.

{
  "ordOverlay": "0.1",
  "target": { "ordId": "sap.foo:apiResource:astronomy:v1", "definitionType": "openapi-v3" },
  "patches": [
    {
      "action": "merge",
      "selector": { "operation": "getConstellationByAbbreviation" },
      "data": {
        "summary": "Get constellation by IAU abbreviation",
        "description": "Returns full details of a constellation by its IAU abbreviation (e.g. 'Ori' for Orion). Useful for star-chart lookups and astronomy education tools."
      }
    }
  ]
}

Publishing

Decision guidance for choosing a publishing approach is collected in the Appendix: ORD Document Resource vs. Attached Resource Definition.

Attached to an ORD Resource

Overlays can be attached directly to an API or Event resource as a resourceDefinitions entry with type ord:overlay:v1. This keeps the overlay co-located with the resource it patches and is the preferred approach when the same ORD Provider owns both.

A single resource can have multiple overlays with different purpose values. This allows independent concerns (e.g. AI enrichment, platform governance) to be managed by different teams without conflicting with each other or the original definition.

Within the same aggregation scope, the combination of purpose and visibility MUST be unique across overlay entries (type: "ord:overlay:v1") on the same resource. This follows directly from the general resource definition uniqueness rule: no two entries in a resourceDefinitions list may share the same type, purpose, and visibility. When a consumer applies multiple overlays to the same target, the processing order is not defined by this specification and MUST be established by the ORD Aggregator or ORD Provider.

{
  "apiResources": [{
    "ordId": "sap.foo:apiResource:astronomy:v1",
    "resourceDefinitions": [
      { "type": "openapi-v3", "url": "/ord/metadata/my-api.oas3.json", "visibility": "public" },
      { "type": "edmx", "url": "/ord/metadata/my-api.edmx.xml", "visibility": "public" },
      { "type": "ord:overlay:v1", "url": "/ord/overlays/ai-enrichment.overlay.json", "visibility": "public", "purpose": "ord:ai-enrichment" },
      { "type": "ord:overlay:v1", "url": "/ord/overlays/governance.overlay.json", "visibility": "internal", "purpose": "foo.bar:governance" }
    ]
  }]
}

As an ORD Document Resource

Overlays can be described as standalone OrdOverlayResource entries inside an ORD Document. This is the preferred approach for cross-cutting overlays that are not tightly coupled to a single resource, or for overlays managed by a different team than the resource provider.

The ORD Overlay Resource acts as any other ORD resource: it has its own ordId, version, releaseStatus, and visibility, and references the actual overlay file via a definitions entry with type: ord:overlay:v1.

{
  "overlays": [
    {
      "ordId": "sap.foo:overlay:astronomy-api-ai-enrichment:v1",
      "title": "Astronomy API AI Enrichment Overlay",
      "version": "1.0.0",
      "releaseStatus": "active",
      "visibility": "public",
      "relatedApiResources": [
        { "ordId": "sap.foo:apiResource:astronomy:v1", "relationType": "ord:patches" }
      ],
      "definitions": [
        {
          "type": "ord:overlay:v1",
          "mediaType": "application/json",
          "url": "/ord/overlays/ai-enrichment.overlay.json",
          "purpose": "ord:ai-enrichment"
        }
      ]
    }
  ]
}

Target Resolution

The optional target object narrows which document the overlay applies to. When omitted, all patches in the file are context-free and each patch's selector alone identifies the element. Omitting target is only appropriate when the association between the overlay and its target definition file is established by external convention (e.g. a pipeline that always merges a fixed overlay into a fixed file). For all other cases, specifying target.ordId is strongly recommended to make patch resolution unambiguous.

Key fields on target:

Field	Purpose
`ordId`	Identifies the ORD resource whose attached definition file is being patched. Used together with `url` or `definitionType` to disambiguate.
`url`	Direct URL to the specific metadata definition file (e.g. an OpenAPI JSON file).
`definitionType`	Declares the format of the file (e.g. `openapi-v3`, `a2a-agent-card`). Disambiguates when a resource has multiple definitions attached.

Example of ambiguity: an OData API resource may expose both edmx and openapi-v3 definitions. Provide definitionType and/or url to make the concrete patch target explicit.

Selectors

Each patch identifies the element to patch using exactly one selector. Concept-level selectors are preferred over jsonPath because they are resilient to structural format changes (e.g. OpenAPI 3.0 → 3.1, OData CSDL XML → JSON).

Available selectors:

root: document-level metadata and top-level sections
operation: OpenAPI, MCP, A2A, OData Actions/Functions
entityType: OData EntityTypes, CSN Interop entities
complexType: OData ComplexTypes
enumType: OData EnumTypes
entitySet: OData EntitySets
namespace: OData Schema namespace
propertyType: OData/CSN properties (requires entityType, complexType, or enumType)
parameter: OData/OpenAPI parameters (requires operation)
returnType: OData return types (requires operation)
jsonPath: generic fallback for any JSON/YAML location

Use root for document-level merges such as OpenAPI info, components, or ORD top-level properties.

jsonPath follows RFC 9535. The jsonPath selector definition specifies the portable subset that every toolkit must support and portable overlays must use. Toolkits may support additional features as non-portable extensions.

See each selector's definition for detailed format mappings and usage.

Patch Actions

Each patch specifies an action, a selector, and a data value. The full semantics of each action (update, merge, remove) are defined on the action field.

Key points:

data is required for merge and update: remove omits data when the selected element should be removed entirely.
remove semantics:
- If the selector matches nothing, the action succeeds without changing the document because the requested absence already holds, and tooling should report a warning.
- Omit data to remove the entire selected element. The document root cannot be removed: root, or jsonPath: "$", with omitted data MUST error. Use update to replace the complete document explicitly. For EDMX, the selected structural element is preserved and its complete annotation set is removed.
- Provide data with null-valued properties to remove only those specific fields. Missing fields in a matched element are ignored. A removal mask MAY target the document root because it preserves the document itself.
- data MUST NOT be null, an empty object {}, or an empty array []; conformant tooling rejects these values.
merge behavior: arrays are appended, not replaced. To replace a selected array, use update. To replace an array-valued field while preserving its containing object, first remove the field with data: { "arrayField": null }, then merge the new value.
CSDL JSON concept selectors: merge, update, and data-bearing remove operate on annotations while preserving structural CSDL content. update replaces the selected target's complete annotation set. This exception does not apply to root or jsonPath, which retain generic structural semantics. Structural CSDL data supplied to an OData concept-level selector is an error.
Selector matches: a merge or update concept-level selector that matches nothing is an error. An unmatched remove succeeds without changing the document, which makes removal idempotent, and tooling should report a warning. All selectors, including the generic jsonPath, match only structure the target already declares; overlays do not create missing targets. A jsonPath selector may match zero or more elements. A zero-match jsonPath patch succeeds without changing the document and tooling should report a warning, regardless of the patch action. The patch applies to every element when jsonPath matches one or more. This is a deliberate limitation of this version because errors and warnings surface selector typos rather than silently authoring content. A future version may add a dedicated create action. See selector.
OData targets: overlays carry annotations in CSDL JSON @TermName form. EDMX targets are annotation-only: existing structure is annotated, new structural elements cannot be created, and jsonPath is unavailable for EDMX. OData v4 EDMX annotations use reconciled external <Annotations Target="..."> blocks. Applying overlays to OData v2 EDMX is out of scope and produces an error. An OData v4 EDMX document may describe the model of an OData v2 API and serve as the overlay target. For CSDL JSON, enum-member annotations are sibling keys on the enum type. Updating an enum member preserves its scalar value and replaces its sibling annotations. Removing an enum member without data removes both the member and its sibling annotations. See data.

Validation

Overlays assume the target document is already valid for its native format. Overlay tooling does not fully re-validate target formats. After applying an overlay, validate the merged output with the corresponding format-specific tooling. Overlay output is defined semantically, not byte-for-byte. Tooling may change insignificant formatting, object-property order, or XML-attribute order. Consumers MUST compare parsed content rather than serialized bytes unless a separate canonicalization profile is applied.

See Compatibility Expectations for rules on what overlays may and may not change.

Tooling

A reference implementation for merging, validating, and converting ORD Overlays is provided as a separate package. It supports all selector types and patch actions defined in this specification, including EDMX XML targets.

Additionally a set of React components for viewing Open Resource Discovery Overlay documents and a reusable library written in Go.

ORD Aggregator Expectations

An ORD Aggregator SHOULD enforce that overlay sources are permitted to patch the target metadata. Without such enforcement, consumers could be exposed to unauthorized metadata changes through overlay processing.

An ORD Aggregator SHOULD support merging ORD Overlays into the resource definitions centrally, so that individual consumers do not need to implement overlay processing themselves.

When an ORD Aggregator performs the merge, it SHOULD produce a new resource definition entry with the merged content. The new entry takes over the type from the original resource definition, the visibility from the overlay document, and the purpose from the overlay's definition entry.

Overlay Document Metadata

Note on perspective: unlike its use in ORD Documents (which scopes transport), perspective on an overlay declares where the patch should be applied — at system-type, system-version, or system-instance level. See the field description for details.

Outlook: Patching ORD Resource Metadata Directly

A future version of the ORD Overlay specification may introduce a dedicated ordId selector that allows patching ORD resource metadata itself (e.g. title, description, visibility, tags on an API Resource or Event Resource) without requiring a separate resource definition file as the patch target.

This capability is not included in version 0.1 to limit scope and allow the overlay model to mature on resource definition patching first. When introduced, it will enable use cases such as:

Enriching ORD resource descriptions or documentation links centrally
Adding classification tags or AI-related metadata at the ORD resource level
Adjusting visibility or lifecycle metadata through overlay governance workflows

Schema Definitions

The root schema of the document is ORD Overlay
The interface is available as JSON Schema: OrdOverlay.schema.json.

ORD Overlay

Type: Object($schema, ordOverlay, ordId, description, perspective, describedSystemType, describedSystemVersion, describedSystemInstance, visibility, target, patches, meta)

Property	Type	Description
$schema OPTIONAL	string	Optional URL to the ORD Overlay schema (defined as a JSON Schema). If provided, this enables code intelligence and validation in supported editors (like VSCode) and tools. JSON Schema Format: `uri-reference` Array Item Allowed Values (extensible): Any string of format `uri-reference` `"https://open-resource-discovery.org/spec-v1/interfaces/OrdOverlay.schema.json#"`
ordOverlay MANDATORY	string	Version of the ORD Overlay specification. Allowed Values: `"0.1"` Example Values: `"0.1"`
ordId OPTIONAL	string	Optional ORD ID of this overlay document. Regex Pattern: `^([a-z0-9]+(?:[.][a-z0-9]+)):(overlay):([a-zA-Z0-9._\-]+):(v0\|v[1-9][0-9])$` Maximum Length: `255` Example Values: `"sap.foo:overlay:astronomy-api-openapi:v1"`
description OPTIONAL	string	Optional description of the overlay document itself. Notated in CommonMark (Markdown). Minimum Length: `1` Example Values: `"This overlay adds descriptive metadata for AI use-cases\nwithout modifying the original resource definition.\n"`
perspective OPTIONAL	string	Overlay Perspective Overlay-specific perspective that scopes where this overlay should be applied. Use this together with `describedSystemType`, `describedSystemVersion`, and `describedSystemInstance` to describe whether the overlay applies broadly to a system type, to one released system version, or only to a specific system instance. Allowed Values: `"system-type"`: Applies the overlay at system-type level. Use this when the overlay should patch the same targeted resource across versions and instances of the same system type, typically for the same ORD resource major version. `describedSystemType` SHOULD be provided as the identifying context. `"system-version"`: Applies the overlay to one concrete system version. Use this when metadata differs between released versions and the patch should only affect a specific version of the target resource. `describedSystemVersion` SHOULD be provided, and `describedSystemType` SHOULD also be provided as parent context. `"system-instance"`: Applies the overlay to one concrete system instance / tenant. Use this when the patch reflects tenant-specific configuration, extensions, or runtime differences in the target metadata. `describedSystemInstance` SHOULD be provided. Example Values: `"system-type"` `"system-version"` `"system-instance"`
describedSystemType OPTIONAL	Overlay System Type	Information on the system type this overlay describes. This object is identical to the ORD Document `describedSystemType` object; see System Type. Its purpose is to link the overlay to the same system landscape model as ORD resources, if needed. This is the primary context object for `perspective: system-type`, and also the parent context for more specific `system-version` and `system-instance` overlays. Usually this is not necessary for static overlays if the patched resource is already selected via ORD ID.
describedSystemVersion OPTIONAL	Overlay System Version	Information on the system version this overlay describes. This object is identical to the ORD Document `describedSystemVersion` object; see System Version. Its purpose is to link the overlay to the same system landscape model as ORD resources, if needed. Use this when the overlay should only patch metadata for one specific released system version. Usually this is not necessary for static overlays if the patched resource is already selected via ORD ID.
describedSystemInstance OPTIONAL	Overlay System Instance	Information on the system instance this overlay describes. This object is identical to the ORD Document `describedSystemInstance` object; see System Instance. Its purpose is to link the overlay to the same system landscape model as ORD resources, if needed. Use this when the overlay should only patch metadata for one concrete tenant / runtime instance. Usually this is not necessary for static overlays if the patched resource is already selected via ORD ID.
visibility OPTIONAL	string	Overlay Visibility Controls which consumers can discover and access this overlay document. It does NOT control runtime access to the resources being patched — that is managed separately through authentication and authorization mechanisms. Use this to prevent exposing internal overlay enrichments to inappropriate consumer audiences. Allowed Values: `"public"`: The overlay can be discovered and accessed by anyone, including customers, partners, and unauthenticated external parties. `"internal"`: The overlay can only be discovered and accessed by vendor internal consumers (e.g. applications or services of the same vendor). MUST NOT be made available to external parties or vendor customers. `"private"`: 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 OPTIONAL	Overlay Target	Optional target context identifying the resource or definition file being patched. See Overlay Target for details on identifier requirements and disambiguation.
patches MANDATORY	Array<Overlay Patch>	Ordered sequence of patches to apply to the targeted resource(s). Patches are applied strictly in the order they are listed. If two patches target the same document element, both are applied in sequence — the later patch supersedes the earlier one. Array Constraint: MUST have at least 1 items
meta OPTIONAL	Overlay Meta	Optional arbitrary metadata associated with this overlay document for use by overlay consumers, tooling, and registries. The contents of this block are never applied to the target document — they are strictly out-of-band and ignored by the patch merge process. Use this to carry document-level information such as provenance, approval status, or processing instructions that apply to the overlay as a whole rather than to individual patches.

Overlay Target

Optional context about the target being patched. The target can refer to an ORD resource or to a referenced resource definition file.

When this object is present, at least one of ordId, url, correlationIds, or definitionType MUST be provided so that consumers can identify what is being patched. ordId identifies the ORD resource whose attached definition file is being patched. Use url and/or definitionType to disambiguate which definition file to target.

Example: one OData API resource can have both edmx and openapi-v3 definitions attached. In such cases, provide definitionType and/or url to make the concrete patch target explicit.

Multiple identifiers, if provided, are treated as all pointing to the same resource.

Use systemInstance to further scope the target to a specific system instance (tenant). This is relevant when perspective: system-instance is set and the same ORD resource exists across multiple tenants.

Type: Object(ordId, url, correlationIds, definitionType, systemInstance)

Property	Type	Description
ordId OPTIONAL	string	ORD ID of the target being patched (e.g. an API Resource, Event Resource, Data Product). MUST be a valid ORD ID. Regex Pattern: `^([a-z0-9]+(?:[.][a-z0-9]+)):([a-zA-Z0-9.\-]+):([a-zA-Z0-9.\-]+):(v0\|v[1-9][0-9])$` Maximum Length: `255` Example Values: `"sap.s4:apiResource:OP_API_BUSINESS_PARTNER_SRV:v1"`
url OPTIONAL	string	URL or URI pointing directly to the file being patched. This is typically a resource definition file (e.g. OpenAPI, AsyncAPI, OData CSDL), but can also point to any JSON/YAML-based target document. JSON Schema Format: `uri-reference` Example Values: `"https://example.com/api/openapi.json"` `"./openapi.yaml"`
correlationIds OPTIONAL	Array<string>	Correlation IDs referencing the target resource in external registries or systems of record. Reuses the ORD correlation ID format: `namespace:type:localId`. All listed IDs are treated as pointing to the same resource. Array Constraint: MUST have at least 1 items Array Item Regex Pattern: `^([a-z0-9]+(?:[.][a-z0-9]+)):([a-zA-Z0-9.\-\/]+):([a-zA-Z0-9.\-\/]+)$` Example Values*: `["sap.s4:communicationScenario:SAP_COM_0008"]`
definitionType OPTIONAL	string	Overlay Definition Type Optional, but RECOMMENDED type of the target definition being patched. If provided, this SHOULD match the `type` of the referenced metadata definition (as used in API/Event/Capability resource definitions). This is especially useful when target `ordId` resolves to a resource with multiple attached definitions. This can be used to disambiguate how selectors are interpreted for the target. MUST be either: - any valid Specification ID, or - one of the pre-defined values reused from: - API Resource Definition `type` - Event Resource Definition `type` - Capability Definition `type` The literal value `custom` is deprecated for `definitionType` and MUST NOT be used. In such cases, use a concrete Specification ID instead. Array Item Allowed Values (extensible): Any string: Any valid Specification ID. `"openapi-v2"` `"openapi-v3"` `"openapi-v3.1+"` `"raml-v1"` `"edmx"` `"csdl-json"` `"graphql-sdl"` `"wsdl-v1"` `"wsdl-v2"` `"a2a-agent-card"` `"sap-rfc-metadata-v1"` `"sap-sql-api-definition-v1"` `"sap-csn-interop-effective-v1"` `"asyncapi-v2"` `"sap.mdo:mdi-capability-definition:v1"` Example Values: `"openapi-v3"` `"asyncapi-v2"` `"sap.mdo:mdi-capability-definition:v1"`
systemInstance OPTIONAL	Overlay System Instance	Optional system instance (tenant) context for the target. Use this to scope the patch to a specific running instance of the system, e.g. when `perspective: system-instance` is set and the same ORD resource exists across multiple tenants. Note: if the entire overlay applies to one tenant, the document-level `describedSystemInstance` is sufficient and `target.systemInstance` can be omitted. Example Values: `{"localId":"LocalTenantId123"}` `{"correlationIds":["sap.cld:tenant:741234567"]}`

Overlay Patch

A single patch action to apply to the element identified by the Overlay Selector.

Type: Object(description, action, selector, data, tags, meta)

Property	Type	Description
description OPTIONAL	string	Optional human-readable note explaining the purpose or rationale of this individual patch. This field is purely informational and has no effect on patch application. Typical use-cases: - Reviewer / audit notes explaining why a particular element is being modified. - Commit-message style annotations generated by AI tooling (e.g. "Enriched summary for GetUser operation"). - References to tickets or decisions that motivated the change. Maps 1:1 to the `actions[].description` field in the OpenAPI Overlay spec, enabling lossless round-trip conversion between OpenAPI overlays and ORD overlays. Example Values: `"Added missing description for the pagination parameters."` `"Marked as deprecated following platform v3 migration."` `"JIRA-1234: Corrected return type description."`
action MANDATORY	string	Overlay Patch Action The patch operation to perform on the selected element. Allowed Values: `"update"`: Replace the selected element entirely with `data`. For CSDL JSON, an update using an OData concept-level selector preserves the selected structural element and replaces its complete annotation set. This exception does not apply to `root` or `jsonPath`, which retain whole-element replacement semantics. For EDMX, the selected structural element is preserved and `data` replaces its complete annotation set. `"remove"`: Remove the selected element or specific fields within it. If the selector matches nothing, the action succeeds without changing the document because the requested absence already holds. Tooling SHOULD report a warning. - When `data` is omitted: remove the selected element from the document entirely. The document root cannot be removed: when the selector resolves to the root (`root`, or `jsonPath: "$"`), the patch MUST error. Use `update` to replace the complete document explicitly. For EDMX, the selected structural element is preserved and all annotations on it are removed. - When `data` is provided: remove only the fields or array entries marked by the removal mask. For object masks, properties with `null` values are removed recursively. This uses JSON Merge Patch-style delete semantics where `null` indicates deletion. Nested `null` values remove nested fields as well. A field or array entry that is absent from a matched element is ignored; it does not make the selector unmatched. A removal mask MAY target the document root because it preserves the document itself. `"merge"`: Deep-merge `data` into the selected element. - Objects are deep-merged recursively. - Scalar values are overwritten by the value from `data`. - Arrays are appended (new array items are added after existing items). - Existing object properties not mentioned in `data` are preserved. - For OData annotations (keyed `@TermName`, optionally with a qualifier), an annotation with the same term-plus-qualifier identity is replaced rather than duplicated. A target carries at most one annotation per term-plus-qualifier identity.
selector MANDATORY	Overlay Selector	Identifies the element in the target to patch. Exactly one selector type is used per patch. Prefer concept-level selectors over generic `jsonPath` where possible, as they are resilient to structural changes in the target format. Selector behavior: - All selectors match only structure the target already declares. Overlays patch what exists; they do not synthesize the selected element. This includes `jsonPath`, which MUST NOT create a missing target. - A `merge` or `update` patch whose concept-level selector matches nothing MUST error. An unmatched `remove` patch succeeds without changing the document, which makes removal idempotent, and tooling SHOULD report a warning. (`root` always resolves, so this cannot arise for `root`.) - A `jsonPath` selector MAY match zero or more elements. When it matches nothing, the patch succeeds without changing the document and tooling SHOULD report a warning, regardless of the patch action. When it matches one or more elements, all locations are identified before mutation and the patch is applied exactly once to every matched location. - This is a deliberate limitation of this version: there is no create-on-missing behavior. Errors and warnings surface selector typos and wrong assumptions about the target structure instead of silently authoring unintended content. A future version MAY add a dedicated create action if a concrete use case requires it.
data OPTIONAL	Overlay Patch Value	The value used by the patch action. REQUIRED for `merge` and `update`. OPTIONAL for `remove`; omit `data` to remove the selected element entirely. The interpretation of this value depends on the patch `action`.
tags OPTIONAL	Array<string>	String labels associated with the patched element. Useful for classification, domain tagging, and filtering in registries or tooling. These are purely informational and have no effect on patch application or on the target document. Array Constraint: MUST have at least 1 items Example Values: `["HR","Employee","Core"]` `["deprecated","migration-v3"]`
meta OPTIONAL	Overlay Meta	Optional arbitrary metadata associated with this specific patch for use by overlay consumers, tooling, and registries. The contents of this block are never applied to the target document — they are strictly out-of-band and ignored by the patch merge process. Use this to carry information that enrichment sources associate with a specific patched element but that has no standard representation in the target metadata format.

Overlay Meta

Optional arbitrary metadata for use by overlay consumers, tooling, and registries. The contents of this block are never applied to the target document — they are strictly out-of-band and ignored by the patch merge process.

When used at the document level, this carries information about the overlay as a whole (e.g. provenance, approval status, processing instructions). When used at the patch level, this carries information specific to the patched element (e.g. confidence scores, source references).

This is an open/extensible object — any properties are allowed.

Example Values:

{
  "sourceSystem": "AI Enrichment Pipeline v2.1",
  "enrichmentDate": "2026-04-01"
}

{
  "someMetadataKey": {
    "complex": "object"
  }
}

Overlay Selector

Identifies the element in the target to patch. Exactly one selector type is used per patch.

Prefer concept-level selectors over generic jsonPath where possible, as they are resilient to structural changes in the target format.

Selector behavior:

All selectors match only structure the target already declares. Overlays patch what exists; they do not synthesize the selected element. This includes jsonPath, which MUST NOT create a missing target.
A merge or update patch whose concept-level selector matches nothing MUST error. An unmatched remove patch succeeds without changing the document, which makes removal idempotent, and tooling SHOULD report a warning. (root always resolves, so this cannot arise for root.)
A jsonPath selector MAY match zero or more elements. When it matches nothing, the patch succeeds without changing the document and tooling SHOULD report a warning, regardless of the patch action. When it matches one or more elements, all locations are identified before mutation and the patch is applied exactly once to every matched location.
This is a deliberate limitation of this version: there is no create-on-missing behavior. Errors and warnings surface selector typos and wrong assumptions about the target structure instead of silently authoring unintended content. A future version MAY add a dedicated create action if a concrete use case requires it.

Overlay Selector By Root

Type: Object(root)

Property	Type	Description
root MANDATORY	boolean	Concept-level selector targeting the root of the document being patched. MUST be `true`. Use this selector to patch top-level properties of any JSON/YAML-based metadata format without coupling to specific structural paths. This is especially useful for: - Patching document-level metadata (title, description, version, contact info) - Adding or merging top-level sections (e.g. `components`, `tags`, `servers` in OpenAPI) - Extending the root object with new properties across format versions Supported metadata formats and typical use cases: OpenAPI (`openapi-v2`, `openapi-v3`, `openapi-v3.1+`): - Patch `info.description`, `info.title`, `info.contact` - Add `components.securitySchemes` or `components.schemas` - Add `tags`, `servers`, or `externalDocs` AsyncAPI (`asyncapi-v2`): - Patch `info` block, `servers`, `channels` at the root OData CSDL JSON (`csdl-json`): - Patch root-level `$Version`, `$EntityContainer`, or add namespace objects MCP / A2A (any Specification ID): - Patch top-level metadata or add root-level tool/skill definitions The `root` selector is equivalent to `jsonPath: "$"` but is preferred because it explicitly communicates intent and is resilient to format differences where `$` might have ambiguous semantics. Constant Value: `true`

Example Values:

{
  "root": true
}

Overlay Selector By JsonPath

Type: Object(jsonPath)

Property	Type	Description
jsonPath MANDATORY	string	JSONPath expression targeting any location in a JSON/YAML-based target document. MUST start with `$`. This is the generic structural fallback selector, supported for all JSON/YAML-based formats: - `openapi-v2`, `openapi-v3`, `openapi-v3.1+`: targets any node in the OpenAPI document. - `a2a-agent-card`: targets any node in the A2A Agent Card JSON document. - `csdl-json`: targets any node in the OData CSDL JSON document. - MCP (any Specification ID): targets any node in the MCP-compatible JSON/YAML tool metadata. JSONPath syntax and evaluation follow RFC 9535. Every conforming toolkit MUST support this portable subset: - the root identifier `$`; - child-name selectors in dot notation or single-quoted or double-quoted bracket notation; - array selectors using non-negative indices; - object and array wildcards; - selector lists containing distinct member names or distinct non-negative array indices; and - array slices whose bounds are omitted or non-negative and whose step is omitted or positive. A portable ORD Overlay MUST NOT use JSONPath features outside this subset. Toolkits MAY support additional RFC 9535 features or implementation-specific extensions, but overlays using them are implementation-specific and not portable. A toolkit that does not support an expression MUST report an error and MUST NOT treat the expression as matching zero elements. Use concept-level selectors (`operation`, `entityType`, etc.) when available, as they are resilient to structural differences between format versions. Reserve `jsonPath` for cases where no concept-level selector covers the target location. Regex Pattern: `^\$` Minimum Length: `1` Example Values: `"$.info.description"` `"$.paths['/constellations'].get"` `"$.servers[*]"` `"$.tags[0,2]"` `"$.items[1:5:2]"`

Example Values:

{
  "jsonPath": "$.info.description"
}

{
  "jsonPath": "$.paths['/constellations'].get"
}

Overlay Selector By Operation

Type: Object(operation)

Property	Type	Description
operation MANDATORY	string	Concept-level operation identifier. Supported mappings by format: - OpenAPI (`openapi-v2`, `openapi-v3`, `openapi-v3.1+`): maps to the `operationId` field on an HTTP operation inside `paths.{path}.{method}`. - MCP (any Specification ID other than `a2a-agent-card`): maps to `tools[].name`. See: https://modelcontextprotocol.io/specification/2025-11-25/schema#tool-name - A2A Agent Card (`a2a-agent-card`): maps to `skills[].id`. See: https://a2a-protocol.org/latest/specification/#445-agentskill - OData (`edmx`, `csdl-json`): maps to the Action or Function name at Schema level. MUST use either the namespace-qualified name (e.g. `OData.Demo.Approval`) or its namespace-qualified signature (e.g. `OData.Demo.Approval(Edm.Int32,Edm.String)`). For OData v2 `edmx` targets: also searches FunctionImport elements in EntityContainer when a selector without a signature matches no Schema-level Action or Function. A signature selector MUST NOT match a FunctionImport. A namespace-qualified name without a signature is sufficient only when it identifies exactly one Action, Function or Function Import. Otherwise, the selector MUST use a signature containing every declared parameter type in declaration order, including the binding parameter of a bound operation. Signature matching uses exact parameter count, order, and types. Empty parentheses select a zero-parameter operation, so `OData.Demo.Ping()` is distinct from the name-only selector `OData.Demo.Ping`. When `definitionType` is set on `target`, the format is known and the selector resolves unambiguously. When `definitionType` is absent, the implementation SHOULD infer the format from the target document's content (e.g. the `openapi` field, `$schema`, or `$kind` markers). Minimum Length: `1` Example Values: `"getConstellationByAbbreviation"` `"dispute-case-resolution"` `"OData.Demo.Approval"` `"OData.Demo.Rejection"` `"getCompensationHistory"` `"OData.Demo.Approval(Edm.Int32,Edm.String)"`

Example Values:

{
  "operation": "getConstellationByAbbreviation"
}

{
  "operation": "OData.Demo.Approval"
}

{
  "operation": "dispute-case-resolution"
}

Overlay Selector By Entity Type

Type: Object(entityType)

Property	Type	Description
entityType MANDATORY	string	OData-specific selector targeting an EntityType element by its namespace-qualified name. An EntityType in OData is a structured type with a key that represents a business entity (e.g. `Customer`, `Order`, `Employee`). This maps to: - `edmx` (OData v2/v4 CSDL XML): targets `<EntityType Name="...">` elements in the Schema. - `csdl-json` (OData v4 CSDL JSON): targets elements with `$Kind: "EntityType"`. MUST use the namespace-qualified name (e.g. `OData.Demo.Customer`) for unambiguous resolution. For EntitySet-level patching (Capabilities annotations), use the `entitySet` selector instead. For CSN Interop targets (`sap-csn-interop-effective-v1`), this selector targets a `definitions` entry by its fully qualified key (e.g. `AirlineService.Airline`). To target ComplexType or EnumType elements, use the dedicated `complexType` or `enumType` selectors. Minimum Length: `1` Example Values: `"OData.Demo.Customer"` `"OData.Demo.LeaveRequest"` `"AirlineService.Airline"`

Example Values:

{
  "entityType": "OData.Demo.Customer"
}

{
  "entityType": "AirlineService.Airline"
}

Overlay Selector By Complex Type

Type: Object(complexType)

Property	Type	Description
complexType MANDATORY	string	OData-specific selector targeting a ComplexType element by its namespace-qualified name. A ComplexType in OData is a structured type without a key, typically used for reusable embedded structures like addresses, coordinates, or measurement values. This maps to: - `edmx` (OData v2/v4 CSDL XML): targets `<ComplexType Name="...">` elements in the Schema. - `csdl-json` (OData v4 CSDL JSON): targets elements with `$Kind: "ComplexType"`. MUST use the namespace-qualified name (e.g. `OData.Demo.Address`) for unambiguous resolution. ComplexTypes are often shared across multiple EntityTypes, so patching a ComplexType affects all usages of that type throughout the service. Minimum Length: `1` Example Values: `"OData.Demo.Address"` `"OData.Demo.GeoLocation"` `"API_BUSINESS_PARTNER.A_AddressEmailAddress"`

Example Values:

{
  "complexType": "OData.Demo.Address"
}

Overlay Selector By Enum Type

Type: Object(enumType)

Property	Type	Description
enumType MANDATORY	string	OData-specific selector targeting an EnumType element by its namespace-qualified name. An EnumType in OData is an enumeration type with named members representing a fixed set of values (e.g. `OrderStatus`, `Priority`, `Gender`). This maps to: - `edmx` (OData v2/v4 CSDL XML): targets `<EnumType Name="...">` elements in the Schema. - `csdl-json` (OData v4 CSDL JSON): targets elements with `$Kind: "EnumType"`. MUST use the namespace-qualified name (e.g. `OData.Demo.OrderStatus`) for unambiguous resolution. To patch individual enum members, use the `propertyType` selector with this `enumType` as context. Minimum Length: `1` Example Values: `"OData.Demo.OrderStatus"` `"OData.Demo.Priority"` `"SAP.Common.ApprovalStatus"`

Example Values:

{
  "enumType": "OData.Demo.OrderStatus"
}

Overlay Selector By Property Type

Type: Object(propertyType, entityType, complexType, enumType)

Property	Type	Description
propertyType MANDATORY	string	Concept-level property, navigation property, or enum member identifier. Use the unqualified property name (e.g. `BirthDate`, `Street`, `Pending`). Property names are frequently reused across types, so a parent type context MUST be provided via exactly one of: `entityType`, `complexType`, or `enumType`. Supported metadata formats: - `edmx` (OData v2/v4 CSDL XML): targets a Property or NavigationProperty on an EntityType or ComplexType; or a Member on an EnumType. - `csdl-json` (OData v4 CSDL JSON): targets non-`$`-prefixed keys on the matched type object. - `sap-csn-interop-effective-v1` (CSN Interop): targets an entry in the `elements` map of the matched entity definition. Use `entityType` for CSN Interop targets. Minimum Length: `1` Example Values: `"BirthDate"` `"Street"` `"Pending"` `"AirlineID"`
entityType OPTIONAL	string	Parent EntityType context for the property. Use this when targeting a property on an EntityType. MUST be the namespace-qualified name (e.g. `OData.Demo.Customer`). For CSN Interop: the fully qualified `definitions` key (e.g. `AirlineService.Airline`). Exactly one of `entityType`, `complexType`, or `enumType` MUST be provided. Minimum Length: `1` Example Values: `"OData.Demo.Customer"` `"AirlineService.Airline"`
complexType OPTIONAL	string	OData-specific parent ComplexType context for the property. Use this when targeting a property on a ComplexType. MUST be the namespace-qualified name (e.g. `OData.Demo.Address`). Exactly one of `entityType`, `complexType`, or `enumType` MUST be provided. Minimum Length: `1` Example Values: `"OData.Demo.Address"` `"OData.Demo.GeoLocation"`
enumType OPTIONAL	string	OData-specific parent EnumType context for the enum member. Use this when targeting a member of an EnumType. MUST be the namespace-qualified name (e.g. `OData.Demo.OrderStatus`). Exactly one of `entityType`, `complexType`, or `enumType` MUST be provided. Minimum Length: `1` Example Values: `"OData.Demo.OrderStatus"` `"OData.Demo.Priority"`

Example Values:

{
  "propertyType": "BirthDate",
  "entityType": "OData.Demo.Customer"
}

{
  "propertyType": "Street",
  "complexType": "OData.Demo.Address"
}

{
  "propertyType": "Pending",
  "enumType": "OData.Demo.OrderStatus"
}

Overlay Selector By Entity Set

Type: Object(entitySet)

Property	Type	Description
entitySet MANDATORY	string	Concept-level entity set identifier. Supported metadata formats: - `edmx` (OData v2/v4 CSDL XML): targets an EntitySet element inside EntityContainer. - `csdl-json` (OData v4 CSDL JSON): targets a key with `$Collection: true` inside the EntityContainer object in the namespace. Use `entitySet` when you need to patch EntityContainer-bound metadata such as Capabilities annotations (InsertRestrictions, UpdateRestrictions, etc.). You MAY use an unqualified name if unique (e.g. `Customers`). If not unique a fully-qualified name (e.g. `OData.Demo.Customers`) MUST be used. For patching EntityType structure (Properties, NavigationProperties) via deep merge, use `entityType`. To target a specific property for fine-grained patching, prefer `propertyType` (requires `entityType` as context). Minimum Length: `1` Example Values: `"Customers"` `"SalesOrders"` `"EmployeeSet"` `"OData.Demo.Customers"`

Overlay Selector By Namespace

Type: Object(namespace)

Property	Type	Description
namespace MANDATORY	string	Concept-level OData schema/namespace selector. Supported metadata formats: - `edmx` (OData v2/v4 CSDL XML): targets the `<Schema Namespace="...">` element. Use the namespace value exactly as declared (e.g. `com.example.OrderService`). - `csdl-json` (OData v4 CSDL JSON): targets the namespace-level object (the non-`$`-prefixed key in the CSDL JSON document that matches the namespace value). Use this selector for service/schema-level annotations such as `@Core.Description` and `@Core.LongDescription` on the OData service as a whole. Minimum Length: `1` Example Values: `"com.example.OrderService"` `"SFSF.EC.Compensation"` `"API_BUSINESS_PARTNER"`

Overlay Selector By Parameter

Type: Object(parameter, operation)

Property	Type	Description
parameter MANDATORY	string	Concept-level parameter name. Supported metadata formats: - `edmx` (OData v2/v4 CSDL XML): targets a `<Parameter Name="...">` child element on an Action, Function, or FunctionImport. Use the unqualified parameter name. - `csdl-json` (OData v4 CSDL JSON): targets an entry in the `$Parameter` array of an Action/Function overload whose `$Name` matches. - OpenAPI (`openapi-v2`, `openapi-v3`, `openapi-v3.1+`): targets an entry in the `parameters` array of the operation identified by `operation` (operationId), matching by the parameter `name` field. `operation` MUST always accompany this field to unambiguously identify the owning operation. Minimum Length: `1` Example Values: `"employeeId"` `"Count"` `"filter"`
operation MANDATORY	string	Required operation context for the selected parameter. - For OData: use the same namespace-qualified name or exact signature syntax as the `operation` selector. When the operation is overloaded, the signature MUST identify one overload before `parameter` is resolved. - For OpenAPI: the `operationId` of the HTTP operation. Minimum Length: `1` Example Values: `"com.example.Svc.TerminateEmployee"` `"getConstellationByAbbreviation"`

Overlay Selector By Return Type

Type: Object(returnType, operation)

Property	Type	Description
returnType MANDATORY	boolean	Flag indicating that the return type of the specified operation is the target. MUST be `true`. Use `operation` to identify the owning operation. Supported metadata formats: - `edmx` (OData v2/v4 CSDL XML): targets the `<ReturnType>` child element of the matched Action or Function element. - `csdl-json` (OData v4 CSDL JSON): targets the `$ReturnType` object inside the matched Action/Function overload array entry. Constant Value: `true`
operation MANDATORY	string	Namespace-qualified Action or Function whose return type is targeted. Use the same name or exact signature syntax as the `operation` selector. When the operation is overloaded, the signature MUST identify one overload before its return type is resolved. Minimum Length: `1` Example Values: `"com.example.Svc.TerminateEmployee"` `"com.example.Svc.GetDirectReports"`

Overlay Patch Value

The value used by the patch action. Structure depends on the target being patched and the action type.

For OData targets (edmx, csdl-json), the value MUST be expressed in CSDL JSON annotation format. Annotation keys use the @TermName convention: e.g. { "@Core.Description": "...", "@Core.Revisions": [...] }. For OData v4 EDMX XML, the merge implementation converts this to <Annotation> elements and writes them as external targeting (<Annotations Target="Qualified.Name/path"> blocks at the schema level), reconciling with any annotations already present for the same target so that a given target's annotations are never split across inline and external locations. Applying overlays to OData v2 EDMX XML is out of scope, and tooling MUST report an error. As a workaround, an OData v4 EDMX document MAY describe the model of an OData v2 API and serve as the overlay target. Target identifiers use OData CSDL target syntax: Namespace.Type for types, the namespace name itself for namespace selectors, Namespace.Type/Member for properties and enum members, Namespace.Container/Member for entity sets and FunctionImports, and Namespace.Operation(Type,...) for Actions and Functions. Operation targets always include every declared parameter type, including the binding parameter. Parameter and return-type targets append /<parameter-name> and /$ReturnType, respectively. See: https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html

EDMX targets are annotation-only: overlays add, replace, or remove annotations on structure that already exists in the source schema. They cannot create new structural elements (EntityType, EntitySet, Property, Function/Action, EnumType, ComplexType), and jsonPath is not available for EDMX. New structure belongs in the source CSDL/CDS, not in an overlay. For EDMX, merge replaces annotations with the same term-plus-qualifier identity and preserves all others; update replaces the selected target's complete annotation set; and remove with omitted data removes that complete annotation set while preserving the structural target.

For CSDL JSON, enum-member annotations are carried as sibling keys on the enum type ("Read@Core.Description"), because an enum member is a scalar value that cannot itself hold annotation properties. merge adds or replaces the supplied sibling annotations while preserving the member value and other annotations. update preserves the member value and replaces that member's complete annotation set. remove with data removes the specified sibling annotations, while remove with omitted data removes the member and all of its sibling annotations.

For CSDL JSON, merge, update, and data-bearing remove patches that use an OData concept-level selector (operation, entityType, complexType, enumType, propertyType, entitySet, namespace, parameter, or returnType) operate on annotations rather than structural CSDL content. Their data MAY use member names to nest annotation payloads for those members, but MUST NOT use $-prefixed control properties or other non-annotation values to replace structural content. Tooling MUST report such structural data as an error rather than silently ignoring it. root and jsonPath selectors retain the generic structural action semantics.

For CSN Interop targets (sap-csn-interop-effective-v1), the value is plain CSN JSON merged directly into the matched entity definition or element object. Use the CSN doc field for human-readable descriptions, and @AnnotationName keys for vocabulary annotations (e.g. @EndUserText.label, @Semantics.text). See: https://sap.github.io/csn-interop-specification/

Type: object,array,string,number,boolean,null

Overlay System Instance

A system instance is a concrete, running instance of a system type. This object is identical to the ORD Document describedSystemInstance object; see System Instance.

Its purpose is to link the overlay to the same system landscape model as ORD resources, if needed. Usually this is not necessary for static overlays if the patched resource is already selected via ORD ID.

Type: Object(baseUrl, localId, correlationIds)

Property	Type	Description
baseUrl OPTIONAL	string	Optional base URL of the system instance. By providing the base URL, relative URLs in the overlay are resolved relative to it. The `baseUrl` MUST NOT contain a trailing slash. JSON Schema Format: `uri-reference` Regex Pattern: `^http[s]?:\/\/[^:\/\s]+\.[^:\/\s\.]+(:\d+)?(\/[a-zA-Z0-9-\._~]+)$` Example Values*: `"https://example-sap-system.com"` `"https://sub.foo.bar.com/api/v1"`
localId OPTIONAL	string	Optional local ID for the system instance (usually tenant ID), as known by the described system. Maximum Length: `255` Example Values: `"LocalTenantId123"`
correlationIds OPTIONAL	Array<string>	Correlation IDs for linking this system instance to external systems of record. Array Constraint: MUST have at least 1 items Array Item Regex Pattern: `^([a-z0-9]+(?:[.][a-z0-9]+)):([a-zA-Z0-9.\-\/]+):([a-zA-Z0-9.\-\/]+)$` Example Values*: `["sap.cld:tenant:741234567"]`

Overlay System Type

A system type is the abstract type of an application or service, from operational perspective. This object is identical to the ORD Document describedSystemType object; see System Type.

Type: Object(systemNamespace, correlationIds)

Property	Type	Description
systemNamespace OPTIONAL	string	The system namespace is a unique identifier for the system type. Regex Pattern: `^[a-z0-9]+(?:[.][a-z0-9]+){1}$` Maximum Length: `32` Example Values: `"sap.s4"` `"sap.c4c"` `"sap.cld"`
correlationIds OPTIONAL	Array<string>	Correlation IDs for linking this system type to external systems of record. Array Constraint: MUST have at least 1 items Array Item Regex Pattern: `^([a-z0-9]+(?:[.][a-z0-9]+)):([a-zA-Z0-9.\-\/]+):([a-zA-Z0-9.\-\/]+)$` Example Values*: `["sap.cld:systemRole:S4_PC"]`

Overlay System Version

A system version describes a version/release of the system. This object is identical to the ORD Document describedSystemVersion object; see System Version.

Type: Object(version, title, correlationIds)

Property	Type	Description
version OPTIONAL	string	The version of the system instance (run-time) or the version of the described system-version perspective. It MUST follow the Semantic Versioning 2.0.0 standard. Regex 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-]+)))?$` Example Values*: `"1.2.3"` `"2024.8.0"`
title OPTIONAL	string	Human-readable title of the system version. Minimum Length: `1` Maximum Length: `255` Example Values: `"SAP S/4HANA Cloud 2408"`
correlationIds OPTIONAL	Array<string>	Correlation IDs for linking this system version to external systems of record. Array Constraint: MUST have at least 1 items Array Item Regex Pattern: `^([a-z0-9]+(?:[.][a-z0-9]+)):([a-zA-Z0-9.\-\/]+):([a-zA-Z0-9.\-\/]+)$` Example Values*: `["sap.cld:release:2408"]`

Appendix

Tips: Inline Property Merging for OData Targets

When patching OData metadata (EDMX or CSDL JSON), properties can be annotated inline within their parent entity type, complex type, or enum type patch instead of using separate propertyType selector patches:

{
  "selector": { "entityType": "OData.Demo.Customer" },
  "action": "merge",
  "data": {
    "@Core.Description": "Entity description",
    "Name": {
      "@Core.Description": "Customer name"
    },
    "Email": {
      "@Core.Description": "Email address"
    }
  }
}

This inline approach:

reduces the number of patches
keeps related annotations together
improves readability by showing the entity structure
works for entityType, complexType, and enumType selectors

Deep Dive: Overlays vs. Resource Definition Visibility

When additional metadata should only be visible to a narrower audience, two main approaches exist:

publish a separate overlay that patches the target metadata for that audience
publish multiple resource definitions of the same resource with different API Resource Definition visibility settings

These approaches solve different problems:

resource-definition visibility controls who can access a concrete published definition file
overlays add another metadata layer without modifying the original source

Prefer overlays when

the enrichment is owned by a different team than the team publishing the base resource definition
the enrichment has a different lifecycle, approval workflow, or release cadence
the enrichment should be optional and separable from the original source
multiple parallel enrichments may exist for different consumers or use cases
the original source format should remain untouched, for example because it is generated elsewhere or mirrored from another system

Prefer multiple resource definitions with different visibility when

the same producer team owns both the public and internal metadata
the enriched information is part of the authoritative source and should not drift from it
full consumer compatibility is required without assuming overlay support
the difference is primarily "what full definition should this audience receive?" rather than "what extra layer should be applied afterward?"
the provider already has a reliable publishing pipeline for separate public/internal definition artifacts

Main tradeoff

overlays improve separation of concerns, but they add a second source of truth and may create ordering, sync, and provenance questions
duplicated resource definitions reduce consumer complexity and stay self-contained, but they increase publisher-side duplication and consistency obligations
both approaches can be combined: a narrower-visibility definition may still be enriched further via overlay

Rule of thumb:

use resource-definition visibility for authoritative producer-owned variants
use overlays for additive, externally managed, or use-case-specific enrichment layers

Deep Dive: ORD Document Resource vs. Attached Resource Definition

Overlays can be distributed either as a standalone OrdOverlayResource in an ORD Document or by attaching them as ord:overlay:v1 resource definitions to an API or Event resource. Those options are not interchangeable in practice, because they imply different ownership and publication models.

The strongest discriminator is ownership: if the overlay is created by a different ORD Provider than the one describing the target resource, there is in practice no way to attach that overlay as a resource definition of the foreign resource. In that case, distributing it as an OrdOverlayResource in a separate ORD Document is the viable option.

Prefer an ORD Document Resource when

the overlay is created by someone other than the original resource provider
the overlay is cross-cutting and applies to multiple resources
the overlay should be published independently from the lifecycle of one concrete API or Event resource
the overlay provider needs its own publication channel and cannot modify the target resource entry

Prefer attaching as a resource definition when

the same ORD Provider owns both the target resource and the overlay
the overlay belongs to the resource as part of the producer-owned metadata package
consumers should discover the overlay directly next to the resource definition it patches
the overlay lifecycle is tightly coupled to one specific API or Event resource
the producer wants the co-location to be explicit in the resource metadata itself

Main tradeoff

ORD Document Resources are more flexible for independent publishers, cross-resource overlays, and separate release cycles
attached resource definitions are easier to understand when the overlay is just another producer-owned artifact of the same resource
ORD Document Resources make provenance and authorization more important, because overlays may come from outside the original resource provider
attached overlays reduce indirection, but only work when the publisher controls the target resource entry

Rule of thumb:

use attached resource definitions for producer-owned, resource-local overlays
use ORD Document Resources for externally managed, cross-resource, or independently versioned overlays

Compatibility Expectations

Overlays SHOULD NOT change the target in incompatible ways. The typical use case is enrichment: adding information that helps consumers better discover or understand the described resources. An overlay may also add machine-readable metadata that specific use cases require (hinted at via purpose).

In some cases it is acceptable to remove parts of the metadata — for example when the intended consumer (again guided by purpose) should not see information that is irrelevant or confusing in their context.

As a general rule, the result after applying an overlay SHOULD be a compatible variant of the original: either an enriched superset or a valid subset, but not a contradictory or structurally incompatible.

Examples of changes that are typically appropriate:

Adding or improving descriptions, summaries, or documentation links
Adding annotations or tags for classification, AI grounding, or search
Adding metadata required by a specific consumer scenario (e.g. capability annotations)
Removing fields that are irrelevant to a narrower audience

Examples of changes that are typically inappropriate:

Changing identity fields (ordId, version, resource type)
Altering the structural contract in ways that break existing consumers (e.g. removing required properties from a schema, changing field types)
Contradicting the original meaning of the resource (e.g. changing a resource's title to describe something else entirely)

Enforcement of these expectations is left to ORD Aggregators and overlay governance processes. The purpose field on the overlay's resource-definition entry can help aggregators decide which changes are acceptable for a given overlay source.

Current Constraints

Overlays replace string values as complete values. If you need to refine a summary or description, compute the final string in the patch payload and apply it with update or merge.
The specification defines patch order within one overlay file. If multiple overlay documents apply to the same target, providers and aggregators should define and document a deterministic processing order outside this specification.
For OData, prefer the dedicated selectors in this spec: entityType, complexType, enumType, propertyType, entitySet, namespace, parameter, and returnType.
In OData, entityType targets the type definition itself. EntityContainer-bound annotations such as Capabilities belong on entitySet; use jsonPath only when no dedicated selector fits.
OData patch values MUST use CSDL JSON annotation format (@TermName keys). After applying an overlay, validate the merged result with format-specific tooling before publication.
Use namespace-qualified OData operation and type names whenever ambiguity is possible. ORD Overlay uses its own concept-level selector shapes; external notations such as OData CSDL Annotation Target are informative background, not alternative selector syntaxes in this version.
Selector alternatives based on source-model annotations, such as @EntityRelationship, are outside the scope of ORD Overlay 0.1.

Publishing​

Attached to an ORD Resource​

As an ORD Document Resource​

Target Resolution​

Selectors​

Patch Actions​

Validation​

Tooling​

ORD Aggregator Expectations​

Overlay Document Metadata​

Outlook: Patching ORD Resource Metadata Directly​

Schema Definitions​

ORD Overlay​

Overlay Target​

Overlay Patch​

Overlay Meta​

Example Values:​

Overlay Selector​

Overlay Selector By Root​

Example Values:​

Overlay Selector By JsonPath​

Example Values:​

Overlay Selector By Operation​

Example Values:​

Overlay Selector By Entity Type​

Example Values:​

Overlay Selector By Complex Type​

Example Values:​

Overlay Selector By Enum Type​

Example Values:​

Overlay Selector By Property Type​

Example Values:​

Overlay Selector By Entity Set​

Overlay Selector By Namespace​

Overlay Selector By Parameter​

Overlay Selector By Return Type​

Overlay Patch Value​

Overlay System Instance​

Overlay System Type​

Overlay System Version​

Appendix​

Tips: Inline Property Merging for OData Targets​

Deep Dive: Overlays vs. Resource Definition Visibility​

Prefer overlays when​

Prefer multiple resource definitions with different visibility when​

Main tradeoff​

Deep Dive: ORD Document Resource vs. Attached Resource Definition​

Prefer an ORD Document Resource when​

Prefer attaching as a resource definition when​

Main tradeoff​

Compatibility Expectations​

Current Constraints​

Publishing

Attached to an ORD Resource

As an ORD Document Resource

Target Resolution

Selectors

Patch Actions

Validation

Tooling

ORD Aggregator Expectations

Overlay Document Metadata

Outlook: Patching ORD Resource Metadata Directly

Schema Definitions

ORD Overlay

Overlay Target

Overlay Patch

Overlay Meta

Example Values:

Overlay Selector

Overlay Selector By Root

Example Values:

Overlay Selector By JsonPath

Example Values:

Overlay Selector By Operation

Example Values:

Overlay Selector By Entity Type

Example Values:

Overlay Selector By Complex Type

Example Values:

Overlay Selector By Enum Type

Example Values:

Overlay Selector By Property Type

Example Values:

Overlay Selector By Entity Set

Overlay Selector By Namespace

Overlay Selector By Parameter

Overlay Selector By Return Type

Overlay Patch Value

Overlay System Instance

Overlay System Type

Overlay System Version

Appendix

Tips: Inline Property Merging for OData Targets

Deep Dive: Overlays vs. Resource Definition Visibility

Prefer overlays when

Prefer multiple resource definitions with different visibility when

Main tradeoff

Deep Dive: ORD Document Resource vs. Attached Resource Definition

Prefer an ORD Document Resource when

Prefer attaching as a resource definition when

Main tradeoff

Compatibility Expectations

Current Constraints