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, each overlay applied to a given resource SHOULD have a unique purpose. If two overlays share the same purpose on the same resource, behavior is implementation-defined — consumers SHOULD treat this as a configuration error. 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.

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:
  • Omit data to remove the entire selected element.
  • Provide data with null-valued properties to remove only those specific fields.
  • data MUST NOT be null, an empty object {}, or an empty array [] — these are invalid and will be rejected by conformant tooling.
• merge behavior: arrays are appended, not replaced. To fully replace an array, use two ordered patches — first remove the array field with data: { "arrayField": null }, then merge the new value.

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.

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.

The tooling package will be linked here once published.

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. "remove": Remove the selected element or specific fields within it. - When data is omitted: remove the selected element from the document entirely. - 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. "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.
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.
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.

One of the following: Overlay Selector By Root | Overlay Selector By JsonPath | Overlay Selector By Operation | Overlay Selector By Entity Type | Overlay Selector By Complex Type | Overlay Selector By Enum Type | Overlay Selector By Property Type | Overlay Selector By Entity Set | Overlay Selector By Namespace | Overlay Selector By Parameter | Overlay Selector By Return Type

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 ORD Document (no specific definitionType): - Patch root-level ORD document properties 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. 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"

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://google.github.io/A2A/specification/#agentskill-object - OData (edmx, csdl-json): maps to the Action or Function name at Schema level. MUST use the namespace-qualified name (e.g. OData.Demo.Approval) to be unambiguous. For OData v2 edmx targets: also searches FunctionImport elements in EntityContainer when no Schema-level Action/Function matches the name. For bound operations overloaded on multiple entity types, use jsonPath as a fallback to target the specific overload. 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"

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. May use the unqualified name (e.g. Customers) or namespace-prefixed name. - 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.). 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"

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: the namespace-qualified Action, Function, or FunctionImport name. - 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 name whose ReturnType is targeted. - For edmx: the namespace-qualified name of the Action or Function (e.g. com.example.Svc.TerminateEmployee). - For csdl-json: the namespace-qualified name looked up in the Namespace object. 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": [...] }. When the target is EDMX XML, the merge implementation converts this to <Annotation> elements. See: https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html

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. 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.

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(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.

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(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.