Azure / Azure/typespec-azure

Migrate all services to examples.yaml

Open
#4,839 0 comments 0 reactions 0 assignees View on GitHub
eng feature triaged:core
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

Part of #4831.

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

**Roll the examples migration out across all remaining services** after the EventGrid pilot (#4838) proves the flow.

### Scope
- Run `examples-migrate` (#4833) for every service to produce `examples.yaml` (dedup into `since` variants, `{api-version}` normalization).
- Validate each with `examples-validate` (#4832) and confirm per-version round-trip against the original `x-ms-examples`.
- Stage the migration service-by-service (or in batches) to keep PRs reviewable.
- Enforce in CI that new/updated examples use the new format once a service is migrated.
- Track and remediate services that need manual attention (unusual `x-ms-examples`, non-ARM URL shapes, etc.).

### Out of scope
- Removing the legacy `x-ms-examples` JSON files (final cleanup once all consumers, incl. TCGC #4836, are on the new format).

Depends on #4838 (EventGrid pilot + CI round-trip).

Contributor guide

Open the contributing guide

Research direction

Start with the unified examples RFC and the EventGrid pilot in #4838, then inspect the examples-migrate tool in #4833 and examples-validate in #4832. Done means remaining services have validated examples.yaml files with per-version round-trips, staged reviewable changes, and CI enforcement for migrated services.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
ci-cd, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.