From faec03bc35cdcc17420c7ca75b9a28a4073b03f6 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 17 Nov 2026 10:12:22 -0500 Subject: [PATCH 1/5] feat(json-schema): emit compact type arrays for unions Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../json-schema-compact-union-types.md | 15 ++ .../json-schema/src/json-schema-emitter.ts | 60 +++++-- packages/json-schema/test/unions.test.ts | 156 +++++++++++++++++- .../docs/docs/emitters/json-schema/guide.md | 10 ++ 4 files changed, 229 insertions(+), 12 deletions(-) create mode 100644 .chronus/changes/json-schema-compact-union-types.md diff --git a/.chronus/changes/json-schema-compact-union-types.md b/.chronus/changes/json-schema-compact-union-types.md new file mode 100644 index 00000000000..e1248fe3028 --- /dev/null +++ b/.chronus/changes/json-schema-compact-union-types.md @@ -0,0 +1,15 @@ +--- +changeKind: feature +packages: + - "@typespec/json-schema" +--- + +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"] } +``` + +Fixes [microsoft/typespec#2656](https://github.com/microsoft/typespec/issues/2656). diff --git a/packages/json-schema/src/json-schema-emitter.ts b/packages/json-schema/src/json-schema-emitter.ts index 9d0679a6284..c3dcdeee77e 100644 --- a/packages/json-schema/src/json-schema-emitter.ts +++ b/packages/json-schema/src/json-schema-emitter.ts @@ -312,7 +312,12 @@ export class JsonSchemaEmitter extends TypeEmitter, JSONSche } modelPropertyLiteral(property: ModelProperty): EmitterOutput { - const propertyType = this.emitter.emitTypeReference(property.type); + const propertyType = + isOneOf(this.emitter.getProgram(), property) && + property.type.kind === "Union" && + (!property.type.name || !this.declarationName(property.type)) + ? this.emitter.result.rawCode(this.#unionSchema(property.type, true)) + : this.emitter.emitTypeReference(property.type); compilerAssert(propertyType.kind === "code", "Unexpected non-code result from emit reference"); const result = new ObjectBuilder(propertyType.value); @@ -418,22 +423,57 @@ export class JsonSchemaEmitter extends TypeEmitter, JSONSche } unionDeclaration(union: Union, name: string): EmitterOutput { - const key = isOneOf(this.emitter.getProgram(), union) ? "oneOf" : "anyOf"; - - const withConstraints = this.#initializeSchema(union, name, { - [key]: this.emitter.emitUnionVariants(union), - }); + const withConstraints = this.#initializeSchema(union, name, this.#unionSchema(union)); this.#applyConstraints(union, withConstraints); return this.#createDeclaration(union, name, withConstraints); } unionLiteral(union: Union): EmitterOutput { - const key = isOneOf(this.emitter.getProgram(), union) ? "oneOf" : "anyOf"; + return this.#unionSchema(union); + } - return new ObjectBuilder({ - [key]: this.emitter.emitUnionVariants(union), - }); + #unionSchema( + union: Union, + oneOf = isOneOf(this.emitter.getProgram(), union), + ): ObjectBuilder { + const emitted = this.emitter.emitUnionVariants(union); + if (oneOf) { + return new ObjectBuilder({ oneOf: emitted }); + } + + compilerAssert( + emitted.kind === "code" && Array.isArray(emitted.value), + "Expected union variants", + ); + const schemas: Record[] = emitted.value; + const variants = new ArrayBuilder(); + const types = new Set(); + const combined = new ObjectBuilder(); + for (const schema of schemas) { + const schemaTypes: unknown[] = Array.isArray(schema.type) ? schema.type : [schema.type]; + if ( + Object.keys(schema).length === 1 && + schemaTypes.every((type) => typeof type === "string") + ) { + if (types.size === 0) { + variants.push(combined); + } + for (const type of schemaTypes) { + types.add(type); + } + } else { + variants.push(schema); + } + } + + if (types.size > 0) { + combined.type = types.size === 1 ? [...types][0] : [...types]; + if (variants.length === 1) { + return combined; + } + } + return new ObjectBuilder({ anyOf: variants }); } unionVariants(union: Union): EmitterOutput { diff --git a/packages/json-schema/test/unions.test.ts b/packages/json-schema/test/unions.test.ts index 8b695d71956..78d2ef6f915 100644 --- a/packages/json-schema/test/unions.test.ts +++ b/packages/json-schema/test/unions.test.ts @@ -14,7 +14,8 @@ describe("emitting unions", () => { assert.strictEqual(Foo.$id, "Foo.json"); assert.strictEqual(Foo.$schema, "https://json-schema.org/draft/2020-12/schema"); - assert.deepStrictEqual(Foo.anyOf, [{ type: "string" }, { type: "boolean" }]); + assert.deepStrictEqual(Foo.type, ["string", "boolean"]); + assert.strictEqual(Foo.anyOf, undefined); }); it("union description carries over", async () => { @@ -40,7 +41,131 @@ describe("emitting unions", () => { assert.strictEqual(Foo.$id, "Foo.json"); assert.strictEqual(Foo.$schema, "https://json-schema.org/draft/2020-12/schema"); - assert.deepStrictEqual(Foo.anyOf, [{ type: "string" }, { type: "boolean" }]); + assert.deepStrictEqual(Foo.type, ["string", "boolean"]); + assert.strictEqual(Foo.anyOf, undefined); + }); + + it("combines nullable property types and preserves defaults", async () => { + const schemas = await emitSchema(` + model Foo { + optional?: string | null = null; + value: string | boolean | integer | numeric | null; + } + `); + + expect(schemas["Foo.json"].properties).toEqual({ + optional: { type: ["string", "null"], default: null }, + value: { type: ["string", "boolean", "integer", "number", "null"] }, + }); + }); + + it("deduplicates variants with the same JSON Schema type", async () => { + const schemas = await emitSchema(` + model Foo { + value: string | int64 | decimal; + } + `); + + expect(schemas["Foo.json"].properties.value).toEqual({ type: "string" }); + }); + + it("combines only bare types in mixed unions", async () => { + const schemas = await emitSchema(` + model Foo { + value: string | Bar | null | int32 | utcDateTime | 1 | string[]; + } + model Bar {} + `); + + expect(schemas["Foo.json"].properties.value).toEqual({ + anyOf: [ + { type: ["string", "null"] }, + { $ref: "Bar.json" }, + { type: "integer", minimum: -2147483648, maximum: 2147483647 }, + { type: "string", format: "date-time" }, + { type: "number", const: 1 }, + { type: "array", items: { type: "string" } }, + ], + }); + }); + + it("preserves metadata on variants while combining other types", async () => { + const schemas = await emitSchema(` + union Foo { + @doc("documented string") + documented: string; + @extension("x-kind", "flag") + flag: boolean; + number: numeric; + nothing: null; + } + `); + + expect(schemas["Foo.json"].anyOf).toEqual([ + { type: "string", description: "documented string" }, + { type: "boolean", "x-kind": "flag" }, + { type: ["number", "null"] }, + ]); + }); + + it("preserves overlapping oneOf variants on unions and properties", async () => { + const schemas = await emitSchema(` + @oneOf + union Foo { integer, numeric, null } + model Bar { + @oneOf + value: integer | numeric | null; + @oneOf + overlapping: string | int64; + ordinary: integer | numeric | null; + } + `); + + const variants = [{ type: "integer" }, { type: "number" }, { type: "null" }]; + expect(schemas["Foo.json"].oneOf).toEqual(variants); + expect(schemas["Bar.json"].properties).toEqual({ + value: { oneOf: variants }, + overlapping: { oneOf: [{ type: "string" }, { type: "string" }] }, + ordinary: { type: ["integer", "number", "null"] }, + }); + }); + + it("preserves references to named and recursive unions", async () => { + const schemas = await emitSchema(` + union Value { string, null, Value[] } + model Foo { + @oneOf + exclusive: Value; + ordinary: Value; + } + `); + + expect(schemas["Value.json"].anyOf).toEqual([ + { type: ["string", "null"] }, + { type: "array", items: { $ref: "Value.json" } }, + ]); + expect(schemas["Foo.json"].properties).toEqual({ + exclusive: { $ref: "Value.json" }, + ordinary: { $ref: "Value.json" }, + }); + }); + + it("preserves shared model references from oneOf properties", async () => { + const schemas = await emitSchema(` + model Foo { + @oneOf + exclusive: Bar | string | null; + ordinary: Bar | string | null; + } + model Bar { next?: Bar } + `); + + expect(schemas["Foo.json"].properties).toEqual({ + exclusive: { + oneOf: [{ $ref: "Bar.json" }, { type: "string" }, { type: "null" }], + }, + ordinary: { anyOf: [{ $ref: "Bar.json" }, { type: ["string", "null"] }] }, + }); }); it("works with references", async () => { @@ -145,6 +270,33 @@ describe("emitting unions", () => { }); describe("union templates", () => { + it("combines type arrays from inline union instantiations", async () => { + const schemas = await emitSchema(` + union U { string, T } + model Foo { + value: U | integer; + } + `); + + expect(schemas["Foo.json"].properties.value).toEqual({ + type: ["string", "boolean", "null", "integer"], + }); + }); + + it("applies property-level oneOf only to the outer inline union", async () => { + const schemas = await emitSchema(` + union U { string, T } + model Foo { + @oneOf + value: U | integer; + } + `); + + expect(schemas["Foo.json"].properties.value).toEqual({ + oneOf: [{ type: ["string", "boolean", "null"] }, { type: "integer" }], + }); + }); + it("can be referenced from a property", async () => { const schemas = await emitSchema( ` diff --git a/website/src/content/docs/docs/emitters/json-schema/guide.md b/website/src/content/docs/docs/emitters/json-schema/guide.md index 30910243ec5..57049e7f3bc 100644 --- a/website/src/content/docs/docs/emitters/json-schema/guide.md +++ b/website/src/content/docs/docs/emitters/json-schema/guide.md @@ -26,6 +26,16 @@ If you want to treat all TypeSpec types as JSON Schema types (even if they don't If you want to treat all TypeSpec types referenced from JSON Schema types as JSON Schema types (even if they don't have the `@jsonSchema` decorator), you can set the `emitAllRefs` option to true. With this set, data types which are referenced from JSON Schema types will get their own schema file, and all references to them will be relative URIs. +## Unions + +Unconstrained union variants are combined into a JSON Schema `type` array. For example, `string | null` emits: + +```json +{ "type": ["string", "null"] } +``` + +In mixed unions, unconstrained types are combined into one `anyOf` branch. Variants with constraints, annotations, or references remain separate so their validation behavior and metadata are preserved. Unions marked with `@oneOf`, including inline unions on properties marked with `@oneOf`, keep their separate branches. + ## Bundling behavior By default, this emitter will produce separate schema files for each JSON Schema type in your program. However, if you prefer to bundle all of your schemas into a single file, you can set the `bundleId` option to the id you want to use for your bundle. You will now get a single file containing all of your schemas. From e5a7283bc5ba9c681490ac39ec37bcbc292b706c Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 17 Nov 2026 11:14:49 -0500 Subject: [PATCH 2/5] fix(json-schema): preserve union variants with extensions Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../json-schema/src/json-schema-emitter.ts | 4 ++- packages/json-schema/test/unions.test.ts | 35 +++++++++++++++++++ .../docs/docs/emitters/json-schema/guide.md | 2 +- 3 files changed, 39 insertions(+), 2 deletions(-) diff --git a/packages/json-schema/src/json-schema-emitter.ts b/packages/json-schema/src/json-schema-emitter.ts index c3dcdeee77e..cd1d890d250 100644 --- a/packages/json-schema/src/json-schema-emitter.ts +++ b/packages/json-schema/src/json-schema-emitter.ts @@ -450,9 +450,11 @@ export class JsonSchemaEmitter extends TypeEmitter, JSONSche const variants = new ArrayBuilder(); const types = new Set(); const combined = new ObjectBuilder(); - for (const schema of schemas) { + const unionVariants = [...union.variants.values()]; + for (const [index, schema] of schemas.entries()) { const schemaTypes: unknown[] = Array.isArray(schema.type) ? schema.type : [schema.type]; if ( + getExtensions(this.emitter.getProgram(), unionVariants[index]).length === 0 && Object.keys(schema).length === 1 && schemaTypes.every((type) => typeof type === "string") ) { diff --git a/packages/json-schema/test/unions.test.ts b/packages/json-schema/test/unions.test.ts index 78d2ef6f915..3a61ec42c46 100644 --- a/packages/json-schema/test/unions.test.ts +++ b/packages/json-schema/test/unions.test.ts @@ -130,6 +130,41 @@ describe("emitting unions", () => { }); }); + it("does not combine variants with type extensions", async () => { + const schemas = await emitSchema(` + union Value { + @extension("type", "string") + text: string; + boolean; + null; + } + `); + + expect(schemas["Value.json"].anyOf).toEqual([ + { type: "string" }, + { type: ["boolean", "null"] }, + ]); + }); + + it("preserves pending recursive references on variants with extensions", async () => { + const schemas = await emitSchema( + ` + @jsonSchema model Node { value: Value; } + union Value { + @extension("type", "object") + node: Node; + nothing: null; + } + `, + {}, + { emitNamespace: false }, + ); + + expect(schemas["Node.json"].$defs.Value).toEqual({ + anyOf: [{ type: "object", $ref: "Node.json" }, { type: "null" }], + }); + }); + it("preserves references to named and recursive unions", async () => { const schemas = await emitSchema(` union Value { string, null, Value[] } diff --git a/website/src/content/docs/docs/emitters/json-schema/guide.md b/website/src/content/docs/docs/emitters/json-schema/guide.md index 57049e7f3bc..09e203fe7c7 100644 --- a/website/src/content/docs/docs/emitters/json-schema/guide.md +++ b/website/src/content/docs/docs/emitters/json-schema/guide.md @@ -34,7 +34,7 @@ Unconstrained union variants are combined into a JSON Schema `type` array. For e { "type": ["string", "null"] } ``` -In mixed unions, unconstrained types are combined into one `anyOf` branch. Variants with constraints, annotations, or references remain separate so their validation behavior and metadata are preserved. Unions marked with `@oneOf`, including inline unions on properties marked with `@oneOf`, keep their separate branches. +In mixed unions, unconstrained types are combined into one `anyOf` branch. Variants with constraints, annotations, references, or `@extension` decorators remain separate so their validation behavior and metadata are preserved. Unions marked with `@oneOf`, including inline unions on properties marked with `@oneOf`, keep their separate branches. ## Bundling behavior From 7cb7a48a9dcfc3a133d0aea9856f4d668906c94f Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 17 Nov 2026 11:32:12 -0500 Subject: [PATCH 3/5] docs(json-schema): remove issue reference from changelog Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .chronus/changes/json-schema-compact-union-types.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/.chronus/changes/json-schema-compact-union-types.md b/.chronus/changes/json-schema-compact-union-types.md index e1248fe3028..54ddc7e0607 100644 --- a/.chronus/changes/json-schema-compact-union-types.md +++ b/.chronus/changes/json-schema-compact-union-types.md @@ -11,5 +11,3 @@ For example, `value: string | null` now emits: ```json { "type": ["string", "null"] } ``` - -Fixes [microsoft/typespec#2656](https://github.com/microsoft/typespec/issues/2656). From b44597e0778033c6b5c106ede69d4cad6d225a16 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 19 Nov 2026 09:30:43 -0500 Subject: [PATCH 4/5] docs(json-schema): clarify extension escape hatch design Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/instructions/json-schema.instructions.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .github/instructions/json-schema.instructions.md diff --git a/.github/instructions/json-schema.instructions.md b/.github/instructions/json-schema.instructions.md new file mode 100644 index 00000000000..9e7a94606ff --- /dev/null +++ b/.github/instructions/json-schema.instructions.md @@ -0,0 +1,13 @@ +--- +applyTo: "packages/json-schema/**/*" +--- + +# JSON Schema design decisions + +## Extensions are an escape hatch + +`@extension` adds arbitrary schema keywords. Guarding against misuse of this escape hatch is a non-goal. Users are responsible for the validity and semantics of extensions that override or conflict with emitter-generated keywords such as `type`, `anyOf`, or `$ref`. + +Emitter changes may alter the generated schema structure while preserving the semantics of the TypeSpec types. They do not need to preserve the validation behavior of extensions that depend on replacing a particular generated keyword. For example, replacing `anyOf` through an extension does not require the emitter to retain an `anyOf` layer instead of compacting a union into a `type` array. + +When implementing or reviewing changes, do not request defensive logic or regression tests solely to preserve behavior under such overrides. This does not exempt ordinary custom keywords or vendor extensions from being emitted correctly. From acc8e4b90c92b1e8b3598120fcd9daec37aca224 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 19 Nov 2026 09:42:43 -0500 Subject: [PATCH 5/5] docs(json-schema): move design decisions into the package Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 4 ++++ .../json-schema/DESIGN.md | 6 +----- 2 files changed, 5 insertions(+), 5 deletions(-) rename .github/instructions/json-schema.instructions.md => packages/json-schema/DESIGN.md (71%) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 09a403d1adc..e6c6e874315 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,6 +7,10 @@ TypeSpec is a language for defining cloud service APIs and shapes. This monorepo > [!IMPORTANT] > **These instructions do NOT apply to the language emitter packages** (`http-client-csharp`, `http-client-java`, `http-client-python`). Those packages are excluded from the pnpm workspace and do not require using pnpm. +## Package design documents + +Before implementing or reviewing changes in a package, look for its `DESIGN.md` and other design documents in that package. Read the relevant documents and follow their design decisions, constraints, and explicit non-goals when evaluating changes. + ## Essential Setup and Build Commands ### Prerequisites and Installation diff --git a/.github/instructions/json-schema.instructions.md b/packages/json-schema/DESIGN.md similarity index 71% rename from .github/instructions/json-schema.instructions.md rename to packages/json-schema/DESIGN.md index 9e7a94606ff..4733dc83edd 100644 --- a/.github/instructions/json-schema.instructions.md +++ b/packages/json-schema/DESIGN.md @@ -1,7 +1,3 @@ ---- -applyTo: "packages/json-schema/**/*" ---- - # JSON Schema design decisions ## Extensions are an escape hatch @@ -10,4 +6,4 @@ applyTo: "packages/json-schema/**/*" Emitter changes may alter the generated schema structure while preserving the semantics of the TypeSpec types. They do not need to preserve the validation behavior of extensions that depend on replacing a particular generated keyword. For example, replacing `anyOf` through an extension does not require the emitter to retain an `anyOf` layer instead of compacting a union into a `type` array. -When implementing or reviewing changes, do not request defensive logic or regression tests solely to preserve behavior under such overrides. This does not exempt ordinary custom keywords or vendor extensions from being emitted correctly. +Defensive logic and regression tests solely to preserve behavior under such overrides are outside the emitter's scope. Ordinary custom keywords and vendor extensions must still be emitted correctly.