[Frank Li (franklixuefei)]

ARM (Control Plane) API Specification Update Pull Request

Tip

Overwhelmed by all this guidance? See the Getting help section at the bottom of this PR description.

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.

Purpose of this PR

What's the purpose of this PR? Check the specific option that applies. This is mandatory!

• New resource provider.
• New API version for an existing resource provider. (If API spec is not defined in TypeSpec, the PR should have been created in adherence to OpenAPI specs PR creation guidance).
• Update existing version for a new feature. (This is applicable only when you are revising a private preview API version.)
• Update existing version to fix OpenAPI spec quality issues in S360.
• Convert existing OpenAPI spec to TypeSpec spec (do not combine this with implementing changes for a new API version).
• Other, please clarify:
  • Spec-only conditional PUT proposal for the upcoming, unmerged 2026-11-01 GA contract in Add Chaos 2026-11-01 stable API version #45455. The intended base is juliagao-microsoft-chaos-2026-11-ga-promotion, not main. This is not a change to an already published GA API.

Contract and scope

Only these operations gain optional If-None-Match / If-Match request headers. Failed conditions return actual HTTP 412 with PreconditionFailed in the existing common Azure error body, modeled by the standard ARM default response:

• Workspaces_CreateOrUpdate
• Scenarios_CreateOrUpdate
• ScenarioConfigurations_CreateOrUpdate

The supported proposal is wildcard create-only (If-None-Match: *) and update-only (If-Match: *). Failed conditions cause no resource change or LRO acceptance. Omitting both headers preserves unconditional PUT. Existing supported validators must be preserved; effective conditions must be honored or rejected with 412 when they cannot be verified, not silently ignored. RFC-required ignoring of If-Unmodified-Since with If-Match, an invalid date, or no available modification date still applies.

No new etag body property, response ETag, full entity-tag matching platform, or public date-validator parameter is introduced. V1 resources, Connections, DELETE, ownership migration, runtime implementation, SDKs and Portal/CLI defaults are excluded. Existing operation IDs, 200/201 payloads, requiredness, sync/async choices and LRO headers/options are unchanged.

The emitted public response map remains exactly 200 / 201 / default; there is no explicit 412 declaration, custom error model, union or new TypeSpec suppression. This follows the user's revised modeling decision: preserve actual HTTP 412 behavior while using the standard public ARM default-error schema. No internal service status declaration is changed by this spec-only amendment.

Six operation-wired examples use supported responses.default error examples with HTTP 412 in their titles, PreconditionFailed bodies, and their conditional success responses. This is an example-representation change, not a change to actual HTTP failure behavior. OAV LiveValidator additionally validates the same six bodies with actual status 412 and rejects six malformed-body negative controls. Existing unconditional examples are unchanged. All OpenAPI and copied examples were regenerated by the locked emitter, not hand-edited.

Compatibility and validation evidence

Baseline: promotion-branch SHA c4271ad95126b3e0356cc9614b5b679f1cb10d77, freshly verified against live #45455. The untouched locked baseline compiled without warnings or tracked-file changes. Toolchain: TypeSpec compiler 1.17.0, Azure ARM/AutoRest libraries 0.73.0, pnpm 12.6.0; frozen dependency restore changed no manifests or locks.

Run the following from the repository root. These are the actual commands run and their results:

