Azure / Azure/typespec-azure

service.yaml schema + conversion tool + repo-wide migration

Open
#4,826 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 #4825.

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

Define the **`service.yaml`** format and build the tooling to adopt it across the repo.

### Scope
- Define the format and **publish a JSON Schema** for editor validation + CI.
- Build a conversion tool that generates `service.yaml` from each service's `readme.md`:
- version tags → `versions` list
- swagger `input-file`s → `swagger-files` (only for swagger versions)
- Decide **granularity** (one file per RP vs per sub-service) to match today's `readme.md` granularity.
- Run repo-wide so a `service.yaml` lands **alongside** every `readme.md` (both coexist during transition).

### Out of scope
- Deleting `readme.md` (tracked separately).

Contributor guide

Open the contributing guide

Research direction

Start with documentation/rfc/service-yaml.md, then inspect existing service readme.md files to understand their current granularity and inputs. Identify the TypeScript conversion-tool entry point and schema or CI validation path before implementing. Done means a published schema, conversion tooling, and a service.yaml alongside every readme.md while both formats coexist.

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.