Azure / Azure/typespec-azure

Epic: Unified Examples Format

Open
#4,831 0 comments 0 reactions 0 assignees View on GitHub
epic feature needs-area
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

**Epic** tracking the rollout of the **Unified Examples Format** in `Azure/typespec-azure` — a single `examples.yaml` per service that replaces ~282K individual `x-ms-examples` JSON files.

RFC: https://github.com/Azure/azure-rest-api-specs/blob/rfc/unified-examples-format/documentation/rfc/unified-examples-format.md

Examples are authored once per service in YAML, version-aware via `since`, joined to Swagger operations through an `x-id` extension. Version ordering comes from `service.yaml` (see the [service.yaml epic](https://github.com/Azure/typespec-azure/issues/4825)).

### Rollout

### Early august
- [ ] #4832 — `examples.yaml` JSON Schema + `examples-validate`
- [ ] #4833 — `examples-migrate` tool
- [ ] #4834 — `examples-resolve` tool
- [ ] #4835 — `x-id` emission: `typespec-autorest` + transitional JSON

## August-September
- [ ] #4836 — TCGC + consumers adoption
- [ ] #4837 — Auxiliary tooling: `examples-scaffold` + `examples-diff`

## Early September
- [ ] #4838 — Pilot migration (EventGrid) + CI round-trip
- [ ] #4839 — Migrate all services to `examples.yaml`

## January 2027
- [ ] #4840 — Disable old example tooling
- [ ] #4841 — Delete all `x-ms-examples` JSON files

_Child issues are attached as sub-issues below._

Contributor guide

Open the contributing guide

Research direction

Start by reading the linked unified-examples-format RFC and the rollout checklist in this issue. Then follow the child issues #4832 through #4841, beginning with the specific sub-issue that has an actionable task. The epic is complete when the listed tooling, migration, adoption, and cleanup milestones are finished.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.