service.yaml schema + conversion tool + repo-wide migration
- 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
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