You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Import OpenAPI schema examples arrays as TypeSpec decorators - #12626
tsp-openapi3 silently drops schema-level examples arrays. This change imports each entry as an @example decorator, preserving values, duplicates, and array order when round-tripping.
Conversion: Reverse decorator order to compensate for TypeSpec’s application order; avoid duplicate collection on properties and nullable unions.
Invalid input: Emit nothing for absent or empty arrays. Warn and skip non-array values.
Scope: Leave singular example and Media Type Object example maps unchanged.
For examples: [{ name: "Fluffy" }, { name: "Spot" }]:
Vincent Biret (baywet)
changed the title
[WIP] Update tsp-openapi to add examples to TypeSpec
Import OpenAPI schema examples arrays as TypeSpec decorators
Nov 20, 2026
[converter] Import schema-level examples arrays as @example decorators, preserving values and order when round-tripping OpenAPI 3.1 and 3.2. Invalid non-array examples are ignored with a warning.,> ,> tsp,> @example(#{ name: "Spot" }),> @example(#{ name: "Fluffy" }),> model Pet {,> name: string;,> },>
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
Example generation can emit invalid TypeSpec for date-time and enum values and silently omit or alter examples in inline bodies, composed schemas, and strings containing backslashes.
Adds schema-level examples array support to the OpenAPI-to-TypeSpec converter, aiming to preserve example values, duplicates, and order through round trips.
Changes:
Generates @example decorators in reverse application order and preserves repeated examples.
Avoids duplicate collection on properties and nullable unions; warns and skips non-array input.
Adds conversion and round-trip tests plus a feature changelog entry. Singular example fields and Media Type Object example maps remain unchanged.
Fixed in c58f9045: const body examples now round-trip, string examples use TypeSpec-compatible escaping, and schema-aware example conversion handles nullable temporal types, inherited enum properties, and union member selection.
Copilot address the review comments, commit, push, reply and resolve.
Committed and pushed c58f9045, addressing all six review findings. All 449 converter tests passed, along with lint, spellcheck, and CodeQL. I replied to both inline threads, but couldn’t mark them resolved from this session.
A valid OpenAPI 3.1+ body schema such as { $ref: "#/components/schemas/Pet", examples: [{ name: "Spot" }] } is skipped here, and the request-body generator emits only the referenced type (generators/generate-operation.ts:98–114), so these schema-level examples are still silently dropped. Preserve $ref sibling examples on a decorated use-site declaration or body property without attaching them globally to the referenced component, and cover referenced request/response body schemas.
Referenced header examples are resolved without context
For a response header whose schema has a string-enum $ref and sibling examples: ["red"], this filter retains the unresolved @example("red") collected without context in utils/response-properties.ts:71 and discards the correctly resolved enum-member example. The generated header then fails enum assignability (packages/compiler/src/core/type-relation-checker.ts:1176–1195). Pass context to that initial getDecoratorsForSchema call and add a referenced-header regression test.
Non-object response schemas generate an invalid intersection
A 201 JSON response with inline { type: "string", examples: ["ok"] } is now hoisted to a scalar, but this branch emits CreatedResponse & __OpenAPIExampleBody0, which cannot compile (packages/compiler/test/checker/relation.test.ts:165–191). Restrict the intersection shortcut to intersectable object models, use an explicit @body wrapper for other schema kinds, and add a non-200 response regression test.
Numeric temporal examples are emitted as incompatible numbers
Numeric examples for encoded temporal schemas fall through as numeric literals: { type: "integer", format: "unixtime", examples: [0] } produces @example(0) on a utcDateTime-derived scalar, and numeric x-ms-duration schemas have the same problem (generators/generate-types.ts:596–630). These scalars reject numeric literals (packages/compiler/src/core/type-relation-checker.ts:822–850); convert the encoded numbers to appropriate scalar constructor values while retaining their wire encoding, and add compile/round-trip tests.
AnyOf example selection ignores declared property matches
With anyOf object variants declaring optional a: string and optional b: utcDateTime, an example containing only b selects the first variant because undeclared properties are accepted here. It then emits b as a plain string, which fits neither generated variant: the first rejects the extra property (packages/compiler/src/core/type-relation-checker.ts:970–984) and the second requires a scalar value. Prefer variants whose declared properties match before permissive fallbacks, and add a regression case without required lists.
AnyOf selection ignores requirements inherited through allOf
For anyOf: [{ allOf: [ref A] }, { allOf: [ref B] }], where A requires a and B requires a date-time b, the example { b: "2026-11-20T16:00:00Z" } selects A because this fallback ignores inherited requirements. The resulting raw string fails the generated union, whose model requirements are preserved by generators/generate-types.ts:287–324. Check allOf constraints before accepting a candidate, with cycle-safe traversal and an inherited-variant regression test.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed because multiple schema-conversion edge cases can produce uncompilable TypeSpec or lose examples and nullability across request, response, and header paths.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Human assessment is needed because unpublished findings include a critical response-body compilation failure and several example-conversion cases that produce invalid output or lose schema semantics.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
tsp-openapi3silently drops schema-levelexamplesarrays. This change imports each entry as an@exampledecorator, preserving values, duplicates, and array order when round-tripping.exampleand Media Type Object example maps unchanged.For
examples: [{ name: "Fluffy" }, { name: "Spot" }]:Re-emitting OpenAPI 3.2 preserves
[Fluffy, Spot]inexamples, without a singularexamplefield.