Azure / Azure/typespec-azure

examples-migrate tool

Open
#4,833 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

Build **`examples-migrate`**: convert existing `x-ms-examples` JSON into `examples.yaml`.

### Scope
- Read all `x-ms-examples` JSON for a service and emit a single `examples.yaml` (or `examples/.yaml` for large services).
- **Dedup across versions** into `since` variants (full restatement, no partial overrides).
- **Normalize embedded version strings to `{api-version}`** in headers and body values (e.g. `Location`, `Azure-AsyncOperation`, `nextLink`) so trivially-versioned variants collapse.
- Emit interface-relative operation keys under a single `$namespace`.

Depends on #4832 (schema).

Contributor guide

Open the contributing guide

Research direction

Start with the unified examples format RFC at documentation/rfc/unified-examples-format.md and the schema work in #4832. Inspect the existing x-ms-examples JSON for a service and define the migration entry point from the requested output structure. Done means producing examples.yaml or interface files with deduplicated since variants, normalized {api-version} values, and interface-relative operation keys under one $namespace.

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
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.