Skip to content

Emit compact type arrays for JSON Schema unions - #12599

Open
Timothee Guerin (timotheeguerin) wants to merge 6 commits into
microsoft:mainfrom
timotheeguerin:timotheeguerin-compact-json-schema-unions
Open

Timothee Guerin (timotheeguerin) wants to merge 6 commits into
microsoft:mainfrom
timotheeguerin:timotheeguerin-compact-json-schema-unions

Conversation

@timotheeguerin

Copy link
Copy Markdown
Member

Primitive unions currently emit separate anyOf branches, making schemas more verbose than necessary. Combine unconstrained alternatives into JSON Schema type arrays:

- { "anyOf": [{ "type": "string" }, { "type": "null" }] }
+ { "type": ["string", "null"] }

Mixed unions combine compatible types into one branch while preserving constraints, annotations, references, and explicit @oneOf semantics. This changes the emitted structure without changing which values validate.

Fixes #2656.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@pkg-pr-new

pkg-pr-new Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/json-schema@12599

commit: acc8e4b

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

All changed packages have been documented.

  • ✅ @typespec/json-schema
Show changes

@typespec/json-schema - feature ✏️

Emit unconstrained union variants as a compact JSON Schema type array instead of separate anyOf branches, preserving constrained variants and explicit @oneOf behavior.,> ,> For example, value: string | null now emits:,> ,> json,> { "type": ["string", "null"] },>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Recursive union compaction can discard an unresolved reference and emit an overly permissive schema that incorrectly accepts {}, requiring a resolution-aware fix and regression test.

1 open issue
What changed in this PR

This PR makes the JSON Schema emitter’s union output more compact by combining unconstrained alternatives into type arrays, addressing #2656.

Changes:

  • Combines and deduplicates bare JSON types, including nullable unions.
  • Adds handling for mixed unions and explicit @oneOf behavior.
  • Expands regression tests and documents the new output format.
File Description
website/​src/​content/​docs/​docs/​emitters/​json-schema/​guide.md Explains compact unions and when branches remain separate.
packages/​json-schema/​test/​unions.test.ts Tests compaction, metadata, references, templates, and @oneOf.
packages/​json-schema/​src/​json-schema-emitter.ts Implements type compaction and property-level @oneOf handling.
.chronus/​changes/​json-schema-compact-union-types.md Adds a feature changelog entry with an output example.

Review effort: Balanced

@azure-sdk-automation

azure-sdk-automation Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website 🛝 VSCode Extension

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Union compaction changes validation semantics when union- or property-level extensions override structural keywords, allowing booleans that the previous schema rejected.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Preserve union validation when extensions override structural schema keywords

packages/​json-schema/​src/​json-schema-emitter.ts:475

Returning the compact schema changes validation when a union or its containing property has @extension("type", "boolean"): for value: string | null, the previous schema retained anyOf alongside type: "boolean" and rejected every value, whereas the new schema becomes just type: "boolean" and accepts booleans because #applyConstraints overwrites type (lines 783–789). Preserve the original combinator when union/property extensions override structural keywords such as type or anyOf, and add regression coverage for both scopes.

1 resolved since last review

Review effort: Balanced

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 17, 2026 16:32

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Union compaction changes validation behavior when type or anyOf extensions override the emitted schema, requiring preservation of the original anyOf structure and regression tests at union and inline-property scopes.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Preserve union validation when extensions override type or anyOf

packages/​json-schema/​src/​json-schema-emitter.ts:475

@extension("type", "number") union Value { integer, null } now accepts 1.5: #applyConstraints overwrites the compacted type at lines 783–789, whereas the previous anyOf still rejected it. An anyOf override can instead reject previously accepted values, and both regressions also affect extensions on inline-union properties. Preserve the original anyOf structure when the union or containing property overrides type or anyOf, and add regressions for both keywords at both scopes.

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 19, 2026 14:12

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Union compaction leaves conflicting type and anyOf constraints when extensions override either keyword, rejecting previously valid values and affecting inline union properties.

1 open issue

Review effort: Balanced

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The review identifies no active issues requiring changes.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 19, 2026 14:43

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The JSON Schema union-compaction change has no active review issues.

No open issues 🎉

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

JsonSchema shouldn't union of primitive types use multiple type instead of anyOf

2 participants