openapi/json-schema @extension alignment - remove x- constraint and support values
#6076
Closed
3 tasks done
Labels
1_0_E2E
deprecation
A previously supported feature will now report a warning and eventually be removed
emitter:openapi3
Issues for @typespec/openapi3 emitter
triaged:core
Milestone
Comments
This was referenced Feb 20, 2025
markcowl
added
triaged:core
deprecation
github-merge-queue bot
pushed a commit
that referenced
this issue
Feb 27, 2025
…ts with `x-` extension name constraint (#6078) Resolves #6076 This PR makes a few changes to the `@typespec/openapi` `@extension` decorator to align it closer to the `@typespec/json-schema` `@extension` decorator. `@extension` is updated in 3 ways: 1. The `x-` prefix is no longer required for the extension name. 2. Value kinds are now supported and will be inserted in the Open API doc as raw values. 3. Passing in types (e.g. `typeof "foo"`, model expressions, tuple types) retains current behavior but also triggers a deprecation warning. ## What's with the deprecation warning? Prior to this PR, passed in types would be converted to JSON values (or emit an error if they couldn't be converted). So the following TypeSpec ```tsp @OpenAPI.extension("x-foo", { foo: true }) model Foo {} ``` would emit the following OpenAPI: ```yaml Foo: type: object x-foo: foo: true ``` However, in a follow-up release, passing in the type `{ foo: true }` will cause an OpenAPI schema to be emitted instead: ```yaml Foo: type: object x-foo: type: object required: - foo properties: foo: type: boolean enum: - true ``` To get back to the current behavior, `#{ foo: true }` should be passed instead. The deprecation warning gives users at least 1 release to be aware of the change and update their code accordingly. ## Follow-ups - typespec-azure PR: Azure/typespec-azure#2236 - Update azure-specs repo to use values: Azure/azure-rest-api-specs#32832 - Update azure-specs-pr repo: Azure/azure-rest-api-specs-pr#21556 --------- Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Clear and concise description of the problem
The
@typespec/openapi@extensiondecorator should be updated to behave similarly to the@typespec/json-schema@extensiondecorator.This task tracks the (mostly) non-breaking changes to the extension:
x-extension name constraintAdditionally, a warning should be added for passing in types to the
@extensionas this behavior will change in a subsequent release to emit Open API schemas instead of raw data.Checklist
The text was updated successfully, but these errors were encountered: