Align OpenAPI schema examples with raw SchemaObject shape#2001
Merged
Conversation
typia's emended schema keeps named examples so converters can preserve labels internally, while raw OpenAPI Schema Objects expose array-shaped examples. The downgrade path now drops names at the raw boundary and the schema guide documents the converter step for third-party OpenAPI plugins. Constraint: OpenAPI Schema Object examples are array-shaped in JSON Schema/OpenAPI 3.1 while Parameter and Media Type examples remain named records Rejected: Change typia's emended OpenApi.IJsonSchema examples to arrays | would discard labels before converters can choose a target dialect Confidence: high Scope-risk: moderate Tested: pnpm format Tested: pnpm build Tested: node compiled OpenApiConverter downgradeSchema examples smoke test Tested: pnpm run build (website) Not-tested: Full test-utils runner; local ttsx project check timed out before executing filtered tests Related: #1697
Owner
Author
|
Self-review round 1 completed against the full PR diff (types, downgrade/upgrader converter paths, regression tests, and docs together). Result: no follow-up changes found. CI is green across build, experiments, test, website/deploy, tarballs, Socket, and spell-check. |
OAS 3.0 only has the singular Schema Object example field, while OAS 3.1 and newer inherit JSON Schema's array-shaped examples keyword. The v3.0 downgrade path now strips typia's emended named examples instead of leaking a non-standard Schema Object field; v3.1 continues to emit the JSON Schema array form. Constraint: OAS 3.0 Schema Object does not define examples; Parameter and Media Type examples remain named maps Rejected: Keep examples?: any[] on OpenApiV3.IJsonSchema | still advertises a non-standard OAS 3.0 Schema Object field Confidence: high Scope-risk: narrow Tested: pnpm format Tested: pnpm build Tested: node compiled OpenApiConverter downgradeSchema v3.0/v3.1 examples smoke test Tested: pnpm --filter ./tests/test-utils start Related: #1697
JSON Schema examples are array-shaped in raw OpenAPI 3.1 and 3.2 Schema Objects, while typia's emended schema stores them as named records. These tests cover upgrade, downgrade, and document round-trip boundaries so schema examples cannot be confused with Media Type Object examples. Constraint: OpenAPI 3.1/3.2 Schema Object examples use JSON Schema array semantics; Media Type examples remain named maps Rejected: Only test top-level schema downgrade | would miss recursive property/item schemas and media-type map preservation Confidence: high Scope-risk: narrow Tested: pnpm format Tested: pnpm --filter ./tests/test-utils start Tested: pnpm build Tested: pnpm test Tested: pnpm run build (website) Related: #2001 Related: #1697
Owner
Author
|
Self-review round 2 completed against the full PR diff after reopening and adding round-trip coverage. Reviewed scope in one pass:
Result: no follow-up changes found. Verification:
|
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Summary
examplestypes to array-shaped values for v3.0/v3.1/v3.2Discussion
Validation
pnpm formatpnpm buildnodesmoke test against builtOpenApiConverter.downgradeSchemafor v3.0/v3.1 schema examplespnpm run buildfromwebsite/Local Gap
tests/test-utilsexecution timed out locally inttsxproject check before test execution; the new behavior was still checked via package build plus compiled converter smoke test.