Azure / Azure/typespec-azure

examples.yaml JSON Schema + examples-validate

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

Publish the **JSON Schema** for `examples.yaml` (at the `$schema` URL) and build the **`examples-validate`** tool.

### Validation rules (RFC §3)
- `$`-prefixed file metadata (`$schema`, `$namespace`); bare top-level keys are always operations.
- Response status codes are **bare integer keys**; `default`/`2XX` ranges are **not allowed**.
- `since` values are **quoted** and **must be a version listed in `service.yaml`**.
- Per lineage: **at most one entry without `since`** (the base) and **unique `since`** values.
- An operation's full lineage lives in **one file**; split large services **by interface** (`examples/.yaml`).
- The only supported placeholder is `{api-version}`.

Contributor guide

Open the contributing guide

Research direction

Read the linked unified-examples-format RFC, especially §3, then locate the examples-validate entry point and inspect examples.yaml and service.yaml handling. Done means the JSON Schema is published at the $schema URL and the tool enforces the metadata, status-code, version, lineage, file-layout, and placeholder rules listed here.

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
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.