[anugrah55]

Closes #299

OpenApiVisitor copied the JSON Schema definitions into components.schemas unchanged, including the $decorators key on decorated types and properties. Open API 3.0 schema objects only allow extension keys that start with x-, so redocly rejected the output for any decorated model.

Changes

• OpenApiVisitor renames $decorators to x-concerto-decorators on each definition and on each of its properties. These are the only places JSONSchemaVisitor writes decorators, and a targeted rename leaves user data such as default values and decorator arguments alone. JSON Schema output is unchanged (its snapshot still has $decorators).
• Unit test covering a decorated enum, concept, primitive property, concept-typed property and relationship array; it fails without the change.
• The model-base and agreement OpenAPI verification cases are no longer skipped and pass redocly lint.
• hr_integration's OpenAPI skip reason now names only the map schema wrapper (JSONSchemaVisitor: map properties are emitted as { "schema": {...} }, so map values are never validated #292/fix(jsonschema): emit map property schemas directly and apply their key and value types #293), which is its only remaining redocly error; it reuses the collectionsize wording.
• OpenAPI snapshot updated (10 keys renamed).

Flags

• Generated OpenAPI changes for anyone reading $decorators from openapi.json. The concerto-docs OpenAPI page and accordproject/apap's openapi.json still show $decorators; no code in the org reads the key back. The docs page would need a follow-up.
• fix(jsonschema): emit map property schemas directly and apply their key and value types #293 rewrites the same hr_integration skip line in test/verification/cases.js. Whichever lands second should keep the text without $decorators.
• Checks: npm test on Node 24.15 (macOS): 721 passing, coverage gate met, openapivisitor.js at 100%. OpenAPI output is checked with redocly by test/verification/openapi.validate.test.js; model-base and agreement now pass there, and CI's verify-openapi passes. verification/corpus/manifest.json has no OpenAPI skips to update.

Questions for maintainers

1. Key name. This uses x-concerto-decorators, as proposed in bug: OpenAPI output keeps $decorators from JSON Schema, which OpenAPI 3.0 schema objects do not allow #299, because Open API 3.0 only allows x- extension keys and the prefix says where the data comes from. It has not been confirmed there; happy to change it.
2. Breaking or not. This is a fix rather than fix!, because the old output failed OpenAPI validation and fix(avro): drop the version from Avro namespaces #290 treated a similar output change the same way. If you would rather mark it breaking, I can change the type and add a section to MIGRATION.md.

Author Checklist

• Ensure you provide a DCO sign-off for your commits using the --signoff option of git commit.
• Vital features and changes captured in unit and/or integration tests
• Commits messages follow AP format
• Extend the documentation, if necessary
• Merging to main from fork:branchname

AI usage

• AI tools were used: AI was used to understand the codebase and edge cases, and to draft the code change and tests; I reviewed the result and can explain every change.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[anugrah55]

This is my first contribution here, so the workflows are waiting for approval. Could a maintainer approve the CI run when convenient? Thanks!

[mira-accord-project]

Thanks for your first contribution to Accord Project, and for the clear description of the OpenAPI 3.0 issue in #299. The CI workflows have now been approved and are passing. The change is waiting for review from the Concerto maintainers; they review as time allows, and we are working to shorten that wait. If you push further changes, the checks will run again, and it helps if the commits are signed off (DCO).

Drafted by an Accord Project agent, reviewed by a maintainer.

[mira-accord-project]

Thank you, anugrah55, for a careful first contribution. I read the change against JSONSchemaVisitor and found nothing to fix. renameDecorators covers every place the JSON Schema visitor writes $decorators: class and enum schemas, primitive properties, $ref and anyOf properties, the array wrapper, and relationship properties. Map properties return early without decorators. A targeted rename also leaves default values and decorator arguments untouched, and the JSON Schema output is unchanged. The new unit test asserts the renamed keys on each of those cases and the absence of $decorators, the snapshot changes follow directly from the fix, and the verification skips are updated to match. The two design questions you raised (the x-concerto-decorators key name, and fix versus fix! with a MIGRATION.md entry) are for the maintainers to decide, and the docs follow-up you noted is a sensible plan. Nothing here blocks the merge; it now needs a maintainer's approval.

No problems found.

---

_{Automated review by Mira, an Accord Project agent, at 196cf9c. Findings are labelled blocking, should-fix or nit; a maintainer makes the final call.}