# azure/azure-rest-api-specs architecture

> Architecture diagram of the GitHub repository azure/azure-rest-api-specs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azure/azure-rest-api-specs
- Repository: https://github.com/azure/azure-rest-api-specs

## Overview

Azure REST API Specifications is the canonical source repository for Azure REST API definitions. Contributors author specifications; the engineering tools support validation, change assessment, breaking-change checks, SDK generation, and release planning. The README documents SDK and API-reference generation as a next step after a specification is complete. Source excerpts show selected internal calls, but many tools and the specification tree were not sampled, so their internal wiring is omitted.

Main entry points: [`eng/tools/openapi-diff-runner/src/commands.ts`](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/commands.ts) (Diff commands), [`eng/tools/typespec-validation/src/index.ts`](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/index.ts) (TypeSpec validation), [`eng/tools/openapi-diff-runner/src/index.ts`](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/index.ts) (Breaking-change runner), [`specification/automation/resource-manager/Microsoft.Automation/Automation/preview/2023-05-15-preview/package.json`](https://github.com/azure/azure-rest-api-specs/blob/main/specification/automation/resource-manager/Microsoft.Automation/Automation/preview/2023-05-15-preview/package.json) (API definitions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_specs["API specifications"]
  node_api_specs["API definitions<br/>[package.json]"]
end

subgraph group_validation["Specification validation"]
  node_type_validation["TypeSpec validation<br/>[index.ts]"]
  node_service_rule["Service manifest rule<br/>[service-yaml.ts]"]
  node_service_parser["Manifest parser<br/>[service-yaml.ts]"]
  node_client_rule["Client import rule"]
  node_migration["Migration comparison<br/>[index.ts]"]
  node_migration_compare["Document comparison<br/>[compare.ts]"]
end

subgraph group_change["Change assessment"]
  node_lint_diff["Lint change analysis<br/>[processChanges.ts]"]
  node_impact["PR impact assessment<br/>[impact.ts]"]
  node_oas_diff["Breaking-change runner<br/>[index.ts]"]
  node_oas_commands["Diff commands<br/>[commands.ts]"]
  node_oas_helpers["Diff command helpers<br/>[command-helpers.ts]"]
  node_breaking_detector["Breaking-change detection"]
  node_message_processing["Diff message processing"]
end

subgraph group_sdk["SDK workflows"]
  node_sdk_runner["SDK generation runner<br/>[commands.ts]"]
  node_sdk_helpers["SDK generation helpers<br/>[command-helpers.ts]"]
  node_release_plan["Release planning<br/>[index.ts]"]
end

node_contributors(("Contributors"))
node_sdk_docs["SDKs and API docs"]

node_contributors -->|"author specifications"| node_api_specs
node_api_specs -->|"generate next"| node_sdk_docs
node_service_rule -->|"parses manifest"| node_service_parser
node_type_validation -.->|"runs rule"| node_service_rule
node_type_validation -.->|"runs rule"| node_client_rule
node_migration -->|"compares documents"| node_migration_compare
node_oas_diff -->|"builds context"| node_oas_helpers
node_oas_diff -->|"validates changes"| node_oas_commands
node_oas_commands -->|"detects changes"| node_breaking_detector
node_oas_commands -->|"processes messages"| node_message_processing
node_sdk_runner -->|"generates artifacts"| node_sdk_helpers
node_release_plan -.->|"plans releases"| node_sdk_docs

click node_api_specs "https://github.com/azure/azure-rest-api-specs/blob/main/specification/automation/resource-manager/Microsoft.Automation/Automation/preview/2023-05-15-preview/package.json"
click node_type_validation "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/index.ts"
click node_service_rule "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/rules/service-yaml.ts"
click node_service_parser "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/service-yaml.ts"
click node_client_rule "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/rules/client-tsp-import.ts"
click node_migration "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-migration-validation/src/index.ts"
click node_migration_compare "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-migration-validation/src/compare.ts"
click node_lint_diff "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/lint-diff/src/processChanges.ts"
click node_impact "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/summarize-impact/src/impact.ts"
click node_oas_diff "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/index.ts"
click node_oas_commands "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/commands.ts"
click node_oas_helpers "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/command-helpers.ts"
click node_breaking_detector "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/detect-breaking-change.ts"
click node_message_processing "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/utils/oad-message-processor.ts"
click node_sdk_runner "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/spec-gen-sdk-runner/src/commands.ts"
click node_sdk_helpers "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/spec-gen-sdk-runner/src/command-helpers.ts"
click node_release_plan "https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/release-plan/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_specs toneBlue
class node_type_validation,node_service_rule,node_service_parser,node_client_rule,node_migration,node_migration_compare toneAmber
class node_lint_diff,node_impact,node_oas_diff,node_oas_commands,node_oas_helpers,node_breaking_detector,node_message_processing,node_sdk_docs toneMint
class node_sdk_runner,node_sdk_helpers,node_release_plan toneRose
class node_contributors toneIndigo
```

## Components

### API specifications

- [API definitions](https://github.com/azure/azure-rest-api-specs/blob/main/specification/automation/resource-manager/Microsoft.Automation/Automation/preview/2023-05-15-preview/package.json): `specification/automation/resource-manager/Microsoft.Automation/Automation/preview/2023-05-15-preview/package.json`

### Specification validation

- [TypeSpec validation](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/index.ts): `eng/tools/typespec-validation/src/index.ts`
- [Service manifest rule](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/rules/service-yaml.ts): `eng/tools/typespec-validation/src/rules/service-yaml.ts`
- [Manifest parser](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/service-yaml.ts): `eng/tools/typespec-validation/src/service-yaml.ts`
- [Client import rule](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-validation/src/rules/client-tsp-import.ts): `eng/tools/typespec-validation/src/rules/client-tsp-import.ts`
- [Migration comparison](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-migration-validation/src/index.ts): `eng/tools/typespec-migration-validation/src/index.ts`
- [Document comparison](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/typespec-migration-validation/src/compare.ts): `eng/tools/typespec-migration-validation/src/compare.ts`

### Change assessment

- [Lint change analysis](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/lint-diff/src/processChanges.ts): `eng/tools/lint-diff/src/processChanges.ts`
- [PR impact assessment](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/summarize-impact/src/impact.ts): `eng/tools/summarize-impact/src/impact.ts`
- [Breaking-change runner](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/index.ts): `eng/tools/openapi-diff-runner/src/index.ts`
- [Diff commands](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/commands.ts): `eng/tools/openapi-diff-runner/src/commands.ts`
- [Diff command helpers](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/command-helpers.ts): `eng/tools/openapi-diff-runner/src/command-helpers.ts`
- [Breaking-change detection](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/detect-breaking-change.ts): `eng/tools/openapi-diff-runner/src/detect-breaking-change.ts`
- [Diff message processing](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/openapi-diff-runner/src/utils/oad-message-processor.ts): `eng/tools/openapi-diff-runner/src/utils/oad-message-processor.ts`

### SDK workflows

- [SDK generation runner](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/spec-gen-sdk-runner/src/commands.ts): `eng/tools/spec-gen-sdk-runner/src/commands.ts`
- [SDK generation helpers](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/spec-gen-sdk-runner/src/command-helpers.ts): `eng/tools/spec-gen-sdk-runner/src/command-helpers.ts`
- [Release planning](https://github.com/azure/azure-rest-api-specs/blob/main/eng/tools/release-plan/src/index.ts): `eng/tools/release-plan/src/index.ts`

### Other components

- **Contributors**
- **SDKs and API docs**

## Connections

- Contributors → API definitions: author specifications (evidence: `README.md`)
- API definitions → SDKs and API docs: generate next (evidence: `README.md`)
- Service manifest rule → Manifest parser: parses manifest (evidence: `eng/tools/typespec-validation/src/rules/service-yaml.ts`)
- TypeSpec validation → Service manifest rule: runs rule
- TypeSpec validation → Client import rule: runs rule
- Migration comparison → Document comparison: compares documents (evidence: `eng/tools/typespec-migration-validation/src/index.ts`)
- Breaking-change runner → Diff command helpers: builds context (evidence: `eng/tools/openapi-diff-runner/src/index.ts`)
- Breaking-change runner → Diff commands: validates changes (evidence: `eng/tools/openapi-diff-runner/src/index.ts`)
- Diff commands → Breaking-change detection: detects changes (evidence: `eng/tools/openapi-diff-runner/src/commands.ts`)
- Diff commands → Diff message processing: processes messages (evidence: `eng/tools/openapi-diff-runner/src/commands.ts`)
- SDK generation runner → SDK generation helpers: generates artifacts (evidence: `eng/tools/spec-gen-sdk-runner/src/commands.ts`)
- Release planning → SDKs and API docs: plans releases