Azure API Review

Azure API Review -- Shared Rules

This skill contains cross-cutting API review rules that apply regardless of whether the specification is authored in OpenAPI v2 (Swagger) JSON or TypeSpec. These rules are the single source of truth -- referenced by the format-specific instruction files and review agents.

When to Use

• Reviewing Azure REST API specification PRs (OpenAPI JSON or TypeSpec)
• Building review agents or CI workflows that validate API specs
• Understanding Azure API design rules that span both OpenAPI and TypeSpec formats

Reference Files

Each reference file covers one cross-cutting rule area with:

• The canonical rule definition
• Links to authoritative external sources (RPC contract, Azure REST API Guidelines, TypeSpec docs)
• Format-specific guidance for OpenAPI JSON and TypeSpec
• Rule IDs for citation in review findings

| Reference | Rule Area | Key Rule IDs |

| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------- |

| secret-detection.md | Proactive secret detection in API properties | SEC-SECRET-DETECT |

| property-mutability.md | Write-only, conditional read-only, immutability, update tolerance, and field ownership rules | OAPI027, OAPI020, OAPI029, OAPI030, OAPI031, OAPI034 |

| provisioning-state.md | provisioningState requirements for ARM resources | RPC-Async-V1-02, RPC-Async-V1-03 |

| naming-conventions.md | Naming, casing, and Azure terminology | -- |

| enum-best-practices.md | Enum extensibility and boolean alternatives | -- |

| tracked-resource-lifecycle.md | Required CRUD operations and resource move for tracked ARM resources | RPC-Put-V1-22, RPC-Get-V1-05, RPC003 |

| policy-compatibility.md | Azure Policy compatibility rules for API design | PLCY001–PLCY009 |

| template-deployment.md | ARM Template Deployment engine compatibility | TD001–TD003 |

| availability-zones.md | Availability zone property contract and zone immutability | -- |

| field-ownership.md | Value preservation (array ordering, data types, casing) | OAPI024, OAPI025, OAPI026 |

| what-if-preflight-compliance.md | What-If noise prevention and preflight validation contract | WHATIF-001–005, PREFLIGHT-001–005 |

| lro-final-state-via.md | LRO polling and final-state-via decision table | -- |

| suppression-review-criteria.md | Suppression approval/rejection decision framework | RPC-SUPPRESS-GA, RPC-SUPPRESS-SCOPE |

| linter-rule-coverage.md | Linter rule ID → instruction file mapping (130+ rules) | -- |

| example-quality.md | Example file quality: orphan detection, coverage, descriptive values | EX-ORPHAN, EX-COVERAGE, EX-DESCRIPTIVE-VALUES |

| design-decisions.md | Grey-area design trade-off frameworks (10 decision matrices) | DD-001–DD-010 |

| pattern-validation.md | Allowlist vs. denylist pattern constraints; Unicode bypass risk; severity matrix | OAPI-PATTERN-ALLOWLIST |

Authoritative External Sources

These external documents are the upstream authorities. When they conflict with each other, the precedence order is:

• Azure Resource Provider Contract (RPC) -- ARM control-plane contract (highest precedence for ARM resources)
• Azure REST API Guidelines -- general Azure API design (highest precedence for data-plane)
• TypeSpec Azure library docs -- TypeSpec-specific patterns for Azure
• ARM wiki / RP guidelines -- supplementary ARM guidance

Design Principles

These principles guide how the ARM API Reviewer agent, its instruction

files, and reference files are designed and maintained:

• Expert persona. The agent operates as a seasoned

engineer -- meticulous, skeptical, and uncompromising on quality --

with years of hands-on experience designing APIs for Azure and other

cloud providers: globally distributed, highly scalable, reliable,

and secure services that have earned customer trust. It works

alongside experienced human reviewers who hold every Azure service

to the highest standards of security, reliability, consistency,

performance, and maintainability. Missing a violation means a broken

SDK, a security hole, or an inconsistency that millions of Azure

customers will encounter. Findings should reflect depth of

judgment, not mechanical rule-checking alone.

• Consistency and reusability. Every rule is defined in exactly one

place (a reference file or an instruction file section) and

cross-referenced everywhere else. No duplication. When the same

concept applies to OpenAPI and TypeSpec, the shared reference file

covers both formats. File structure, naming, upstream-alignment

comments, and severity levels follow uniform conventions across all

files.

• Low maintenance overhead. The files are designed so that

maintainers spend minimal effort. Updates are needed only when

upstream guidance (RPC contract, Azure REST API Guidelines, ARM

wiki) changes. When that happens, a maintainer refreshes the

affected instruction/reference files, updates the `Upstream

alignment` date, and the change propagates through all

cross-references automatically.

Maintenance & Upstream Alignment

The instruction files and reference files in this skill are **derived

from** the authoritative external sources listed above. They are not

replacements for those documents — they distill the most commonly

violated rules into a structured format optimized for LLM-based review

agents.

Why inline rules instead of raw document references: LLM review

agents produce more consistent, actionable findings when rules are

codified with explicit rule IDs, severity levels, and fix suggestions.

Raw upstream documents are prose-heavy and not structured for automated

consumption.

Keeping rules current:

• Each instruction file includes an Upstream alignment date in an

HTML comment at the top. This date indicates when the rules were last

verified against the upstream documents.

• When an upstream document changes a rule, the corresponding

instruction file MUST be updated to match. The upstream document

always takes precedence.

• Rules that overlap with existing linter checks are annotated with

(Also enforced by: ...). The review agent should check CI results

before flagging these to avoid duplicating linter findings.

• To avoid conflicts with the

azure-typespec-author

skill (used for TypeSpec code generation), coordinate rule changes

with that skill's maintainers. A rule flagged by the reviewer agent

should not contradict guidance given by the authoring agent.

• Formatting: After editing any .md file under skills/ or

agents/, run npm run format from the .github/ directory

(Prettier). Note: instruction files (*instructions.md) are excluded

from Prettier via .prettierignore and do not need formatting.

Repository Documentation

These documents in this repo provide additional context:

• Breaking changes guidelines
• Uniform versioning
• Directory structure
• OpenAPI authoring automated guidelines
• Swagger extensions
• CI fix guide
• TypeSpec dev process

Relationship to Instruction Files

The format-specific instruction files reference these shared rules:

| Instruction File | Applies To | Relationship |

| --------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |

| arm-api-review.instructions.md | specification//resource-manager//*.json | References shared rules + adds ARM-specific rules (path structure, PUT/PATCH/DELETE contracts, LRO, ARG compatibility) |

| openapi-review.instructions.md | specification/**/*.json | References shared rules + adds generic OpenAPI rules (file structure, x-ms extensions, examples, security definitions) |

| typespec-review.instructions.md | specification/**/*.tsp | References shared rules + adds TypeSpec-specific rules (decorators, project structure, anti-patterns) |