Azure / Azure/typespec-azure

Epic: service.yaml rollout

Open
#4,825 0 comments 0 reactions 0 assignees View on GitHub
epic feature needs-area
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

**Epic** tracking the rollout of **`service.yaml`** in `Azure/typespec-azure` — a machine-readable per-service version-metadata file that replaces the version-metadata role of `readme.md`.

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

`service.yaml` declares the ordered list of API versions for a service (with `swagger-files` for legacy swagger versions). It becomes the source of version ordering that the [Unified Examples Format](https://github.com/Azure/azure-rest-api-specs/blob/rfc/unified-examples-format/documentation/rfc/unified-examples-format.md) `since`-resolution depends on.

### Rollout
- [ ] #4826 — `service.yaml` schema + conversion tool + repo-wide migration
- [ ] #4827 — `typespec-autorest`: inject API versions from TypeSpec
- [ ] #4828 — TSV validation: require + sync-check `service.yaml`
- [ ] #4829 — Contributor docs: author API versions via `service.yaml`
- [ ] #4830 — Remove `readme.md`

_Child issues are attached as sub-issues below._

Contributor guide

Open the contributing guide

Research direction

Start with documentation/rfc/service-yaml.md, then review child issues #4826–#4830 to understand the rollout boundaries. The epic is done when the schema, conversion and validation work, TypeSpec version injection, contributor documentation, and readme.md removal are completed and all listed sub-issues are closed.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript, yaml
Domain
build-system, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.