Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .chronus/changes/json-schema-compact-union-types.md
Original file line number Diff line number Diff line change
@@ -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"] }
```
4 changes: 4 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 9 additions & 0 deletions packages/json-schema/DESIGN.md
Original file line number Diff line number Diff line change
@@ -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.
62 changes: 52 additions & 10 deletions packages/json-schema/src/json-schema-emitter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -312,7 +312,12 @@ export class JsonSchemaEmitter extends TypeEmitter<Record<string, any>, JSONSche
}

modelPropertyLiteral(property: ModelProperty): EmitterOutput<object> {
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);
Expand Down Expand Up @@ -418,22 +423,59 @@ export class JsonSchemaEmitter extends TypeEmitter<Record<string, any>, JSONSche
}

unionDeclaration(union: Union, name: string): EmitterOutput<object> {
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<object> {
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<unknown> {
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<string, unknown>[] = emitted.value;
const variants = new ArrayBuilder();
const types = new Set<string>();
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")
Comment thread
timotheeguerin marked this conversation as resolved.
Resolved
) {
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;
Comment thread
Copilot marked this conversation as resolved.
Resolved
}
}
return new ObjectBuilder({ anyOf: variants });
}

unionVariants(union: Union): EmitterOutput<object> {
Expand Down
191 changes: 189 additions & 2 deletions packages/json-schema/test/unions.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 () => {
Expand All @@ -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 () => {
Expand Down Expand Up @@ -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<T> { string, T }
model Foo {
value: U<boolean | null> | 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<T> { string, T }
model Foo {
@oneOf
value: U<boolean | null> | 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(
`
Expand Down
10 changes: 10 additions & 0 deletions website/src/content/docs/docs/emitters/json-schema/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading