Open
Conversation
- Implement 'operation' concept-level selector in overlay-merge:
- OpenAPI (openapi-v2/v3/v3.1+): resolves via paths.{path}.{method}.operationId
- MCP (Specification ID definitionType): resolves via tools[].name
- A2A Agent Card: resolves via skills[].id
- Auto-detection (no definitionType): tries OpenAPI → MCP → A2A in order
- Throws OverlayMergeError for named definitionTypes without operation support
(e.g. edmx, csdl-json, asyncapi-v2, raml-v1)
- Add 6 new unit tests and 2 integration tests for operation selector
- Rename dispute-agent-mcp.overlay.json → dispute-agent-a2a.overlay.json
- Update SelectorByOperation schema description: clearly defines all three
operation mappings and removes resolved A2A TODO
- Update OrdOverlay.intro.md: remove A2A TODO block, document A2A skills[].id
- Add real paths/operationIds/schemas to astronomy-v1.oas3.json for tests
- Add legacy-dispute-lookup skill to DisputeResolutionAgentcard.json
- Rewrite examples/definitions/ord-document-overlay.json to current schema format
- Copy OrdOverlay.schema.json to static/spec-extension/models/ for canonical $id URL;
gitignore /static/spec-extension/ (URL only works after deployment)
- Clean stale ResourceDefinitionOverlay references from clean.mjs
- Add inline TODOs: YAML CLI input, deepMerge type mismatch, definitionType
validators, entityType/propertyType selectors, OData operation mapping
- Fix JSON formatting in business-partner-odata.overlay.json
- Add structured sections: Distribution, Target Resolution, Selectors, Patch Actions, Validation, Overlay Document Metadata, Open TODOs - Replace repeated prose with tables and anchor links to schema definitions - Add inline example overlay JSON (enriching an undocumented API operation) - Split Distribution into two sub-sections with brief JSON examples each - Remove redundant Referencing from ORD Documents section (now inline) - Consolidate all TODOs at end under Open TODOs - Fix all broken Docusaurus anchor links
Closed
|
Co-authored-by: Sebastian Wennemers <sebastian.wennemers@sap.com>
- Move 'remove' before 'merge' in the action description and enum so the definition of 'remove' precedes the reference to it in the 'merge' array-replacement example - Add 'Intended use and compatibility' section clarifying overlays MUST NOT introduce breaking API changes; typical use is non-breaking enrichment (extensions, annotations, descriptions); exception is intentional restriction/removal
Fannon
commented
Mar 14, 2026
Comment on lines
+34
to
+39
| Intended use and compatibility: | ||
| - Overlays MUST NOT introduce breaking / incompatible changes to the original API or metadata. | ||
| - Typical use-cases are non-breaking enrichments: adding extensions, annotations, or updating | ||
| non-critical properties such as descriptions, summaries, or display names. | ||
| - An exception is intentionally restricting exposure: an overlay MAY remove or hide elements | ||
| (e.g. operations, fields) that should not be visible in a given context or to a given audience. |
Member
Author
There was a problem hiding this comment.
@swennemers does this address your comments suggestions / concerns?
Member
There was a problem hiding this comment.
It is good to have these statement, but they don't address my issue above.
Member
Author
There was a problem hiding this comment.
What statement are you missing still?
Member
There was a problem hiding this comment.
You have added it to the open topics section, it is the selector and annotations only question.
…ode review and consistency
…ormation in overlay that don't get merged into target
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The ORD Overlay is an optional ORD model extension that allows patching both ORD resource metadata
and referenced resource definition files (e.g. OpenAPI, AsyncAPI, OData CSDL, MCP/A2A Agent Cards)
without modifying the original source files.
What to Review
This PR contains a lot of file changes, but some of them are just generated files (ignore in review) and quite a few are for the merge-overlay script that we should move to a separate repository / NPM project later anyway.
For easier reviewing, concentrate on:
Added
ord:overlay:v1)openResourceDiscoveryV1.overlays) or attached directly to an API/Event resource as aresourceDefinitionsentry.ordId,operation,entityType,propertyType) or a genericjsonPathfallback, with actionsmerge,update,append, andremove.targetobject narrows a patch to a specific definition file or format (e.g.definitionType: openapi-v3).describedSystemType,describedSystemVersion,describedSystemInstance,visibility) scope the overlay to a particular system context.