[Swagger Linter Migration] EnumInsteadOfBoolean

[Yuchao Yan (msyyc)]

Original Swagger linter

• Rule: EnumInsteadOfBoolean
• Validator docs: https://github.com/Azure/azure-openapi-validator/blob/main/docs/enum-instead-of-boolean.md
• Validator function source: https://github.com/Azure/azure-openapi-validator/blob/main/packages/rulesets/src/spectral/functions/enum-insteadof-boolean.ts
• Validator ruleset registration: https://github.com/Azure/azure-openapi-validator/blob/main/packages/rulesets/src/spectral/az-common.ts

Specific checks promoted from the done lintdiff rule:

• Boolean model properties should be reported.
• Boolean operation parameters should be reported, including path parameters.
• Boolean request bodies should be reported.
• Boolean response bodies should be reported.
• Comparable non-boolean shapes should not be reported.

How the Swagger linter works

The Swagger rule is a Spectral rule from the common ruleset. It inspects emitted OpenAPI schema objects and reports schemas whose type is boolean, with diagnostics located on the emitted schema path. The lintdiff migration evidence accepts that the Swagger and TypeSpec implementations run at different representation layers: Swagger can report repeated emitted schema copies, while the TypeSpec rule reports the authorable source target.

Source TypeSpec lintdiff rule

Source branch: feature/lintdiff-migration-new

Source rule: https://github.com/Azure/typespec-azure/blob/feature/lintdiff-migration-new/packages/typespec-lintdiff/src/rules/enum-instead-of-boolean.ts

The source worktree had no uncommitted changes for the lintdiff source rule or EnumInsteadOfBoolean fixture directory when this promotion was created. The user-marked done lintdiff source rule was not modified during promotion.

Destination analysis

The rule belongs in @azure-tools/typespec-azure-core because the lintdiff metadata marks EnumInsteadOfBoolean as applicability: Both with sources: ["common"], and the local TypeSpec rule only depends on compiler/http APIs. It does not inspect ARM resources, provider namespaces, ARM resource paths, ARM lifecycle operations, or ARM envelopes.

Because the rule applies to both ARM and data-plane specs, this PR enables @azure-tools/typespec-azure-core/enum-instead-of-boolean in both typespec-azure-rulesets data-plane and resource-manager rulesets.

How the promoted TypeSpec linter works

The promoted Azure Core rule preserves the done lintdiff rule behavior:

• Visits model properties and reports a diagnostic when the property type is the intrinsic boolean scalar.
• Visits HTTP operation responses via getHttpOperation and reports boolean response bodies on the operation or authored body property target.
• Keeps the diagnostic as a warning and adapts the message/docs to Azure Core convention by recommending descriptive extensible enums.
• Registers the rule in the Azure Core linter and rulesets without adding any dependency on Azure Resource Manager libraries.

Fixture-to-native test mapping

• boolean-property -> emits warning for boolean model properties
• boolean-path-param -> emits warning for boolean path parameters
• boolean-body -> emits warning for boolean request bodies
• boolean-response -> emits warning for boolean response bodies
• non-boolean-shapes -> allows comparable non-boolean shapes

The official package tests use direct TypeSpec snippets and expected diagnostics. Lintdiff harness snapshots were not copied.

Migration evidence

Migration evidence: https://github.com/Azure/typespec-azure/blob/feature/lintdiff-migration-new/packages/typespec-lintdiff/test/fixtures/EnumInsteadOfBoolean/migration.md

The detailed focused tests, real-service project comparison, corpus counts, one-sided project explanations, compile-failure handling, and remaining uncertainty are recorded there rather than duplicated in this PR description.

Promotion sync policy

Semantic gaps found after promotion should block the promotion PR until the user explicitly reopens lintdiff repair. This PR does not include unapproved source-rule edits in packages/typespec-lintdiff.

[github-actions]

All changed packages have been documented.

• ✅ @azure-tools/typespec-azure-core
• ✅ @azure-tools/typespec-azure-rulesets

Show changes

@azure-tools/typespec-azure-core - feature ✏️

Add the enum-instead-of-boolean lint rule that recommends descriptive extensible enums instead of boolean API shapes when semantic values matter.

@azure-tools/typespec-azure-rulesets - feature ✏️

Add the enum-instead-of-boolean lint rule that recommends descriptive extensible enums instead of boolean API shapes when semantic values matter.

[github-actions]

📦 Package size report

✅ No notable package size changes compared to the base branch.

13 package(s) with no notable change

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-azure-core	130.28 KB → 130.38 KB	+103 B (+0.1%)	706.82 KB → 707.33 KB	+521 B (+0.1%)
@azure-tools/typespec-java	13.51 MB → 13.51 MB	+45 B (+0.0%)	15.03 MB → 15.03 MB	—
@azure-tools/typespec-azure-rulesets	5.16 KB → 5.18 KB	+21 B (+0.4%)	32.09 KB → 32.44 KB	+360 B (+1.1%)
@azure-tools/azure-http-specs	146.63 KB → 146.63 KB	—	1.16 MB → 1.16 MB	—
@azure-tools/typespec-autorest	80.93 KB → 80.93 KB	—	395.06 KB → 395.06 KB	—
@azure-tools/typespec-autorest-canonical	7.42 KB → 7.42 KB	—	26.00 KB → 26.00 KB	—
@azure-tools/typespec-azure-portal-core	42.40 KB → 42.40 KB	—	192.91 KB → 192.91 KB	—
@azure-tools/typespec-azure-resource-manager	171.92 KB → 171.92 KB	—	1.04 MB → 1.04 MB	—
@azure-tools/typespec-client-generator-core	229.25 KB → 229.25 KB	—	1.23 MB → 1.23 MB	—
@azure-tools/typespec-go	258.44 KB → 258.44 KB	—	1.32 MB → 1.32 MB	—
@azure-tools/typespec-metadata	15.91 KB → 15.91 KB	—	62.26 KB → 62.26 KB	—
@azure-tools/typespec-python	42.22 KB → 42.22 KB	—	164.91 KB → 164.91 KB	—
@azure-tools/typespec-ts	527.17 KB → 527.17 KB	—	2.54 MB → 2.54 MB	—

_{Packed = gzipped .tgz published to npm. Unpacked = total extracted size. 🆕 added, 🗑️ removed. Packages from the core/ submodule are not included.
🔴 grew · 🟢 shrank — only changes of at least 512 B and 0.5% are marked.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@azure-tools/typespec-azure-core@5265

npm i https://pkg.pr.new/@azure-tools/typespec-azure-rulesets@5265

commit: 42287eb

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website