Command	Result
node .\node_modules\@typespec\compiler\cmd\tsp.js compile .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos (untouched baseline)	Passed; zero tracked-file changes.
Azure SDK MCP azsdk_run_typespec_validation with the absolute Chaos project root	Succeeded.
node .\node_modules\@typespec\compiler\cmd\tsp.js compile .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos --warn-as-error	Passed; no unsuppressed diagnostics.
node .\eng\tools\typespec-validation\cmd\tsv.js .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos	Passed: 10 passed, 2 skipped.
node .\eng\tools\typespec-suppressions\cmd\typespec-suppressions.js --base c4271ad95126b3e0356cc9614b5b679f1cb10d77 --head HEAD --check-rules-file .\eng\tools\typespec-suppressions\check-rules.json --fail-on-approval .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos	Passed: no new/changed/removed TypeSpec suppressions relative to the promotion base; requiresApproval: false.
$env:CHAOS_CONTRACT_BASE_REF='c4271ad95126b3e0356cc9614b5b679f1cb10d77'; $env:CHAOS_PRECONDITION_BASE_REF=$env:CHAOS_CONTRACT_BASE_REF; node --test .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos\tests\workspace-encryption.test.mjs .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos\tests\put-preconditions.test.mjs	Passed: 21/21, no skipped tests. Includes OAV LiveValidator validation of all six actual 412 error bodies through default, plus six malformed-error-body negative controls that must fail.
node .\node_modules\oav\dist\cli.js validate-example .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos\stable\2026-11-01\openapi.json --operationIds Workspaces_CreateOrUpdate,Scenarios_CreateOrUpdate,ScenarioConfigurations_CreateOrUpdate --logLevel error --logFilepath "$env:TEMP\chaos-default-examples.log"	Passed. Supported responses.default examples validate against the actual default error schema; the existing narrowly scoped 200/201 completeness directives remain.
node .\node_modules\oav\dist\cli.js validate-spec .\specification\chaos\resource-manager\Microsoft.Chaos\Chaos\stable\2026-11-01\openapi.json --logLevel error --logFilepath "$env:TEMP\chaos-default-spec.log"	Passed; semantic validation without errors.
git diff --check	Passed before commit.

SHA-256 comparison against the same-toolchain baseline found 592 retained emitted files, zero mismatches, including 2025-01-01 and the May/August previews. The existing regression additionally compares earlier source/generated examples and contracts byte-for-byte to the base commit. The new regression removes only the authorized headers and example links from the November document and then deep-compares the entire document with the baseline: the complete response maps, success responses, default errors, definitions, other operations and LRO metadata remain identical. It does not delete response entries to make the comparison pass.

Current review gates and warning dispositions

• The original four TypeSpec suppressions, error union and explicit 412 model have been removed, not replaced with Swagger rule waivers. Local suppression analysis reports zero new/changed/removed suppressions relative to the promotion base and no TypeSpec suppression approval requirement. Standard 200/201/default modeling removes the cause of the original six introduced PutResponseCodes / NoErrorCodeResponses lint errors; hosted re-evaluation is still required.
• Three RESPONSE_STATUS_CODE_NOT_IN_EXAMPLE directives remain, narrowed to November's selected PUT response leaves 200/201 only. A create-only request cannot return 200 and an update-only request cannot return 201. The examples collectively cover those statuses plus actual 412 through the default schema. Request/response schema validation is not suppressed. Both path separators are necessary because locked OAV's endsWithPath performs literal string suffix matching without normalization; a basename-only match would improperly broaden the version scope. These README suppressions still require owner review.
• The locked example CLI requires exact example response keys; responses.default is its supported representation for these error bodies. The emitter accepts and copies it unchanged and the final CLI passes. In an isolated fixture without README suppressions, the same validator reports only six missing impossible success outcomes; changing a default error body's error.code to a number additionally produces INVALID_TYPE, proving body validation is active. Actual HTTP status 412 is independently exercised by the committed LiveValidator regression with six negative controls. No dependency upgrade, CLI patch, impossible success, ignored status field or new suppression was added.
• The original hosted lint report explicitly classified EnumInsteadOfBoolean (including existing V1/common-type and V2 properties), LatestVersionOfCommonTypesMustBeUsed, PostOperationIdContainsUrlVerb, ParameterDescription and LocationMustHaveXmsMutability as existing before this PR. The normalized whole-document regression proves those response/model/operation definitions are unchanged. Changing boolean contracts, operation IDs, common-type versions, or resource mutability would alter inherited contracts outside this proposal; none were changed or waived.
• Existing PostResponseCodes errors are also promotion-owned and unchanged. The hosted cross-version report compares November against 2025-01-01 and August-preview on main, not this PR's promotion-branch base; its broader definition/common-type evolution findings remain for promotion review, not claimed resolved here.
• Local attempt at the exact hosted AutoRest/Spectral lint command was blocked by a missing @autorest/core package; no claim is made that this local lint run passed. Frozen dependencies and manifests were not upgraded to work around it.

Revised-head cross-version findings: not all warnings are inherited

