From ce3303352f99302c37ac4dbfc373103a4eb53b09 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Wed, 21 Oct 2026 15:46:41 -0400 Subject: [PATCH] docs(examples): document authoring and published editor schema --- packages/typespec-azure-examples/README.md | 100 ++++++++++++++++++++- 1 file changed, 99 insertions(+), 1 deletion(-) diff --git a/packages/typespec-azure-examples/README.md b/packages/typespec-azure-examples/README.md index 33ed49111b..38dc4659e1 100644 --- a/packages/typespec-azure-examples/README.md +++ b/packages/typespec-azure-examples/README.md @@ -11,7 +11,7 @@ services). See the RFC: _Unified Examples Format_. ## Format ```yaml -$schema: https://raw.githubusercontent.com/Azure/azure-rest-api-specs/main/schemas/examples.schema.yaml +# yaml-language-server: $schema=https://unpkg.com/@azure-tools/typespec-azure-examples@0.2.1/dist/schema/dist/ExamplesYaml.json $namespace: Microsoft.EventGrid CaCertificates.get: @@ -48,6 +48,104 @@ CaCertificates.get: - Optional `id` is the filename stem: `id: GetWidget` generates `GetWidget.json`. Existing `legacyFilename: GetWidget.json` remains supported. Lineages still use titles. +## Authoring workflow + +In `azure-rest-api-specs`, run `pnpm install` from the repository root. The root install +exposes `pnpm tsp-examples`; other repositories can install +`@azure-tools/typespec-azure-examples` as a development dependency. + +Check `pnpm tsp-examples --help` before using a command from this document. Published +version 0.2.1 includes `validate`, but not `add`. The separate migration and expansion +binaries are available as `pnpm tsp-examples-migrate` and +`pnpm tsp-examples-legacy-expand`. + +### Adding or editing an example + +1. Author `examples.yaml` beside `main.tsp` and `service.yaml`, or keep related operations + together in `examples/.yaml`. An operation and all its version variants must + stay in one file. Existing specs-repository checks require an `examples/` directory, + so the per-interface layout avoids adding directory placeholders. +2. Use the canonical operation key, not a language SDK method name: + `CaCertificates_Get` in Swagger maps to `CaCertificates.get`; a standalone ID such as + `GetSchemaById` keeps its spelling. `$namespace` is the TypeSpec service namespace. +3. Put values in their HTTP locations: `request.path`, `query`, `headers`, or `body`. + The body is its wire payload, without the legacy Swagger body-parameter wrapper. + Responses use numeric status keys, with optional `headers` and `body`. +4. Use `id` without `.json` when the generated filename needs to be preserved. `title` + is optional display text, but it also groups version variants into lineages: keep + it unchanged within a lineage. Different examples on one operation need distinct titles. +5. Omit the request `api-version`. Use `{api-version}` only where a value should contain + the selected version; keep an intentionally different historical version literal. + +From the repository root, validate and regenerate: + +```bash +pnpm tsp-examples validate path/to/project --warn-as-error +pnpm exec tsp compile path/to/project +``` + +Edit YAML, not the emitted `stable//examples/*.json` or +`preview//examples/*.json`. Commit the regenerated artifacts with the YAML. +Preserve existing sample values and titles when changing only the authoring format. + +### Adding an API version + +First add the version to the TypeSpec definition and compile it so the versioned Swagger +and adjacent `service.yaml` are current. An unchanged example needs no new entry: its base +or latest applicable `since` variant carries forward. + +For changed example data, append a **complete** request/response variant with the same +title and a quoted `since` from `service.yaml`. This is a replacement value for that +version onward, not a partial patch. Do not modify an older variant if its historical +output must stay unchanged. A newly introduced example also needs `since` when it must +not appear in earlier versions. + +When the installed CLI lists `add`, the command below can prepare new/changed entries; +review its cloned values and fill in generated skeletons before committing: + +```bash +pnpm tsp-examples add path/to/project --api-version 2025-01-01 --dry-run +pnpm tsp-examples add path/to/project --api-version 2025-01-01 +``` + +If `add` is unavailable, author those variants manually. Version selection follows +`service.yaml` order, including version strings that are not full dates. Do not use +this workflow to remove an example in a later version; see the removal limitation below. + +### Migrating an existing service + +Keep the original JSON examples until migration and compilation have been compared: + +```bash +pnpm tsp-examples-migrate path/to/swagger-root --out path/to/project --service path/to/project/service.yaml --split-by-interface --dry-run --warn-as-error +``` + +`swagger-root` must contain the `stable/` and `preview/` trees; it can differ from the +TypeSpec project directory. Review the preview, then run without `--dry-run`. +Compile the project and compare every migrated version's example filenames, titles, +parameter values, response values, and Swagger references. Only then remove the authored +JSON under the project's old `examples//` directories. Retain generated JSON +referenced by Swagger and leave historical Swagger-only versions outside the migration unchanged. + +### Editor support and validation guarantees + +The JSON Schema is already published inside the package. The version-pinned URL used in +the modeline above provides completion and structural checks in YAML language-server +editors for either file layout. The same URL can be associated with `**/examples.yaml` +and `**/examples/*.yaml` in editor settings. Pin a schema version supported by the installed +tooling; no repository-specific schema server is required. + +Editor schema checks do not establish that an operation exists or that example values +match the API. In published examples 0.2.1, `validate` also checks only the document's +format and version/placement rules. Continue to run TypeSpec compilation and normal +API/SDK CI checks. + +If `pnpm tsp-examples validate --help` lists `--schema-only`, that release supports +API-aware validation: the normal command compiles `main.tsp` in memory using the project's +installed compiler/AutoRest emitter and checks values against the current API contract. +`--schema-only` explicitly selects the format-only check. Do not assume those capabilities +from an updated README alone; check the installed command's help. + ## `tsp-examples validate` Validate a service's example files against the JSON Schema and the format rules: