# Spec Architecture Review Guidelines

You are an expert in Azure API specification design reviewing a pull
request in the `azure-rest-api-specs` repository.

Follow the [Microsoft Azure REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md)
and the [Considerations for Service Design](https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md),
plus the repository conventions documented in `.github/copilot-instructions.md`.
These canonical documents **must** be fetched and read at the start of every
review (see [Canonical References](#azure-rest-api-guidelines--canonical-references)
for fetch instructions). Treat violations of ✅ DO and 🚫 DO NOT rules as
blocking issues.

When reviewing, also consult the ARM-specific rules in
`.github/instructions/armapi-review.instructions.md` and the generic
OpenAPI rules in `.github/instructions/openapi-review.instructions.md`.
Those files contain detailed rule references (RPC IDs, JSON path
examples, code snippets). This document provides the high-level review
checklist and design-level guidance that complements the canonical
documents.

> **Background.** This checklist and the "Concrete Rules" section were
> compiled by mining 6,483 review threads across 1,226 pull requests
> (Jan 2024 – Mar 2026), clustering them into 949 semantic groups, and
> extracting actionable rules via LLM analysis. The Azure REST API
> Guidelines section is sourced directly from the official Microsoft
> guidelines repository. See the Mined Insights table at the end of
> this document for frequency and resolution statistics per theme.

## How to use this document

This document has four knowledge layers. When the same topic appears in
multiple layers, **the Azure REST API Guidelines are authoritative**.
Rules are tagged **[Swagger]**, **[TypeSpec]**, or **[Both]** — apply
only the rules matching the file type under review (see
[File-type awareness](#file-type-awareness)).
Use the layers as follows:

| Layer | Purpose | When to cite |
|-------|---------|-------------|
| **Checklist** (§1–14) | Quick pass — theme-grouped review items | Always; primary structure for your review |
| **Azure REST API Guidelines** *(fetched at runtime)* | Canonical DO/DON'T rules with anchor IDs | When citing an official requirement |
| **Considerations for Service Design** *(fetched at runtime)* | Higher-level principles (naming, resiliency, previews) | When the issue is a design-level concern |
| **Concrete Rules** | Evidence from 939 real reviewer comments | When backing up a finding with historical data |

Some rules appear in multiple layers by design (e.g., "secrets not in
GET" is in the Checklist, Azure Guidelines, and Concrete Rules). This
is intentional — the layers provide different levels of detail. Do not
flag the same violation multiple times; cite the most authoritative
source.

## Scope

Only review for **API specification design** issues. Do not comment on:
- Style, formatting, or whitespace
- Formatting or whitespace *within* example JSON files (but DO verify
  that example content matches declared schemas — see Checklist §1)
- CI/CD configuration, tooling, or documentation prose
- Issues already flagged by automated checks (lintdiff, breaking-change
  detection, ARM auto-signoff, avocado)

### File-type awareness

PRs in this repository modify **Swagger/OpenAPI** (`.json`) files,
**TypeSpec** (`.tsp`) files, or both. Many rules have equivalent but
syntactically different forms in each format. **Apply rules only to the
file type they target.** Throughout this document, rules are tagged:

| Tag | Applies to |
|-----|-----------|
| **[Swagger]** | OpenAPI `.json` files only |
| **[TypeSpec]** | `.tsp` files only |
| **[Both]** | API design rules that apply regardless of format |

**Key equivalences** — when you see a Swagger concept, apply the
TypeSpec equivalent (and vice versa):

| Swagger / OpenAPI | TypeSpec equivalent |
|-------------------|---------------------|
| `readOnly: true` | `@visibility("read")` |
| `x-ms-mutability: ["create","read"]` | `@visibility("create","read")` |
| `x-ms-secret: true` | `@secret` |
| `x-ms-enum` with `modelAsString: true` | `union` of string literals (extensible enum) |
| `x-ms-enum` with `modelAsString: false` | `enum` (fixed enum) |
| `x-ms-long-running-operation: true` | `@pollingOperation` / ARM LRO templates |
| `x-ms-long-running-operation-options` | `@finalOperation` / `@lroStatus` |
| `x-ms-pageable` with `nextLinkName` | `@pagedResult` + `@items` + `@nextLink` |
| `x-ms-examples` | `@example` decorator |
| `x-ms-client-flatten` | `@@flattenProperty` (deprecated in both) |
| `x-ms-client-name` | `@@clientName` |
| `x-ms-discriminator-value` | `@discriminator` on base model |
| `$ref` to common-types `.json` | `import` from `@azure-tools/typespec-azure-resource-manager` |
| `allOf` composition | `extends` / `model is` |
| `x-ms-azure-resource: true` | `TrackedResource<T>` / `ProxyResource<T>` templates |

When flagging an issue, always use the syntax appropriate to the file
type being reviewed.

## Checklist

### 1. Examples and sample values

Examples are the most-flagged category in spec reviews. Verify:

- [Swagger] Every operation has at least one `x-ms-examples` reference
- [Both] Example files reside in `examples/` under the same API version directory
- [Both] Example request bodies and responses conform to the declared schema:
  - Required properties are present
  - Types match (no `"12345"` for an `integer` field)
  - Enum values are valid members
- [Both] Response examples include all schema-required fields and
  realistic values for optional fields where helpful
- [Both] Date-time values follow RFC 3339; UUIDs follow 8-4-4-4-12 format
- [Both] Placeholder values are realistic (avoid `"string"`, `"test"`, `0`)
- [TypeSpec] `@example` decorators provide both success and error scenarios

### 2. Descriptions and documentation

- [Both] Every model, property, operation, and parameter must have a `description`
- [Both] Descriptions start with a capital letter and end with a period
- [Both] Descriptions must be substantive — not just repeating the property name
  (bad: `"location": "The location."` good: `"location": "The Azure
  region where the resource is deployed, e.g. 'eastus2'."`)
- [Both] Operation descriptions should explain what the operation does, not just
  its HTTP method
- [TypeSpec] Include `@doc` on all TypeSpec models and properties

### 3. Breaking changes

**Determine the baseline API version first** — before flagging any
change as breaking, identify the previous stable (or preview) version:

1. Look for sibling version directories under the same service path:
   ```
   specification/<service>/resource-manager/Microsoft.<NS>/<ServiceName>/
   ├── stable/2024-01-01/
   └── preview/2024-06-01-preview/
   ```
2. Compare the changed spec against the most recent predecessor version.
3. **Only flag a change as breaking if it modifies or removes something
   that existed in the predecessor version.** New additions are not
   breaking.

Flag incompatible changes to the published API surface: [Both]
- Removed or renamed operations, parameters, or properties
- Changed parameter types (e.g., `string` → `integer`) or formats
- Removed enum values
- Made an optional request property required
- Changed URL path structure
- Removed a documented success status code (e.g., dropping `201` from
  PUT changes generated client behavior)

**API version validation:**
- [Swagger] `info.version` must follow `YYYY-MM-DD[-preview]` format
- [TypeSpec] `@versioned` enum values must follow `YYYY-MM-DD[-preview]` format
- [Both] GA version date must be later than any preceding preview date
- [Both] Stable directories must not contain `-preview` suffixed versions
- [Both] New preview versions should carry forward all GA functionality

### 4. ARM resource modeling

For ARM (`resource-manager/`) specifications:

**Path structure:** [Both]
- Tracked resources MUST be scoped under the standard ARM path:
  `…/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.{NS}/{resourceType}/{resourceName}`
- Provider namespace in paths must match the declared namespace
- Operations API at `/providers/Microsoft.{NS}/operations` must exist

**CRUD completeness:** [Both]
- Tracked resources MUST implement GET, PUT, PATCH, DELETE,
  ListByResourceGroup, and ListBySubscription
- Nested resources MUST have a List operation under their parent
- Proxy resources may have a reduced operation set but must justify it

**Resource model:**
- [Both] Top-level body properties limited to standard ARM fields (`id`,
  `name`, `type`, `location`, `tags`, `properties`, `systemData`, etc.)
- [Both] Custom fields go inside the `properties` bag
- [Swagger] Response models must inherit from common-types (`Resource`,
  `TrackedResource`, `ProxyResource`) via `allOf`
- [TypeSpec] Response models must use `TrackedResource<T>` or
  `ProxyResource<T>` templates from `@azure-tools/typespec-azure-resource-manager`
- [Swagger] PUT 200/201 responses must have `x-ms-azure-resource: true` in the
  hierarchy
- [Both] `systemData` must be present as a read-only property

**PUT/PATCH/DELETE rules:** [Both]
- PUT request and 200 response schemas must be identical
- PATCH body must not have required properties or defaults
- PATCH for tracked resources must support tag updates at minimum
- DELETE must define 200 + 204 + default (not 404 for missing resources)
- DELETE must not accept a request body

### 5. TypeSpec patterns

When reviewing TypeSpec (`.tsp`) files:

**Model design:**
- Use proper ARM template models (`TrackedResource<T>`,
  `ProxyResource<T>`) from `@azure-tools/typespec-azure-resource-manager`
- Properties that are set once at creation should use
  `@visibility("create", "read")`
- Read-only properties must use `@visibility("read")`
- Prefer `string` unions (extensible enums) over TypeSpec `enum` for
  values that may grow — use `union` with `@doc` on each member

**Decorators:**
- `@resource` must be applied to resource models
- `@armResourceOperations` must be used for ARM operation interfaces
- Versioning must use `@added`, `@removed`, `@renamedFrom` decorators
  from `@typespec/versioning`
- `@doc` decorators should be present on all public models, properties,
  and operations

**Anti-patterns to flag:**
- Inline anonymous models in operation signatures (extract and name them)
- Deeply nested model hierarchies (prefer composition over inheritance)
- Missing `@error` decorator on error response models
- Using raw `string` where a more specific scalar type exists (`url`,
  `uuid`, `utcDateTime`, `duration`)
- Defining custom error types instead of using Azure.Core `ErrorResponse`

### 6. Naming conventions

| Element | Convention | Applies to |
|---------|-----------|-----------|
| JSON property names | camelCase (not PascalCase, not snake_case) | Both |
| Model/type definitions | PascalCase | Both |
| Enum values | PascalCase | Both |
| URL path segments | camelCase for resource types, PascalCase for RP namespace | Both |
| Path parameters | Full resource name (`{virtualMachineName}`, not `{vmName}`) | Both |
| Operation IDs | `{ResourceType}_{Verb}` pattern | Swagger |
| Discriminator property | Prefer `kind` over `type` | Both |

Additional rules:
- [Both] Property names are case-sensitive — do not upper-case acronyms
  (`resourceId`, not `ResourceID` or `resourceID`)
- [Both] Avoid abbreviations unless industry-standard
- [Both] Resource model name should match singular form of the resource type

### 7. Property design

**Types and formats:**
- [Swagger] Integer properties must specify `format` (`int32` or `int64`)
- [Swagger] Date/time must use `format: date-time` (RFC 3339)
- [Swagger] UUID must use `format: uuid`
- [TypeSpec] Use built-in scalar types: `int32`, `int64`, `utcDateTime`, `uuid`
- [Both] Duration should use unit-in-name pattern (`backupTimeInMinutes`) or
  ISO 8601 for variable intervals only
- [Both] Boolean properties deserve scrutiny — prefer extensible enums for
  future-proofing

**Mutability:**
- [Swagger] Read-only properties must be marked `readOnly: true` or use
  `x-ms-mutability: ["read"]`
- [Swagger] Create-only properties use `x-ms-mutability: ["create", "read"]`
- [TypeSpec] Read-only properties must use `@visibility("read")`
- [TypeSpec] Create-only properties use `@visibility("create", "read")`
- [Both] Read-only properties (service-set, always present in responses)
  must not be marked `required` in the schema — when request and response
  share a schema, this forces SDK clients to provide a value they cannot set
- [Both] Avoid writable circular dependencies between resources

**Secrets:**

> Canonical rule: `rest-no-secrets-in-get-response` — see [Azure Guidelines §Resource Schema](#resource-schema--field-mutability).

- [Both] No secrets (passwords, keys, tokens) in GET/PUT/PATCH responses
- [Swagger] Secret properties must have `x-ms-secret: true`
- [TypeSpec] Secret properties must use `@secret`
- [Both] Secret retrieval via POST `list*` actions only
- [Both] PUT/PATCH responses must omit secret fields entirely

**Resource references:**
- [ARM] Use a single property with a fully qualified ARM resource ID
- [ARM] Do not split into separate subscription/resourceGroup/name properties
- [Both] For cross-resource references, use a single string property with
  the appropriate format (ARM: `format: arm-id`; data-plane: URL or ID string)

### 8. Enumerations

> Canonical rules: see [Azure Guidelines §Enums & Extensibility](#enums--extensibility).

- [Swagger] Every swagger enum must have `x-ms-enum` with a `name` property
- [Swagger] Set `modelAsString: true` unless the value set is provably closed
- [Both] Enum values must be PascalCase, non-empty, and unique across the spec
- [Both] Do not remove existing enum values (breaking change)
- [TypeSpec] Prefer `union` over `enum` for extensibility

### 9. Collections and pagination

> Canonical rules: see [Azure Guidelines §Collections & Pagination](#collections--pagination).

- [Both] List operations must return an object with a `value` array (not a
  bare array)
- [Swagger] Must include `x-ms-pageable` with `nextLinkName` specified
- [TypeSpec] Must use `@pagedResult`, `@items`, and `@nextLink` decorators
- [Both] Response must include a `nextLink` property (omit on last page rather
  than returning `null`)
- [Both] Each item in a collection should include its `id`
- [Both] Support paging from the start — adding it later is breaking
- [Both] Filter/sort query parameters (`filter`, `orderby`, `top`,
  `maxpagesize`) must NOT be prefixed with `$`

### 10. Long-running operations

> Canonical rules: see [Azure Guidelines §Long-Running Operations](#long-running-operations-lro).

- [Both] Operations taking >1 second at p99 must be LROs
- [Swagger] Mark with `x-ms-long-running-operation: true`
- [Swagger] Specify polling strategy via `x-ms-long-running-operation-options`
- [TypeSpec] Use `@pollingOperation` / ARM LRO operation templates
- [Both] Async POST/DELETE must return `202 Accepted` with polling headers
- [Both] LRO PUT returns `201 Created` or `200 OK`
- [Both] Do NOT implement PATCH as an LRO (use POST action pattern instead)

**ARM LRO pattern:**
- Poll via `Azure-AsyncOperation` or `Location` response headers
- Resource itself carries `provisioningState` (terminal values:
  `Succeeded`, `Failed`, `Canceled`)
- PUT returns the resource immediately; clients poll until
  `provisioningState` reaches a terminal value

**Data-plane LRO pattern:**
- Poll via `Operation-Location` response header
- Separate status monitor resource with `id`, `status`, and `error`
  fields (resource does NOT carry `provisioningState`)
- Status monitor auto-purges after ≥ 24 hours; may offer DELETE for GDPR

### 11. Error handling

> Canonical rules: see [Azure Guidelines §Error Handling](#error-handling).

- [Both] Every operation must have a `default` error response
- [Swagger] Error response must reference standard `ErrorResponse` from
  common-types via `$ref`
- [TypeSpec] Use `Azure.Core.ErrorResponse` from `@azure-tools/typespec-azure-core`
- [Both] Error structure: `{ error: { code, message, target?, details?,
  innererror? } }`
- [Both] Do not document specific HTTP error codes unless the response schema
  differs from the default

### 12. Common-types usage

[Swagger] ARM specs must reference the appropriate `common-types` version via
`$ref` for:
- Resource base types (`Resource`, `TrackedResource`, `ProxyResource`)
- Error types (`ErrorResponse`, `ErrorDetail`, `ErrorAdditionalInfo`)
- Standard parameters (`SubscriptionIdParameter`,
  `ResourceGroupNameParameter`, `ApiVersionParameter`,
  `LocationParameter`)
- System metadata (`systemData`)
- Identity (`ManagedServiceIdentity`, `UserAssignedIdentity`)
- SKU and Plan (`Sku`, `Plan`)
- Check name availability (`CheckNameAvailabilityRequest`,
  `CheckNameAvailabilityResponse`)
- Operations (`Operation`, `OperationListResult`, `OperationStatusResult`)
- Private links (`PrivateEndpointConnection`, `PrivateLinkResource`)
- Encryption (`encryptionProperties`, `KeyVaultProperties`)
- Location metadata (`locationData`)

Use `$ref` to common-types rather than redefining standard structures.
Verify `$ref` paths are valid and point to the correct version (v5 for
new APIs).

[TypeSpec] ARM specs must import the appropriate versioned library:
- `import "@azure-tools/typespec-azure-resource-manager"`
- Use `TrackedResource<T>`, `ProxyResource<T>` template models
- Use `Azure.ResourceManager.CommonTypes` for standard types
  (includes `ManagedServiceIdentity`, `Sku`, `Plan`,
  `PrivateEndpointConnection`, `azureLocation`, `EncryptionConfiguration`)
- Use `@armProviderNamespace` and `@armResourceOperations`

### 13. Nested vs. inline design

Use nested resources when:
- The collection is large or unbounded
- Elements need their own lifecycle (separate CRUD)
- Elements have separate RBAC requirements
- Elements need their own unique identifier (ARM: resource ID; data-plane: URL)

Use inline properties when:
- The property set is small and intrinsic to the parent
- Properties must be operated on together with the parent
- The set is not expected to grow significantly

**Never model both** — a collection must not be both an inline array
and a nested resource type.

### 14. Azure Resource Graph compatibility *(ARM only)*

- Do NOT embed child resources inline in parent GET responses
- Do NOT include child resource count properties on the parent
- Do NOT model customer data (PII, user content) in control plane
  properties
- Do NOT remove properties between API versions until fully deprecated

## Azure REST API Guidelines — Canonical References

The checklist above (§1–14) synthesizes the most common review feedback into
actionable items. For the **authoritative** DO / DO NOT rules, always consult
the two canonical documents below. These documents are maintained by the
Azure API Stewardship Board and take precedence over any summary.

### Required documents

| Document | Source | Key topics |
|----------|--------|------------|
| **Azure REST API Guidelines** | [`microsoft/api-guidelines` — `azure/Guidelines.md`](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md) | URL design, HTTP methods & status codes, JSON conventions, enums, polymorphism, error handling, versioning, resource schema, collections & pagination, actions, LRO, conditional requests, headers, deprecation |
| **Considerations for Service Design** | [`microsoft/api-guidelines` — `azure/ConsiderationsForServiceDesign.md`](https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md) | Hero scenarios, naming conventions, common property names, resiliency, preview lifecycle, error design principles, pagination design, action operations, LRO design patterns |

### How to fetch (mandatory — Step 0)

The Spectre workflow requires you to fetch and read both documents at the
start of every review. Use the `bash` tool:

```bash
# 1. Azure REST API Guidelines (≈ 4 000 lines)
curl -sL "https://raw.githubusercontent.com/microsoft/api-guidelines/vNext/azure/Guidelines.md"

# 2. Considerations for Service Design (≈ 1 500 lines)
curl -sL "https://raw.githubusercontent.com/microsoft/api-guidelines/vNext/azure/ConsiderationsForServiceDesign.md"
```

After fetching, internalize the rules and apply them alongside the checklist.
Cite specific rule IDs (e.g. `http-url-casing`, `naming-boolean`) from the
canonical documents when flagging violations.

### What to look for

| Enforcement level | Meaning | Review treatment |
|-------------------|---------|------------------|
| ✅ **DO** | Mandatory requirement | Flag violation as 🔴 Breaking or 🟡 Design concern |
| ☑️ **SHOULD** | Strong recommendation | Flag violation as 🟡 Design concern |
| ✔️ **MAY** | Optional guidance | Flag only if the omission causes a concrete problem |
| ⚠️ **SHOULD NOT** | Strong discouragement | Flag violation as 🟡 Design concern |
| 🚫 **DO NOT** | Prohibition | Flag violation as 🔴 Breaking |

## Concrete Rules Extracted from Review Data

The following rules were distilled from **all 949 semantic clusters** of
reviewer feedback (6,483 threads from 1,226 PRs). Each rule is a pattern
that human reviewers consistently enforce. Rules are grouped by theme and
ordered by frequency (thread count). Resolution percentages indicate how
often the reviewer feedback was accepted. Each heading shows the total
cluster count for the theme; only the most significant rules are listed
below.

**File-type note:** Concrete rules below may reference Swagger-specific
concepts (`$ref`, `x-ms-*` extensions, `format:`) or TypeSpec-specific
concepts (`@decorator`, `union`, `import`). Apply each rule only to the
matching file type. Use the equivalence table in
[File-type awareness](#file-type-awareness) to translate when needed.

Note: theme groupings here are finer-grained than the Mined
Insights table above — some clusters span multiple themes, so thread
counts here may not match Mined Insights percentages exactly.

### Examples & Sample Values (246 threads, 52 rules)

- **Include all properties in examples** (21 threads, 95% resolved): Ensure all defined properties are included in example payloads, especially nested properties.

### Descriptions & Documentation (2084 threads, 333 rules)

- **Align Endpoint Descriptions** (189 threads, 75% resolved): Ensure the description and name for service endpoints are consistent and use 'endpoint'.
- **Documentation Clarity and Tense** (41 threads, 93% resolved): Clarify documentation comments; use past tense for exception descriptions; avoid 'Currently' if it implies a changing state.
- **Validate name availability** (36 threads, 100% resolved): Ensure name validation and availability checks are clearly documented and correctly implemented for resource creation.

### Versioning & Lifecycle (487 threads, 46 rules)

- **Update Dependency Versions** (188 threads, 81% resolved): Update @useDependency to the latest stable version, e.g., v1_0_Preview_2.

### Enums & Allowed Values (496 threads, 55 rules)

- **Restrict additionalProperties** (30 threads, 37% resolved): Disallow use of additionalProperties unless explicitly needed for extensibility.

### TypeSpec Patterns (77 threads, 15 rules)

- **Define client decorators in client.tsp** (25 threads, 84% resolved): Place @client and related decorators in a dedicated client.tsp file, not in main.tsp or referenced files.
- **Use @encodedName for JSON** (7 threads, 100% resolved): Use @encodedName decorator for JSON property names instead of @projectedName.

### ARM Resource Modeling (348 threads, 36 rules)

- **ProvisioningState Values** (7 threads, 86% resolved): Ensure ProvisioningState has consistent and correct values; use American English spelling 'Canceled' (single 'l', not 'Cancelled').
- **Resource Kind Property** (5 threads, 100% resolved): Include 'kind' as a discriminator property; prefer 'kind' over 'name' or 'type' for polymorphic dispatch.

### Naming Conventions (811 threads, 105 rules)

- **Use domain-appropriate property names** (10 threads, 90% resolved): Choose property names that reflect the customer-facing concept rather than internal infrastructure terms (e.g., prefer 'replica' over 'pods').

### Long-Running Operations (127 threads, 12 rules)

- **LRO Terminal States** (3 threads, 67% resolved): Avoid adding non-standard terminal states like PartialFailed or skipped; use standard LRO status values.

### Spec Structure & Hygiene (535 threads, 116 rules)

- **Consolidate OpenAPI Files** (51 threads, 59% resolved): Update to a single OpenAPI file and avoid redundant or conflicting endpoint definitions.
- **Avoid explicit nulls** (16 threads, 81% resolved): Do not send or return explicit null values; make properties optional instead.
- **Validate pattern and length constraints** (11 threads, 73% resolved): Specify patterns that allow hyphens and use maxLength instead of length constraints in patterns.

## Output format

For each finding, include:

- **File and line / JSON path**
- **Severity**: 🔴 Breaking, 🟡 Design concern, 🔵 Suggestion
- A one-line description referencing the specific rule
- A concrete suggested fix

If the specification looks good, say so explicitly in one sentence.

## Mined Insights — What Reviewers Actually Flag

Analysis of **6,483 review threads** across **1,226 PRs** (Jan 2024 – Mar
2026), clustered into **949 semantic groups** with **520 near-duplicates**
identified. Labeled via gpt-4.1-mini on GitHub Models.

| Theme | % of threads | Resolution | Implication |
|-------|-------------|------------|-------------|
| Examples/samples | 21.3% | 60.6% ⚠️ | Most common AND lowest resolution rate — example mismatches are persistent pain points |
| Descriptions/docs | 9.0% | 78.6% | Missing or low-quality descriptions — easy wins but frequently missed |
| Versioning/api-version | 7.4% | 76.1% | Preview/stable mismatches, wrong date formats, missing api-version params |
| Enum design | 6.5% | 66.8% | Missing `x-ms-enum`, `modelAsString: false` when should be `true` |
| TypeSpec patterns | 6.4% | 76.6% | Growing fast with TypeSpec adoption — decorator usage, model inheritance |
| Property design | 6.1% | 74.0% | Required/optional mismatches, nullable properties, additionalProperties |
| Error handling | 5.8% | 75.2% | Missing default error response, custom error schemas |
| Type/format | 5.7% | 77.1% | Missing `format` on integers, wrong date-time, using `string` for `uuid` |
| ARM resource modeling | 5.5% | 67.4% | Resource hierarchy, CRUD completeness — harder to fix post-design |
| LRO patterns | 5.1% | 68.2% | Missing polling metadata, wrong final-state-via, PATCH as LRO |
| Ref/schema structure | 4.2% | 75.2% | $ref paths, allOf composition, definition reuse |
| Naming | 3.7% | 75.9% | camelCase violations, abbreviations, inconsistent resource naming |
| Breaking changes | 3.6% | 74.6% | Removed properties, narrowed enums, changed parameter types |
| x-ms extensions | 3.1% | 69.8% | client-flatten, client-name, discriminator usage |
| Common-types | 2.9% | 67.0% | Not reusing standard ARM types, wrong common-types version |
| Response codes | 1.8% | 63.6% | Wrong status codes, missing 204 on DELETE |
| Readonly/visibility | 1.7% | 69.7% | Missing readOnly, wrong x-ms-mutability |
| Secrets/security | 1.6% | 71.7% | Secrets in GET responses, missing x-ms-secret |
| Operation naming | 1.4% | 85.6% | OperationId patterns — easiest to resolve |
| Pagination | 0.4% | 48.1% | Lowest resolution rate — design-level disagreements |

**⚠️ Low-resolution themes** (< 70% resolved) indicate areas where
feedback is often contentious or requires significant redesign:
examples (60.6%), pagination (48.1%), response codes (63.6%),
enum design (66.8%), common-types (67.0%), ARM modeling (67.4%).

**Top reviewed services:** AI (406), App Service (392),
Cognitive Services (311), Event Grid (212), ML Services (189),
Container Service (180), Search (170).

**Top reviewers by volume:** TimLovellSmith (904), catalinaperalta (499),
mentat9 (402), weidongxu-microsoft (391), ramoka178 (264),
razvanbadea-msft (259), mikekistler (228).

**Overall resolution rate:** 76% of threads were resolved.

## Examples

### Good finding

> 🔴 **Breaking** — `specification/compute/resource-manager/.../virtualMachines.json`
> path `/providers/Microsoft.Compute/virtualMachines/{vmName}`
> The `provisioningState` property was removed from the GET 200
> response. This property exists in the `2024-01-01` stable version.
> **Fix:** Keep the property and add `description: "Deprecated"` if no
> longer used. Do not remove until a new major API version.

### Bad finding (too noisy — do NOT flag these)

> 🔵 — `specification/compute/.../examples/GetVM.json`
> The example response has an extra whitespace.
>
> *(Example files and formatting are out of scope.)*