Skip to content

Import OpenAPI schema examples arrays as TypeSpec decorators - #12626

Open
Vincent Biret (baywet) wants to merge 8 commits into
mainfrom
copilot/tsp-openapi3-import-examples
Open

Vincent Biret (baywet) wants to merge 8 commits into
mainfrom
copilot/tsp-openapi3-import-examples

Conversation

@baywet

@baywet Vincent Biret (baywet) commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

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" }]:

@example(#{ name: "Spot" })
@example(#{ name: "Fluffy" })
model Pet {
  name: string;
}

Re-emitting OpenAPI 3.2 preserves [Fluffy, Spot] in examples, without a singular example field.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
@microsoft-github-policy-service microsoft-github-policy-service Bot added emitter:openapi3 Issues for @typespec/openapi3 emitter openapi3:converter Issues for @typespec/openapi3 openapi to typespec converter labels Nov 20, 2026
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
@baywet 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
@azure-sdk-automation

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

Copy link
Copy Markdown

You can try these changes here

🛝 Playground 🌐 Website 🛝 VSCode Extension

@pkg-pr-new

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

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/openapi3@12626

commit: 255e03b

@baywet

Copy link
Copy Markdown
Member Author

Copilot spellcheck is failing, add suppressions for the new terms reported by this CI run https://github.com/microsoft/typespec/actions/runs/44762771140/job/136398416689?pr=12626

@github-actions

Copy link
Copy Markdown
Contributor

All changed packages have been documented.

  • ✅ @typespec/openapi3
Show changes

@typespec/openapi3 - feature ✏️

[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;,> },>

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

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.

4 open issues
What changed in this PR

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.
File Description
packages/​openapi3/​test/​tsp-openapi3/​examples.test.ts Adds serialization, ordering, invalid-input, and round-trip coverage.
packages/​openapi3/​src/​cli/​actions/​convert/​utils/​decorators.ts Collects schema examples as decorators and warns on invalid arrays.
packages/​openapi3/​src/​cli/​actions/​convert/​transforms/​transform-component-schemas.ts Adjusts nullable-union metadata collection and outer-example precedence.
packages/​openapi3/​src/​cli/​actions/​convert/​generators/​generate-model.ts Prevents collecting property examples twice and forwards logging context.
packages/​openapi3/​src/​cli/​actions/​convert/​generators/​generate-decorators.ts Preserves duplicate @example decorators while deduplicating other decorators.
.chronus/​changes/​copilot-tsp-openapi3-import-examples-2026-10-20-15-22-0.md Documents the feature with a TypeSpec example.

Review effort: Balanced

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Copilot spellcheck is failing, add suppressions for the new terms reported by this CI run https://github.com/microsoft/typespec/actions/runs/44762771140/job/136398416689?pr=12626

Added Mochi to the root CSpell dictionary. Repository spellcheck passes with zero issues. Commit: 69124c0d.

@baywet

Copy link
Copy Markdown
Member Author

Copilot address the review comments

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Copilot address the review comments

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.

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

Several valid response and schema example cases generate non-compiling TypeSpec, while examples on referenced body schemas are silently dropped.

No open issues 🎉

6 previously missed issues

In code that hasn't changed since last review

Medium severity Examples on referenced body schemas are dropped

packages/​openapi3/​src/​cli/​actions/​convert/​convert.ts:80

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.

Medium severity Referenced header examples are resolved without context

packages/​openapi3/​src/​cli/​actions/​convert/​generators/​generate-model.ts:389

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.

Medium severity Non-object response schemas generate an invalid intersection

packages/​openapi3/​src/​cli/​actions/​convert/​generators/​generate-response-expressions.ts:256

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.

Medium severity Numeric temporal examples are emitted as incompatible numbers

packages/​openapi3/​src/​cli/​actions/​convert/​utils/​decorators.ts:529

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.

Medium severity AnyOf example selection ignores declared property matches

packages/​openapi3/​src/​cli/​actions/​convert/​utils/​decorators.ts:609

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.

Medium severity AnyOf selection ignores requirements inherited through allOf

packages/​openapi3/​src/​cli/​actions/​convert/​utils/​decorators.ts:621

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.

2 resolved since last review

Review effort: Balanced

Comment thread cspell.yaml Resolved
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 20, 2026 20:31

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

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.

No open issues 🎉

Review effort: Balanced

Copilot AI commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Copilot address the review comments

I’m checking the remaining review feedback and will address the actionable issues.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 20, 2026 20:42

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

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.

No open issues 🎉

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

emitter:openapi3 Issues for @typespec/openapi3 emitter openapi3:converter Issues for @typespec/openapi3 openapi to typespec converter

Projects

None yet

Development

Successfully merging this pull request may close these issues.

tsp-openapi3: import examples

4 participants