Add no-openapi-client-extensions linter rule - #5109
Merged
Mark Cowlishaw (markcowl) merged 6 commits intoAug 8, 2026
Merged
Conversation
Mark Cowlishaw (markcowl)
requested review from
Timothee Guerin (timotheeguerin) and
Jeff Fisher (xirzec)
as code owners
July 30, 2026 03:04
Mark Cowlishaw (markcowl)
added
the
int:azure-specs
microsoft-github-policy-service
Bot
added
lib:azure-core
Contributor
|
All changed packages have been documented.
Show changes
|
commit: |
Contributor
|
You can try these changes here
|
Adds a typespec-azure-core linter rule that flags use of the @typespec/openapi @extension decorator to emit client-altering x-ms-* / x-nullable OpenAPI extensions (e.g. x-ms-long-running-operation, x-ms-pageable, x-ms-enum, x-ms-client-name, x-ms-secret). These extensions only affect the OpenAPI output, so other emitters produce an incorrect representation of the API; the docs point to the equivalent TypeSpec construct for each. Registered in both the data-plane and resource-manager rulesets. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 53a7f4f6-90c0-4844-bb8c-e3e62837b21b
The no-openapi rule no longer reports a violation for the @typespec/openapi @extension decorator. Client-altering x-ms-* extensions emitted through @extension are now handled by the dedicated no-openapi-client-extensions rule, so flagging every @extension use here is redundant and over-broad. Updates the tests and rule docs accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 53a7f4f6-90c0-4844-bb8c-e3e62837b21b
Mark Cowlishaw (markcowl)
force-pushed
the
markcowl/no-openapi-client-extensions
branch
from
August 7, 2026 00:43
155070d to
5631698
Compare
Mark Cowlishaw (markcowl)
added a commit
to markcowl/azure-rest-api-specs
that referenced
this pull request
Aug 7, 2026
The new @azure-tools/typespec-azure-core/no-openapi-client-extensions linter rule (Azure/typespec-azure#5109) flags uses of the @typespec/openapi @extension decorator that emit client-altering x-ms-* / x-* extensions, because those only affect the OpenAPI output and are ignored by client SDKs and other emitters. This adds #suppress directives at the 150 existing decorator locations (861 diagnostic instances across template instantiations) in 70 specs so they continue to compile once the rule ships. Each directive is placed on the decorated node and records that the usage predates the rule and should migrate to the equivalent TypeSpec construct. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 53a7f4f6-90c0-4844-bb8c-e3e62837b21b
Mark Cowlishaw (markcowl)
added a commit
to markcowl/azure-rest-api-specs
that referenced
this pull request
Aug 7, 2026
The new @azure-tools/typespec-azure-core/no-openapi-client-extensions linter rule (Azure/typespec-azure#5109) flags uses of the @typespec/openapi @extension decorator that emit client-altering x-ms-* / x-* extensions, because those only affect the OpenAPI output and are ignored by client SDKs and other emitters. This adds #suppress directives at the 150 existing decorator locations (861 diagnostic instances across template instantiations) in 70 specs so they continue to compile once the rule ships. Each directive is placed on the decorated node and records that the usage predates the rule and should migrate to the equivalent TypeSpec construct. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 53a7f4f6-90c0-4844-bb8c-e3e62837b21b
Member
Author
|
PR for spec suppressions: Azure/azure-rest-api-specs#45323 |
Contributor
📦 Package size report✅ No notable package size changes compared to the base branch. 13 package(s) with no notable change
Packed = gzipped |
catalinaperalta
approved these changes
Aug 7, 2026
catalinaperalta
left a comment
catalinaperalta
left a comment
Member
There was a problem hiding this comment.
just a small nit in the docs
…sions.md Co-authored-by: catalinaperalta <9859037+catalinaperalta@users.noreply.github.com>
Mark Cowlishaw (markcowl)
enabled auto-merge
August 8, 2026 07:53
Mark Cowlishaw (markcowl)
deleted the
markcowl/no-openapi-client-extensions
branch
August 8, 2026 08:40
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
3 participants
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
Adds a new
typespec-azure-corelinter rule,no-openapi-client-extensions, that flags use of the@typespec/openapi@extensiondecorator to emit client-alteringx-ms-*/x-nullableOpenAPI extensions.These extensions change how clients, SDKs, and the ARM platform interpret an API (long-running, pageable, secret, ARM resource, client name, etc.). When hand-written with the raw
@extensiondecorator they only appear in the OpenAPI output, so every other emitter works from the semantic TypeSpec model and never sees them — producing an incorrect representation of the API. Each has a first-class TypeSpec construct that should be used instead, which the docs enumerate.Extensions flagged:
x-ms-skip-url-encoding,x-ms-enum,x-ms-parameter-grouping,x-ms-parameter-location,x-ms-client-name,x-ms-discriminator-value,x-ms-client-flatten,x-ms-parameterized-host,x-ms-pageable,x-ms-long-running-operation,x-ms-long-running-operation-options,x-nullable,x-ms-internal,x-ms-azure-resource,x-ms-arm-id-details,x-ms-secret.Motivated by the discussion in #3066 (bar use of client-altering extensions).
Changes
packages/typespec-azure-core.linter.tsand in both thedata-planeandresource-managerrulesets.@azure-tools/typespec-azure-coreand@azure-tools/typespec-azure-rulesets.Validation
pnpm build, targeted rule tests (12, all passing), and rulesetsvalidate-rules-definedtests pass.pnpm format,lint, andcspellclean.int:azure-specslabel to be applied to run the External Integration check against all Azure specs.