| name | azure-api-review |
| license | MIT |
| metadata | {"version":"1.0.0"} |
| description | Shared Azure REST API review rules for OpenAPI (Swagger) and TypeSpec specifications. Contains cross-cutting review guidelines used by ARM API reviewers, code review agents, and CI workflows. USE FOR: reviewing API specs for naming, security, property design, resource lifecycle, and versioning compliance. DO NOT USE FOR: authoring TypeSpec files (use azure-typespec-author), SDK generation, or releasing packages. |
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 |
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:
Relationship to Instruction Files
The format-specific instruction files reference these shared rules:
| Instruction File | Applies To | Relationship |
|---|
armapi-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) |
