Repository navigation
feat(openapi3): Configure namespace qualification in component names - #12505
Timothee Guerin (timotheeguerin) wants to merge 6 commits into
Conversation
commit: |
|
All changed packages have been documented.
Show changes
|
|
You can try these changes here
|
There was a problem hiding this comment.
🟡 Changes recommended
The distinct-multipart-type collision guard lacks a diagnostic test, leaving silent schema overwrites undetected if the guard is removed.
1 open issue
What changed in this PR
Adds configurable component naming to the OpenAPI 3 emitter, allowing namespace prefixes to be omitted or joined with custom separators while preserving existing defaults.
Changes:
- Applies
component-name-strategyto schemas, named multipart bodies, and reusable parameter keys and references. - Adds collision checks and tests for naming behavior, reference consistency, and service isolation.
- Documents configuration options and their limits; identifier sanitization remains out of scope.
| File | Description |
|---|---|
website/src/content/docs/docs/emitters/openapi3/reference/emitter.md |
Documents the new emitter option. |
website/src/content/docs/docs/emitters/openapi3/openapi.md |
Explains naming behavior, examples, and collision handling. |
packages/openapi3/test/parameters.test.ts |
Tests reusable parameter naming and collisions. |
packages/openapi3/test/multipart.test.ts |
Tests multipart naming, reuse, and schema collisions. |
packages/openapi3/test/get-openapi.test.ts |
Tests independent naming across services through the object API. |
packages/openapi3/test/component.test.ts |
Covers naming strategies, defaults, and reference preservation. |
packages/openapi3/src/schema-emitter.ts |
Applies configured naming across schema kinds. |
packages/openapi3/src/openapi.ts |
Resolves options and integrates parameter and multipart naming. |
packages/openapi3/src/lib.ts |
Defines the option’s types and validation schema. |
packages/openapi3/src/component-naming.ts |
Centralizes namespace qualification and separator handling. |
packages/openapi3/README.md |
Adds option reference documentation. |
.chronus/changes/feat-openapi3-component-naming-2026-10-4-18-35-26.md |
Records the feature with a configuration example. |
Review effort: Balanced
| ): string { | ||
| const strategy = options.componentNameStrategy; | ||
| const friendlyName = getFriendlyName(program, type); | ||
| const name = friendlyName ?? getTypeName(type, { ...typeNameOptions, nameOnly: true }); |
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
4 open issues
Preserve qualified template names to prevent multipart schema collisionsseparatoris markednullable: truein the option schema, but the public TS type for… · NewresolveOptions()always populatescomponentNameStrategy(it defaults to"fqn"and"."), but… · New This uses a JS/TS object-literal shape in prose ({ kind: fqn, ... }), which can be confusing… · New
Review effort: Lite
| separator: { | ||
| type: "string", | ||
| nullable: true, | ||
| default: ".", | ||
| description: | ||
| "Separator between namespace and parameter-property segments. May be empty. Does not replace punctuation within identifiers or friendly names.", | ||
| }, |
| /** Component qualification; defaults to service-relative `"fqn"` with `"."` separators. */ | ||
| componentNameStrategy?: { | ||
| /** Whether to include service-relative namespaces. */ | ||
| kind: ComponentNameStrategy; | ||
| /** Separator between namespace and parameter-property segments. */ | ||
| separator: string; | ||
| }; |
| component-name-strategy: name-only | ||
| ``` | ||
|
|
||
| Alternatively, use `{ kind: fqn, separator: "_" }` to emit `Models_User_Profile`, or an empty separator to concatenate segments. Separators do not replace punctuation inside identifiers or friendly names. The default strategy is `fqn` with `"."` separators. |



OpenAPI component names currently inherit service-relative TypeSpec namespaces, with no emitter option to omit those prefixes or change their separators.
@friendlyNamerequires per-type overrides and also affects other emitters.Models.User_ProfilebecomesUser_Profile. Use{ kind: fqn, separator: "_" }forModels_User_Profile, or an empty separator to concatenate namespace segments.The strategy applies to schemas, named multipart schemas, and reusable parameter keys and references through a single naming path, without changing HTTP names or operation IDs. Default naming remains unchanged.
Multipart component-key validation and collision fixes are isolated in #12545. Merge that fix first, then rebase this PR onto it; this PR contains only configurable naming and its supporting plumbing.
Alphanumeric sanitization is deferred to a follow-up; characters within identifiers and friendly names remain unchanged.
Related to #12479