Epic: Unified Examples Format
- 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
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