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..54ddc7e0607 --- /dev/null +++ b/.chronus/changes/json-schema-compact-union-types.md @@ -0,0 +1,13 @@ +--- +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"] } +``` 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/packages/json-schema/DESIGN.md b/packages/json-schema/DESIGN.md new file mode 100644 index 00000000000..4733dc83edd --- /dev/null +++ b/packages/json-schema/DESIGN.md @@ -0,0 +1,9 @@ +# 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. + +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. diff --git a/packages/json-schema/src/json-schema-emitter.ts b/packages/json-schema/src/json-schema-emitter.ts index 9d0679a6284..cd1d890d250 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,59 @@ 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(); + 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") + ) { + 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..3a61ec42c46 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,166 @@ 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("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[] } + 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 +305,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..09e203fe7c7 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, 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 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.