The completed reports for head 9b64e3e78998cd9e3c81343384da045a8e21dab3 (run 40018994465, run 40018944680) contain identical findings after excluding timestamps: 12 errors, 99 warnings and 26 informational findings. They compare November against 2025-01-01 and August-preview on main, not against Julia's November branch.

Correction/clarification: the earlier inherited-warning discussion concerned the original Spectral lint report. It must not be read as saying all cross-version warnings are inherited. Three 1042 ChangedParameterOrder warnings are attributable to this optional-header proposal and remain unresolved compatibility effects for SDK/API-owner review. Six 1043 AddingOptionalParameter informational findings are the intended optional headers, not defects to remove.

Introduced preview-comparison finding	November schema location	Body index, before → after
1042 ChangedParameterOrder	paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Chaos/workspaces/{workspaceName}'].put.parameters (openapi.json:2238)	2 → 4
1042 ChangedParameterOrder	paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Chaos/workspaces/{workspaceName}/scenarios/{scenarioName}'].put.parameters (openapi.json:3326)	3 → 5
1042 ChangedParameterOrder	paths['/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Chaos/workspaces/{workspaceName}/scenarios/{scenarioName}/configurations/{scenarioConfigurationName}'].put.parameters (openapi.json:3595)	4 → 6

The same three parameter arrays account for six 1043 informational additions (If-None-Match and If-Match each). Removing only those two additions reproduces each baseline array exactly, preserving the relative order, requiredness and values of all existing parameters. Nevertheless, the 1042 rule warns about SDK signature compatibility; it is not declared harmless or approved here. Locked typespec-autorest 0.73.0's emitEndpointParameters emits non-body properties first and calls emitBodyParameters afterward (dist/src/openapi.js:680–710). Reordering source declarations cannot place the body ahead of those emitted headers through this mechanism. No proven safe source-only remedy was found without altering the emitter, generated arrays, intended headers or toolchain, so none was applied and no waiver was added.

The remaining findings have baseline-equivalent November inputs, established by per-finding source-path/value comparison, not merely by retained-version byte parity:

Findings	Exact affected schema paths / feature
Error 1006 RemovedDefinition ×1	November definitions: missing UserAssignedIdentities was already missing in Julia's baseline.
Error 1026 TypeChanged ×3	Common v6 definitions.ResourceModelWithAllowedPropertySet.properties.identity, .sku, .plan versus v5.
Error 1034 AddedRequiredProperty ×8	Common v6 ManagedServiceIdentity.properties (type), Sku.properties (name), Plan.properties (name, publisher, product), and their ResourceModelWithAllowedPropertySet.properties.identity/sku/plan uses.
Baseline-equivalent warnings ×96	Stable: 1017 ReferenceRedirection ×4, 1032 DifferentAllOf ×3, 1038 AddedPath ×31, 1040 AddedReadOnlyPropertyInResponse ×3. Preview: 1005 RemovedPath ×6, 1006 RemovedDefinition ×5, 1011 AddingResponseCode ×2, 1017 ReferenceRedirection ×1, 1023 TypeFormatChanged ×2, 1024 ConstraintIsStronger ×2, 1025 RequiredStatusChange ×3, 1026 TypeChanged ×4, 1029 ReadonlyPropertyChanged ×4, 1033 RemovedProperty ×2, 1034 AddedRequiredProperty ×13, 1036 ConstraintChanged ×5, 1040 AddedReadOnlyPropertyInResponse ×6.

These cover existing common-type identity/SKU/plan evolution; private-access route/definition removals; discover/evaluate POST 200 responses; existing V1 provisioning-state fields; scenario/template/evaluation/discovery/run-summary model evolution; and run-GET 202/Retry-After constraints. Those precise source nodes equal Julia's baseline. For the three AddedPath entries containing amended PUTs, the route keys already exist in the baseline and their route values match after removing only the authorized headers/example links. Twenty informational findings are likewise baseline-equivalent. No promotion/common-types/V1 cleanup or acceptance is implied.

Verification limit: this is a source-provenance audit of the actual hosted reports, not a full baseline re-execution of the OAD cross-version validator. No exact OAD baseline replay was performed or claimed. The separate local AutoRest/Spectral lint attempt was blocked by missing @autorest/core; that failed lint attempt is not presented as an OAD replay or proof that OAD itself cannot run. No package was upgraded or installed. The promotion owner must assess the twelve baseline-equivalent stable-comparison errors and promotion-level warnings; the API/SDK owners must assess the three newly attributable ordering warnings. No finding was waived, relabeled or silently accepted.

