Azure / Azure/typespec-azure

x-id emission: typespec-autorest + transitional JSON

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

Description

Part of the Unified Examples Format epic.

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

Add **`x-id` emission** to `@azure-tools/typespec-autorest`.

### Scope
- Emit an **`x-id`** extension (the full operation identity, `$namespace` + operation key) on every operation.
- **Stop embedding** `x-ms-examples` `$ref` blocks in generated Swagger.
- Transitional: optionally emit `x-ms-examples` JSON generated from the new format for consumers not yet migrated.
- Confirm the **doc-team pipeline** can consume `x-id` in place of the embedded `$ref`.

Contributor guide

Open the contributing guide

Research direction

Read documentation/rfc/unified-examples-format.md first, then trace x-id and x-ms-examples generation in @azure-tools/typespec-autorest and check the doc-team pipeline entry point. Done means every operation emits its full x-id, embedded x-ms-examples $ref blocks are removed, transitional JSON output is optional, and the pipeline consumes x-id.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, documentation, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.