Fix circular references in JSON Schema discriminated unions with polymorphic-models-strategy

[mike-taylor99]

Fix circular references in JSON Schema discriminated unions with polymorphic-models-strategy

Problem

When using polymorphic-models-strategy: "oneOf" (or "anyOf") with discriminated unions, the JSON Schema emitter generates circular references that cause validation errors:

1. Base model (e.g., Pet) emits oneOf: [Cat, Dog]
2. Derived models (e.g., Cat, Dog) emit allOf: [{ $ref: "Pet.json" }]
3. This creates a cycle: Pet → Cat → Pet (via oneOf and allOf)

JSON Schema validators reject these circular references, making it impossible to validate payloads against the discriminated union schemas.

Solution

When a model extends a base model that uses the discriminated union strategy:

• Don't use allOf to reference the base model (avoiding circular references)
• Inline all base properties directly into the derived model schema
• The base model still emits only oneOf/anyOf without properties

Example

Before (circular reference):

// Pet.json
{ "oneOf": [{"$ref": "Cat.json"}], "properties": {"name": ...}, ... }

// Cat.json  
{ "allOf": [{"$ref": "Pet.json"}], "properties": {"meow": ...}, ... }

After (no circular reference):

// Pet.json
{ "oneOf": [{"$ref": "Cat.json"}] }

// Cat.json
{ "properties": {"name": ..., "kind": "cat", "meow": ...}, "required": ["name", "kind"] }

[pkg-pr-new]

Open in StackBlitz

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

commit: cb6fb16

[github-actions]

All changed packages have been documented.

• ✅ @typespec/json-schema

Show changes

@typespec/json-schema - fix ✏️

avoid circular references in discriminated unions with polymorphic-models-strategy

[timotheeguerin]

/azp run typespec - pr tools

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[azure-sdk]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[timotheeguerin]

• from offline talk update the doc to specify what this fully does

[timotheeguerin]

Suggested change

	changeKind: fix
	changeKind: internal

can be internal as the original change wasn't released in regular version