Skip to content

Support configurable JSON Schema filenames - #12619

Open
Timothee Guerin (timotheeguerin) wants to merge 4 commits into
microsoft:mainfrom
timotheeguerin:timotheeguerin-json-schema-filenames
Open

Timothee Guerin (timotheeguerin) wants to merge 4 commits into
microsoft:mainfrom
timotheeguerin:timotheeguerin-json-schema-filenames

Conversation

@timotheeguerin

Copy link
Copy Markdown
Member

JSON Schema files currently use fixed .json or .yaml filenames, preventing users from choosing conventions such as Widget.schema.json.

Add a file-name template with {name} and {ext} placeholders:

options:
  "@typespec/json-schema":
    file-type: json
    file-name: "{name}.schema.{ext}"

This produces Widget.schema.json; selecting YAML produces Widget.schema.yaml. Implicit $id values and references follow the configured filenames, while explicit IDs, bundle filenames, and default behavior remain unchanged.

Directory separators are rejected with an actionable diagnostic; output placement remains controlled by emitter-output-dir.

@pkg-pr-new

pkg-pr-new Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/json-schema@12619

commit: 9786343

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

All changed packages have been documented.

  • ✅ @typespec/json-schema
Show changes

@typespec/json-schema - feature ✏️

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}",>

@azure-sdk-automation

azure-sdk-automation Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website 🛝 VSCode Extension

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Distinct schema IDs can resolve to the same output path and silently overwrite a schema, while accepted empty or directory-marker filenames can cause emission to fail.

2 open issues
What changed in this PR

Adds configurable filenames to the JSON Schema emitter through a file-name template with {name} and {ext} placeholders.

Changes:

  • Applies filename templates to schema files and their implicit IDs and references, preserving explicit IDs and bundle filenames.
  • Rejects directory separators and adds tests for JSON, YAML, bundling, and name sanitization.
  • Documents the option and adds a feature changelog entry.
File Description
website/​src/​content/​docs/​docs/​emitters/​json-schema/​reference/​emitter.md Adds the file-name option reference.
website/​src/​content/​docs/​docs/​emitters/​json-schema/​guide.md Explains configuration and ID behavior.
packages/​json-schema/​test/​output-file.test.ts Tests templates, references, bundling, and validation.
packages/​json-schema/​src/​on-emit.ts Rejects templates containing directory separators.
packages/​json-schema/​src/​lib.ts Defines the option and validation diagnostic.
packages/​json-schema/​src/​json-schema-emitter.ts Interpolates filenames when creating schema files.
packages/​json-schema/​README.md Documents the new emitter option.
.chronus/​changes/​json-schema-filenames.md Records the feature with a configuration example.

Review effort: Balanced

Comment thread packages/json-schema/src/on-emit.ts Resolved
Copilot AI balanced review requested due to automatic review settings November 19, 2026 14:27

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Filename handling can target the output directory for empty declaration names and produce incorrect schema IDs and references when filenames contain unescaped '#' characters.

2 open issues
2 resolved since last review

Review effort: Balanced

Comment thread packages/json-schema/src/on-emit.ts Resolved
Copilot AI balanced review requested due to automatic review settings November 19, 2026 15:02

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The filename guard still permits ?, causing URI consumers to misinterpret emitted schema filenames as queries and breaking cross-schema references.

No open issues 🎉

1 previously missed issue

In code that hasn't changed since last review

Medium severity Reject query delimiters in schema filenames

packages/​json-schema/​src/​on-emit.ts:31

The new guard still accepts file-name: "{name}?schema.{ext}", which writes Bar?schema.json, but #getDeclId (packages/json-schema/src/json-schema-emitter.ts:1126–1141) uses that filename verbatim: URI consumers interpret it as resource Bar with query schema.json, so cross-schema references do not locate the emitted file. Reject ? alongside fragment delimiters with an actionable diagnostic and a regression test.

2 resolved since last review

Review effort: Balanced

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants