From ee486de10b11bd39978a1b445c10a7ddced080a5 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 19 Nov 2026 08:39:11 -0500 Subject: [PATCH 1/3] feat(json-schema): support configurable schema filenames --- .chronus/changes/json-schema-filenames.md | 16 ++++ packages/json-schema/README.md | 12 +++ .../json-schema/src/json-schema-emitter.ts | 6 +- packages/json-schema/src/lib.ts | 31 ++++++- packages/json-schema/src/on-emit.ts | 11 ++- packages/json-schema/test/output-file.test.ts | 81 ++++++++++++++++++- .../docs/docs/emitters/json-schema/guide.md | 21 +++++ .../emitters/json-schema/reference/emitter.md | 12 +++ 8 files changed, 186 insertions(+), 4 deletions(-) create mode 100644 .chronus/changes/json-schema-filenames.md diff --git a/.chronus/changes/json-schema-filenames.md b/.chronus/changes/json-schema-filenames.md new file mode 100644 index 00000000000..416dabe5425 --- /dev/null +++ b/.chronus/changes/json-schema-filenames.md @@ -0,0 +1,16 @@ +--- +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. + +```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..e78c309da8f 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 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..4b54a176f91 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, @@ -1180,7 +1181,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..c3612c1f5e5 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 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 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,13 @@ 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.", + }, + }, "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..479aa7168c1 100644 --- a/packages/json-schema/src/on-emit.ts +++ b/packages/json-schema/src/on-emit.ts @@ -3,12 +3,13 @@ import { type EmitContext, type Enum, 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 +19,14 @@ 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; + } + const emitter = createAssetEmitter(context.program, JsonSchemaEmitter as any, context); if (emitter.getOptions().emitAllModels) { diff --git a/packages/json-schema/test/output-file.test.ts b/packages/json-schema/test/output-file.test.ts index 7a441817c1f..cb507b874ae 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,84 @@ 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("sanitize path separators and traversal in declaration names", async () => { const schemas = await emitSchema("model `../../escaped` {}"); expect(Object.keys(schemas)).toContain(".._.._escaped.json"); 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..d4e7a3aa39f 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,27 @@ 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. + +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..b582051b4d7 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 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"` From c9fab68ef9de6583d9c8092b8f51b0e00ef17c0c Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 19 Nov 2026 09:27:24 -0500 Subject: [PATCH 2/3] fix(json-schema): reject invalid and colliding schema filenames --- .chronus/changes/json-schema-filenames.md | 1 + .../json-schema/src/json-schema-emitter.ts | 25 ++++++ packages/json-schema/src/lib.ts | 8 ++ packages/json-schema/src/on-emit.ts | 14 ++++ packages/json-schema/test/ids.test.ts | 6 ++ packages/json-schema/test/output-file.test.ts | 82 +++++++++++++++++++ .../docs/docs/emitters/json-schema/guide.md | 2 + 7 files changed, 138 insertions(+) diff --git a/.chronus/changes/json-schema-filenames.md b/.chronus/changes/json-schema-filenames.md index 416dabe5425..3f88c25e380 100644 --- a/.chronus/changes/json-schema-filenames.md +++ b/.chronus/changes/json-schema-filenames.md @@ -7,6 +7,7 @@ packages: 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: diff --git a/packages/json-schema/src/json-schema-emitter.ts b/packages/json-schema/src/json-schema-emitter.ts index 4b54a176f91..a864014ae60 100644 --- a/packages/json-schema/src/json-schema-emitter.ts +++ b/packages/json-schema/src/json-schema-emitter.ts @@ -1020,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); diff --git a/packages/json-schema/src/lib.ts b/packages/json-schema/src/lib.ts index c3612c1f5e5..efe901fbb60 100644 --- a/packages/json-schema/src/lib.ts +++ b/packages/json-schema/src/lib.ts @@ -182,6 +182,14 @@ export const $lib = createTypeSpecLibrary({ 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.", + }, + }, + "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": { diff --git a/packages/json-schema/src/on-emit.ts b/packages/json-schema/src/on-emit.ts index 479aa7168c1..bf570984f35 100644 --- a/packages/json-schema/src/on-emit.ts +++ b/packages/json-schema/src/on-emit.ts @@ -2,6 +2,7 @@ import { createAssetEmitter } from "@typespec/asset-emitter"; import { type EmitContext, type Enum, + interpolatePath, type Model, NoTarget, type Scalar, @@ -27,6 +28,19 @@ export async function $onEmit(context: EmitContext) { 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 cb507b874ae..ba4419300c3 100644 --- a/packages/json-schema/test/output-file.test.ts +++ b/packages/json-schema/test/output-file.test.ts @@ -95,4 +95,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 d4e7a3aa39f..f13afddbc73 100644 --- a/website/src/content/docs/docs/emitters/json-schema/guide.md +++ b/website/src/content/docs/docs/emitters/json-schema/guide.md @@ -45,6 +45,8 @@ Set `file-type: yaml` to emit `Widget.schema.yaml` instead. The file name templa The template must be a file name, not a path: `/` and `\` are rejected. Use `emitter-output-dir` to configure the output directory. +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 From 97863437e841948867a622097c22abb46202c955 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Thu, 19 Nov 2026 10:02:51 -0500 Subject: [PATCH 3/3] fix(json-schema): reject fragment delimiters in filename templates --- packages/json-schema/README.md | 2 +- packages/json-schema/src/lib.ts | 5 +++-- packages/json-schema/src/on-emit.ts | 9 +++++++++ packages/json-schema/test/output-file.test.ts | 12 ++++++++++++ .../content/docs/docs/emitters/json-schema/guide.md | 1 + .../docs/emitters/json-schema/reference/emitter.md | 2 +- 6 files changed, 27 insertions(+), 4 deletions(-) diff --git a/packages/json-schema/README.md b/packages/json-schema/README.md index e78c309da8f..2271a27214a 100644 --- a/packages/json-schema/README.md +++ b/packages/json-schema/README.md @@ -74,7 +74,7 @@ Serialize the schema as either yaml or json. File name template for each schema. Supports `{name}` for the declaration name and `{ext}` for the extension selected by `file-type`. -Directory separators are not allowed; use `emitter-output-dir` for the output directory. +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`. diff --git a/packages/json-schema/src/lib.ts b/packages/json-schema/src/lib.ts index efe901fbb60..65d882ae9cb 100644 --- a/packages/json-schema/src/lib.ts +++ b/packages/json-schema/src/lib.ts @@ -39,7 +39,7 @@ export interface JSONSchemaEmitterOptions { /** * File name template for each schema. Supports `{name}` for the declaration name * and `{ext}` for the extension selected by `file-type`. - * Directory separators are not allowed; use `emitter-output-dir` for the output directory. + * 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}` @@ -111,7 +111,7 @@ export const EmitterOptionsSchema: JSONSchemaType = { description: [ "File name template for each schema. Supports `{name}` for the declaration name", "and `{ext}` for the extension selected by `file-type`.", - "Directory separators are not allowed; use `emitter-output-dir` for the output directory.", + "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"), @@ -184,6 +184,7 @@ export const $lib = createTypeSpecLibrary({ "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": { diff --git a/packages/json-schema/src/on-emit.ts b/packages/json-schema/src/on-emit.ts index bf570984f35..320a7661bd9 100644 --- a/packages/json-schema/src/on-emit.ts +++ b/packages/json-schema/src/on-emit.ts @@ -28,6 +28,15 @@ export async function $onEmit(context: EmitContext) { 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", diff --git a/packages/json-schema/test/output-file.test.ts b/packages/json-schema/test/output-file.test.ts index ba4419300c3..9e5ef8c6561 100644 --- a/packages/json-schema/test/output-file.test.ts +++ b/packages/json-schema/test/output-file.test.ts @@ -86,6 +86,18 @@ describe("json-schema: output file", () => { }, ); + 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"); 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 f13afddbc73..0ac9dc8275a 100644 --- a/website/src/content/docs/docs/emitters/json-schema/guide.md +++ b/website/src/content/docs/docs/emitters/json-schema/guide.md @@ -44,6 +44,7 @@ options: 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. 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 b582051b4d7..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 @@ -50,7 +50,7 @@ Serialize the schema as either yaml or json. File name template for each schema. Supports `{name}` for the declaration name and `{ext}` for the extension selected by `file-type`. -Directory separators are not allowed; use `emitter-output-dir` for the output directory. +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`.