diff --git a/.chronus/changes/json-schema-filenames.md b/.chronus/changes/json-schema-filenames.md new file mode 100644 index 00000000000..3f88c25e380 --- /dev/null +++ b/.chronus/changes/json-schema-filenames.md @@ -0,0 +1,17 @@ +--- +changeKind: feature +packages: + - "@typespec/json-schema" +--- + +Support a `file-name` template for schema filenames, including `.schema.json` and `.schema.yaml`. Implicit schema ids and references follow the configured filenames. + +Directory paths are not allowed in the template; use `emitter-output-dir` to configure the output directory. +Templates resolving to empty names or directory markers are rejected, and output filename collisions are reported as errors instead of overwriting schemas. + +```yaml +options: + "@typespec/json-schema": + file-type: json + file-name: "{name}.schema.{ext}" +``` diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md index 1e3af685da6..2271a27214a 100644 --- a/packages/json-schema/README.md +++ b/packages/json-schema/README.md @@ -66,6 +66,18 @@ See [Configuring output directory for more info](https://typespec.io/docs/handbo Serialize the schema as either yaml or json. +### `file-name` + +**Type:** `string` + +**Default:** `"{name}.{ext}"` + +File name template for each schema. Supports `{name}` for the declaration name +and `{ext}` for the extension selected by `file-type`. +Directory separators and `#` are not allowed; use `emitter-output-dir` for the output directory. +Also determines implicit schema ids and references. Does not change the bundle +file name, which is controlled by `bundleId`. + ### `int64-strategy` **Type:** `"string" | "number"` diff --git a/packages/json-schema/src/json-schema-emitter.ts b/packages/json-schema/src/json-schema-emitter.ts index 9d0679a6284..a864014ae60 100644 --- a/packages/json-schema/src/json-schema-emitter.ts +++ b/packages/json-schema/src/json-schema-emitter.ts @@ -51,6 +51,7 @@ import { getPattern, getRelativePathFromDirectory, getSummary, + interpolatePath, isStringType, isType, isTypeRefType, @@ -1019,6 +1020,31 @@ export class JsonSchemaEmitter extends TypeEmitter, JSONSche content: this.#serializeSourceFileContent(content), }); } else { + const paths = new DuplicateTracker(); + for (const sf of sourceFiles) { + if (sf.meta.shouldEmit) { + paths.track(sf.path, this.#typeForSourceFile.get(sf)!); + } + } + + let hasDuplicatePaths = false; + for (const [path, types] of paths.entries()) { + hasDuplicatePaths = true; + const file = getRelativePathFromDirectory( + this.emitter.getOptions().emitterOutputDir, + path, + false, + ); + for (const type of types) { + reportDiagnostic(this.emitter.getProgram(), { + code: "duplicate-output-file", + format: { file }, + target: type, + }); + } + } + if (hasDuplicatePaths) return; + for (const sf of sourceFiles) { const emittedSf = await this.emitter.emitSourceFile(sf); @@ -1180,7 +1206,10 @@ export class JsonSchemaEmitter extends TypeEmitter, JSONSche #newFileScope(type: JsonSchemaDeclaration) { const sourceFile = this.emitter.createSourceFile( - `${sanitizePathSegment(this.declarationName(type)!)}.${this.#fileExtension()}`, + interpolatePath(this.emitter.getOptions()["file-name"] ?? "{name}.{ext}", { + name: sanitizePathSegment(this.declarationName(type)!), + ext: this.#fileExtension(), + }), ); sourceFile.meta.shouldEmit = true; diff --git a/packages/json-schema/src/lib.ts b/packages/json-schema/src/lib.ts index 993b4300632..65d882ae9cb 100644 --- a/packages/json-schema/src/lib.ts +++ b/packages/json-schema/src/lib.ts @@ -32,10 +32,20 @@ export type PolymorphicModelsStrategy = "ignore" | "oneOf" | "anyOf"; export interface JSONSchemaEmitterOptions { /** * Serialize the schema as either yaml or json. - * @defaultValue yaml it not specified infer from the `output-file` extension + * @defaultValue yaml */ "file-type"?: FileType; + /** + * File name template for each schema. Supports `{name}` for the declaration name + * and `{ext}` for the extension selected by `file-type`. + * Directory separators and `#` are not allowed; use `emitter-output-dir` for the output directory. + * Also determines implicit schema ids and references. Does not change the bundle + * file name, which is controlled by `bundleId`. + * @defaultValue `{name}.{ext}` + */ + "file-name"?: string; + /** * How to handle 64-bit integers on the wire. Options are: * @@ -94,6 +104,18 @@ export const EmitterOptionsSchema: JSONSchemaType = { nullable: true, description: "Serialize the schema as either yaml or json.", }, + "file-name": { + type: "string", + nullable: true, + default: "{name}.{ext}", + description: [ + "File name template for each schema. Supports `{name}` for the declaration name", + "and `{ext}` for the extension selected by `file-type`.", + "Directory separators and `#` are not allowed; use `emitter-output-dir` for the output directory.", + "Also determines implicit schema ids and references. Does not change the bundle", + "file name, which is controlled by `bundleId`.", + ].join("\n"), + }, "int64-strategy": { type: "string", enum: ["string", "number"], @@ -155,6 +177,22 @@ export const EmitterOptionsSchema: JSONSchemaType = { export const $lib = createTypeSpecLibrary({ name: "@typespec/json-schema", diagnostics: { + "invalid-file-name": { + severity: "error", + messages: { + default: + "The 'file-name' option must not contain directory separators. Use 'emitter-output-dir' to configure the output directory.", + empty: + "The 'file-name' option must resolve to a non-empty file name other than '.' or '..'. Use '{name}' and '{ext}' as placeholders.", + fragment: "The 'file-name' option must not contain '#', which is a URI fragment delimiter.", + }, + }, + "duplicate-output-file": { + severity: "error", + messages: { + default: paramMessage`Multiple schemas emit to the same file "${"file"}". Configure 'file-name' to produce unique filenames.`, + }, + }, "invalid-prefix-items": { severity: "error", messages: { diff --git a/packages/json-schema/src/on-emit.ts b/packages/json-schema/src/on-emit.ts index deae7af1b86..320a7661bd9 100644 --- a/packages/json-schema/src/on-emit.ts +++ b/packages/json-schema/src/on-emit.ts @@ -2,13 +2,15 @@ import { createAssetEmitter } from "@typespec/asset-emitter"; import { type EmitContext, type Enum, + interpolatePath, type Model, + NoTarget, type Scalar, type Union, } from "@typespec/compiler"; import { getJsonSchemaTypes } from "./decorators.js"; import { JsonSchemaEmitter } from "./json-schema-emitter.js"; -import type { JSONSchemaEmitterOptions } from "./lib.js"; +import { type JSONSchemaEmitterOptions, reportDiagnostic } from "./lib.js"; export { $flags, $lib, EmitterOptionsSchema, type JSONSchemaEmitterOptions } from "./lib.js"; export const namespace = "TypeSpec.JsonSchema"; @@ -18,6 +20,36 @@ export type JsonSchemaDeclaration = Model | Union | Enum | Scalar; * Internal: TypeSpec emitter entry point */ export async function $onEmit(context: EmitContext) { + if (context.options["file-name"]?.match(/[/\\]/)) { + reportDiagnostic(context.program, { + code: "invalid-file-name", + target: NoTarget, + }); + return; + } + + if (context.options["file-name"]?.includes("#")) { + reportDiagnostic(context.program, { + code: "invalid-file-name", + messageId: "fragment", + target: NoTarget, + }); + return; + } + + const fileName = interpolatePath(context.options["file-name"] ?? "{name}.{ext}", { + name: "{name}", + ext: context.options["file-type"] === "json" ? "json" : "yaml", + }); + if (fileName === "" || fileName === "." || fileName === "..") { + reportDiagnostic(context.program, { + code: "invalid-file-name", + messageId: "empty", + target: NoTarget, + }); + return; + } + const emitter = createAssetEmitter(context.program, JsonSchemaEmitter as any, context); if (emitter.getOptions().emitAllModels) { diff --git a/packages/json-schema/test/ids.test.ts b/packages/json-schema/test/ids.test.ts index 8fbb1e447af..2d922fd55a1 100644 --- a/packages/json-schema/test/ids.test.ts +++ b/packages/json-schema/test/ids.test.ts @@ -52,6 +52,12 @@ describe("implicit ids", () => { code: "@typespec/json-schema/duplicate-id", message: `There are multiple types with the same id "Foo.json".`, }, + { + code: "@typespec/json-schema/duplicate-output-file", + }, + { + code: "@typespec/json-schema/duplicate-output-file", + }, ]); }); }); diff --git a/packages/json-schema/test/output-file.test.ts b/packages/json-schema/test/output-file.test.ts index 7a441817c1f..9e5ef8c6561 100644 --- a/packages/json-schema/test/output-file.test.ts +++ b/packages/json-schema/test/output-file.test.ts @@ -1,5 +1,6 @@ +import { expectDiagnostics } from "@typespec/compiler/testing"; import { describe, expect, it } from "vitest"; -import { emitSchema } from "./utils.js"; +import { emitSchema, emitSchemaWithDiagnostics } from "./utils.js"; describe("json-schema: output file", () => { it("emit a file per declaration named after the declaration", async () => { @@ -7,6 +8,96 @@ describe("json-schema: output file", () => { expect(Object.keys(schemas)).toContain("Foo.json"); }); + it.each(["json", "yaml"] as const)( + "configure %s filenames and update schema ids and references", + async (fileType) => { + const schemas = await emitSchema( + ` + model Foo { bar: Bar; } + model Bar {} + `, + { "file-type": fileType, "file-name": "{name}.schema.{ext}" }, + ); + + expect(Object.keys(schemas).sort()).toEqual([ + `Bar.schema.${fileType}`, + `Foo.schema.${fileType}`, + ]); + expect(schemas[`Foo.schema.${fileType}`].$id).toBe(`Foo.schema.${fileType}`); + expect(schemas[`Foo.schema.${fileType}`].properties.bar.$ref).toBe(`Bar.schema.${fileType}`); + expect(schemas[`Bar.schema.${fileType}`].$id).toBe(`Bar.schema.${fileType}`); + }, + ); + + it("use configured filenames with base URIs while preserving explicit ids", async () => { + const schemas = await emitSchema( + ` + @baseUri("https://example.org/") + namespace Example { + model Foo { bar: Bar; } + @id("custom") + model Bar {} + } + `, + { "file-name": "{name}.schema.{ext}" }, + ); + + expect(schemas["Foo.schema.json"].$id).toBe("https://example.org/Foo.schema.json"); + expect(schemas["Bar.schema.json"].$id).toBe("https://example.org/custom"); + expect(schemas["Foo.schema.json"].properties.bar.$ref).toBe("https://example.org/custom"); + }); + + it("preserve the bundle filename while configuring bundled schema ids and references", async () => { + const schemas = await emitSchema( + ` + model Foo { bar: Bar; } + model Bar {} + `, + { bundleId: "bundle.json", "file-name": "{name}.schema.{ext}" }, + ); + + expect(Object.keys(schemas)).toEqual(["bundle.json"]); + expect(schemas["bundle.json"].$id).toBe("bundle.json"); + expect(schemas["bundle.json"].$defs.Foo.$id).toBe("Foo.schema.json"); + expect(schemas["bundle.json"].$defs.Foo.properties.bar.$ref).toBe("Bar.schema.json"); + expect(schemas["bundle.json"].$defs.Bar.$id).toBe("Bar.schema.json"); + }); + + it("sanitize declaration names in configured filenames", async () => { + const schemas = await emitSchema("model `../../escaped` {}", { + "file-name": "{name}.schema.{ext}", + }); + expect(Object.keys(schemas)).toEqual([".._.._escaped.schema.json"]); + }); + + it.each(["schemas/{name}.schema.{ext}", "schemas\\{name}.schema.{ext}"])( + "reject directory paths in the filename template %s", + async (fileName) => { + const [schemas, diagnostics] = await emitSchemaWithDiagnostics("model Foo {}", { + "file-name": fileName, + }); + + expectDiagnostics(diagnostics, { + code: "@typespec/json-schema/invalid-file-name", + message: + "The 'file-name' option must not contain directory separators. Use 'emitter-output-dir' to configure the output directory.", + }); + expect(schemas).toEqual({}); + }, + ); + + it("reject fragment delimiters in the filename template", async () => { + const [schemas, diagnostics] = await emitSchemaWithDiagnostics("model Foo {}", { + "file-name": "{name}#schema.{ext}", + }); + + expectDiagnostics(diagnostics, { + code: "@typespec/json-schema/invalid-file-name", + message: "The 'file-name' option must not contain '#', which is a URI fragment delimiter.", + }); + expect(schemas).toEqual({}); + }); + it("sanitize path separators and traversal in declaration names", async () => { const schemas = await emitSchema("model `../../escaped` {}"); expect(Object.keys(schemas)).toContain(".._.._escaped.json"); @@ -16,4 +107,86 @@ describe("json-schema: output file", () => { const schemas = await emitSchema("model `..` {}"); expect(Object.keys(schemas)).toContain("_.json"); }); + + it.each(["", ".", "..", "{unknown}", "{unknown}.", "{unknown}.."])( + "reject filename templates resolving to an empty name or directory marker: %s", + async (fileName) => { + const [schemas, diagnostics] = await emitSchemaWithDiagnostics("model Foo {}", { + "file-name": fileName, + }); + + expectDiagnostics(diagnostics, { + code: "@typespec/json-schema/invalid-file-name", + message: + "The 'file-name' option must resolve to a non-empty file name other than '.' or '..'. Use '{name}' and '{ext}' as placeholders.", + }); + expect(schemas).toEqual({}); + }, + ); + + it("report filename collisions even when explicit schema ids are distinct", async () => { + const [schemas, diagnostics] = await emitSchemaWithDiagnostics( + ` + @id("foo") model Foo {} + @id("bar") model Bar {} + model Other {} + `, + { "file-name": "schema.{ext}" }, + ); + + expectDiagnostics(diagnostics, [ + { + code: "@typespec/json-schema/duplicate-output-file", + message: + "Multiple schemas emit to the same file \"schema.json\". Configure 'file-name' to produce unique filenames.", + }, + { + code: "@typespec/json-schema/duplicate-output-file", + }, + { + code: "@typespec/json-schema/duplicate-output-file", + }, + ]); + expect(schemas).toEqual({}); + }); + + it("report collisions introduced by sanitizing declaration names", async () => { + const [schemas, diagnostics] = await emitSchemaWithDiagnostics(` + @id("foo") model \`A/B\` {} + @id("bar") model A_B {} + `); + + expectDiagnostics(diagnostics, [ + { code: "@typespec/json-schema/duplicate-output-file" }, + { code: "@typespec/json-schema/duplicate-output-file" }, + ]); + expect(schemas).toEqual({}); + }); + + it("allow a fixed filename when only one schema is emitted", async () => { + const schemas = await emitSchema( + ` + @jsonSchema model Foo { bar: Bar; } + model Bar {} + `, + { "file-name": "schema.{ext}" }, + { emitNamespace: false }, + ); + + expect(Object.keys(schemas)).toEqual(["schema.json"]); + expect(schemas["schema.json"].properties.bar.$ref).toBe("#/$defs/Bar"); + }); + + it("allow matching schema filenames when bundling schemas with distinct ids", async () => { + const schemas = await emitSchema( + ` + @id("foo") model Foo {} + @id("bar") model Bar {} + `, + { "file-name": "schema.{ext}", bundleId: "bundle.json" }, + ); + + expect(Object.keys(schemas)).toEqual(["bundle.json"]); + expect(Object.keys(schemas["bundle.json"].$defs).sort()).toEqual(["bar", "foo"]); + }); }); 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..0ac9dc8275a 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,30 @@ 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. +## Configuring file names + +Use the `file-name` option to customize the name of each schema file. The default is `"{name}.{ext}"`, where `{name}` is the declaration name and `{ext}` is `yaml` or `json`, selected by `file-type` (defaults to `yaml`). + +For example, this configuration emits `Widget.schema.json` for a model named `Widget`: + +```yaml +emit: + - "@typespec/json-schema" +options: + "@typespec/json-schema": + file-type: json + file-name: "{name}.schema.{ext}" +``` + +Set `file-type: yaml` to emit `Widget.schema.yaml` instead. The file name template does not change the serialization format. + +The template must be a file name, not a path: `/` and `\` are rejected. Use `emitter-output-dir` to configure the output directory. +The `#` character is also rejected because it is a URI fragment delimiter and would break implicit schema ids and references. + +Templates that resolve to an empty name, `.` or `..` are also rejected. When emitting separate schema files, each must have a unique file name; collisions are reported as errors before any files are written. A fixed name such as `"schema.{ext}"` is valid when only one schema file is emitted. + +Implicit `$id` values and references between schemas use the configured file names. Explicit ids set with `@id` are preserved. When bundling, `bundleId` still determines the bundle file name; `file-name` only affects the implicit ids and references of the bundled schemas. + ## 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. diff --git a/website/src/content/docs/docs/emitters/json-schema/reference/emitter.md b/website/src/content/docs/docs/emitters/json-schema/reference/emitter.md index 609cc318b8f..38c0b7d7cf3 100644 --- a/website/src/content/docs/docs/emitters/json-schema/reference/emitter.md +++ b/website/src/content/docs/docs/emitters/json-schema/reference/emitter.md @@ -42,6 +42,18 @@ See [Configuring output directory for more info](https://typespec.io/docs/handbo Serialize the schema as either yaml or json. +### `file-name` + +**Type:** `string` + +**Default:** `"{name}.{ext}"` + +File name template for each schema. Supports `{name}` for the declaration name +and `{ext}` for the extension selected by `file-type`. +Directory separators and `#` are not allowed; use `emitter-output-dir` for the output directory. +Also determines implicit schema ids and references. Does not change the bundle +file name, which is controlled by `bundleId`. + ### `int64-strategy` **Type:** `"string" | "number"`