The remaining README suppressions have not been approved by an API reviewer. Local validation is not ARM/API approval. Hosted PR checks, SDK compatibility checks and runtime acceptance remain separate; no claim is made that unavailable or unrun checks passed. The two skipped TSV checks are not reported as passes. No runtime or downstream generated-code tests were run.

Downstream provenance gate

Do not consume this unmerged fork tree. GW model generation is blocked until this PR is merged into juliagao-microsoft-chaos-2026-11-ga-promotion. Then use the owning generator with an explicit promotion-branch parameter, a verified merged promotion-branch SHA, and API version 2026-11-01. No manual .g.cs edits and no fallback to main. This PR neither authorizes merging/deploying nor closes broader service implementation work.

Authoring references

• https://azure.github.io/typespec-azure/docs/howtos/versioning/06-evolving-apis/
• https://azure.github.io/typespec-azure/docs/howtos/arm/resource-operations/
• https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/reference/interfaces/
• https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#conditional-requests
• https://www.rfc-editor.org/rfc/rfc9110.html#section-13.2.2
• https://github.com/Azure/azure-openapi-validator/blob/main/docs/no-error-code-responses.md
• https://github.com/Azure/azure-openapi-validator/blob/main/docs/put-response-codes.md

Due diligence checklist

To merge this PR, you must go through the following checklist and confirm you understood
and followed the instructions by checking all the boxes:

• I confirm this PR is modifying Azure Resource Manager (ARM) related specifications, and not data plane related specifications.
• I have reviewed following Resource Provider guidelines, including
  ARM resource provider contract and
  REST guidelines (estimated time: 4 hours).
  I understand this is required before I can proceed to the diagram Step 2, "ARM API changes review", for this PR.
• A release plan has been created. If not, please create one as it will help guide you through the REST API and SDK creation process.

The human review attestation and release-plan confirmation are intentionally unchecked; this proposal does not attest to either on the service team's behalf.

Additional information

Viewing API changes

For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.

Suppressing failures

If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the
suppressions guide to get approval.

Getting help

• First, please carefully read through this PR description, from top to bottom. Please fill out the Purpose of this PR and Due diligence checklist.
• If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
• To understand what you must do next to merge this PR, see the Next Steps to Merge comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
• For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure
  and https://aka.ms/ci-fix.
• For help with ARM review (PR workflow diagram Step 2), see https://aka.ms/azsdk/pr-arm-review.
• If the PR CI checks appear to be stuck in queued state, please add a comment with contents /azp run.
  This should result in a new comment denoting a PR validation pipeline has started and the checks should be updated after few minutes.
• If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.
• For guidance on SDK breaking change review, refer to https://aka.ms/ci-fix.

[github-actions]

Next Steps to Merge

Next steps that must be taken to merge this PR:

• ❌ The suppressions added to the AutoRest config files (README.mds) require review. Refer to step 1 in the PR workflow diagram, or to step 3, depending on the kind of suppression you did.

Comment generated by summarize-checks workflow run.

[github-actions]

Contributor readiness: required access

Warning

Access issues can block approvals, Azure DevOps pipelines, or labeling.

User / area	Access issue	PR impact
🔴 xuefl-msft	Azure membership not public. No repository write access.	Not determined.

Internal contributors: set up / renew access. Recheck: /azsdk check-access.

Contributors with verified access (1)

Public Azure membership and repository write access verified.

User	Roles
franklixuefei	PR author

Non-blocking check; fix access issues to unblock affected actions.

Last updated: 2026-10-23T22:16:26.175Z

[github-actions]

TypeSpec suppressions requiring review

✅ No TypeSpec suppressions require review for the latest commit.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Go	sdk/resourcemanager/chaos/armchaos
Python	azure-mgmt-chaos
JavaScript	@azure/arm-chaos
Java	com.azure.resourcemanager:azure-resourcemanager-chaos
C#	Azure.ResourceManager.Chaos

---

Comment generated by After APIView workflow run.