Changelog

All notable changes to the typespec-api-design skill.

1.3.1 - 2026-08-26

Currency + accuracy pass (full improve-skill audit). Two months of releases had landed since the last verification window; every tracked package pin was stale, one negative capability claim had flipped, and two issue citations pointed at unrelated threads.

Fixed - version currency (all nine tracked packages)

TypeSpec core moved two stable releases: @typespec/compiler/http/openapi3 1.13.0 -> 1.15.0 (2026-08-11); @typespec/rest/versioning 0.83.0 -> 0.85.0. Updated SKILL.md (ground-truth line now notes the locally installed tsp lags npm latest and must never be copied into pins; asymmetry-traps bullet; hard-rule #15 example; modern baseline), emitter-gotchas (track table + currency note + releases anchor), ci-validation (devDependencies), and the azure-data-plane package.json.
Azure packages converged on a shared family: azure-core/ARM/autorest 0.71.0, TCGC 0.71.2 (npm latest, 2026-08-26). The old "independent, lower track / not aligned with each other" wording replaced with current-family wording; the durable guard stands - the typespec-azure@X.Y.Z GitHub tag is still not a package's npm version.
New pin set compile-tested (representative spec installs and compiles clean under 1.15.0/0.85.0).

Fixed - superseded claims

GraphQL emitter shipped: @typespec/graphql released first-party 2026-07-17 (issue #1390 closed). The emitter-gotchas "don't exist yet" row flipped to shipped-with-date; SKILL.md stop condition and bundle-routing description updated while keeping this skill's REST/OpenAPI scope boundary.
AutoRest retirement tense: July 1, 2026 has passed; hard rule #13 and the migration bundle now state retirement as effective ("retired ... date has passed") instead of a future deadline.

Fixed - wrong citations

lro-pagination-versioning: the @added/@removed orphan-reference diagnostic cited microsoft/typespec#7388, which is actually a VS Code extension compatibility thread. Correct citation: #7035 (verified by direct fetch + GitHub search).
azure-arm: the @parentResource/Legacy-templates caveat cited Azure/typespec-azure#1389, which is actually a dependabot submodule-bump PR. Citation removed; gotcha text retained with an explicit verify-against-pinned-versions instruction.
generic-rest: Sunset header example weekday corrected (Wed -> Fri; 2027-01-01 verified via calendar).
azure-data-plane: HTTP-date citation refreshed from obsoleted RFC 7231 to RFC 9110.

Fixed - link rot

SKILL.md references: https://typespec.io/docs/emitters/openapi3/ 404s; updated to the current emitter guide path /docs/emitters/openapi3/openapi/.

Added

lro-pagination-versioning: short "Version-level retirement" subsection (whole-version sunset planning vs per-operation deprecation).
Hard rule #24 clarified: exactly ONE idempotency scheme per API surface (no mixing Idempotency-Key and Repeatability-*); generic-rest idempotency section gained PATCH scoping guidance (key + method + path + If-Match + body hash).
migration-from-openapi: tsp-openapi3 --namespace optional argument documented (current CLI surface).
emitter-gotchas: upgrade note that recent compiler releases changed using resolution and emitter options - re-run compile after upgrades.
review-checklist: two numbering/header mismatches fixed ("10/10 quality gate" -> "Quality gate"; Azure-specific section header now matches its actual item structure).

Verified correct (no change needed)

AsyncAPI (#2463 open), WebSocket (#4124 open), Record-key constraint (#2842 open) negative claims re-confirmed current.
RateLimit headers remain the IETF draft (draft-ietf-httpapi-ratelimit-headers-11, May 2026) - NOT yet an RFC; existing citation accurate.
All decorator/template/deprecation facts (FilterVisibility transition, TCGC SdkClient consolidation #3997, ARM @locationResource #4132), RFC 9745 Deprecation value format, RFC 8594, W3C Trace Context regex, SSRF/HMAC patterns, ARM three-terminal provisioning states, preview-suffix rule, repeatability semantics.
All 25 internal cross-references resolve.

Validation

External evidence baseline (2026-08-26): npm registry JSON for all 9 packages (spot-re-probed independently), microsoft/typespec + Azure/typespec-azure release feeds and merged-PR sweeps, AutoRest#5175, typespec.io docs pages (link-rot probe across all cited URLs), rfc-editor/W3C citations, local binary help output (tsp format --check confirmed present; no tsp lint).
No automated validator ships with this skill; validation was manual per its established convention.
Bumped frontmatter version to 1.3.1 and last_verified to 2026-08-26 in the same transaction as the content edits.

Honest unknowns

tsp init quick-start remains validated by command-shape cross-check only (interactive prompt cannot run headless in this environment); unchanged from prior passes.

1.3.0 - 2026-07-17

Added horizontal-scaling-by-default hard rules (#23-26): no server-affinity/session semantics in the contract, a client-supplied idempotency key required on mutating operations rather than shown only as an example, Retry-After/RateLimit-* headers required for backpressure so any replica behaves consistently, and a standard unauthenticated /health + /ready probe pair. Rule #24 applies to every API style (generic REST, Azure data-plane, ARM) - Idempotency-Key for generic APIs, Repeatability-Request-ID for Azure Core; it is not Azure-only. Infra-level HPA/replica/stateful-storage guidance already lives in aks-cluster-architecture; this closes the matching gap at the API-contract layer.

1.2.4 - 2026-06-16

Currency + accuracy pass. The June 2026 TypeSpec release shipped (~18h before this pass), and external re-verification against npm and the GitHub release pages surfaced a systematic version error: the skill had been quoting the typespec-azure@X.Y.Z GitHub monorepo release tag as if it were the individual @azure-tools/typespec-* npm package versions. The two are different number spaces. All version strings corrected to the real npm latest values and the tag-vs-package distinction documented so the error does not recur. Two reviewer-found correctness fixes also applied. No routing or hard-rule changes.

Fixed - version currency (TypeSpec core, June 2026 release)

TypeSpec core moved to the June release (typespec-stable@1.13.0, 2026-06-15): @typespec/compiler / @typespec/http / @typespec/openapi3 1.12.0 → 1.13.0; @typespec/rest / @typespec/versioning 0.81.0 → 0.83.0. Updated SKILL.md (Anti-Hallucination grounding list, asymmetry-traps note, hard-rule #15 pin example, modern baseline), emitter-gotchas (version-track table, currency note, releases anchor), and ci-validation (devDependencies example). 1.13.0 adds kind: project/entrypoint config and project-scoped compiler feature flags, and graduates the internal modifier - no decorator-surface break.

Fixed - version attribution (Azure packages: monorepo tag ≠ npm version)

Root cause: the skill listed @azure-tools/typespec-azure-core / -azure-resource-manager / -autorest as 0.68.0 and TCGC as 0.67.x. Those are GitHub monorepo release-tag numbers, not npm package versions. The real npm latest values (verified 2026-06-16) are dramatically lower and each package versions independently: @azure-tools/typespec-azure-core 0.61.0, -azure-resource-manager 0.60.1, -autorest 0.43.0, -client-generator-core (TCGC) 0.39.0. A 0.61 vs 0.68 / 0.39 vs 0.67 gap is far too large to be release lag - it confirms the tag/package conflation.
Corrected every Azure version string in SKILL.md (grounding items 3-5, both asymmetry-trap bullets, modern baseline), emitter-gotchas (track table + currency note), and the azure-data-plane package.json example.
Added a durable guard so this does not recur: SKILL.md modern baseline, the emitter-gotchas version-track section, and ci-validation now state explicitly that the typespec-azure@X.Y.Z GitHub monorepo tag is NOT a package's npm version, that the Azure packages run on an independent lower track (0.4x-0.6x) than the TypeSpec core (1.13.0) and are not aligned with each other, and that the real version must be resolved with npm view <package> version rather than copied from the tag.
The decorator/deprecation FACTS attributed to these releases (SdkOperationGroup→SdkClient, @operationGroup→@client, @locationResource→@parentResource(ArmLocationResource<...>)) were re-verified correct and retained - only the version numbers were wrong.

Fixed - reviewer-found correctness

azure-arm (provisioning state): the bundle claimed "ARM REQUIRES seven standard provisioning-state values". Per official Azure API-review guidance, ARM mandates only the three terminal values (Succeeded/Failed/Canceled, provided by ResourceProvisioningState); the non-terminal states (Creating/Updating/Deleting/Accepted) are RP-defined and recommended, not required. Reworded; the worked union example is retained.
generic-rest (Deprecation header): the Deprecation response header was cited as the IETF draft and its value described as "true" or an HTTP-date. The draft was published as RFC 9745 (March 2025), which also changed the value to a Structured-Field Date @<unix-timestamp> (e.g. Deprecation: @1688169599). Citation and value format corrected in both the prose and the code example.

Verified correct (no change needed)

AutoRest CLI / @autorest/* retirement July 1, 2026 (the @azure-tools/typespec-autorest emitter remains separate and supported) - re-confirmed via Azure/autorest#5175.
All TypeSpec/Azure decorator and template names (@discriminated as a core std-lib decorator, FilterVisibility, @visibility(Lifecycle.Read), ARM TrackedResource/ProxyResource/ExtensionResource/ArmResource*/@armProviderNamespace/@armResourceOperations/ResourceProvisioningState, Azure.Core ResourceOperations/Page<T>/repeatability traits, @pollingOperation, @added/@removed/@versioned).
Security citations: W3C Trace Context traceparent regex, RFC 8594 (Sunset), draft-ietf-httpapi-ratelimit-headers (correctly NOT RFC 9239), cloud-metadata SSRF block (169.254.169.254), HMAC-SHA256 timestamp + "." + body with v1= prefix + replay window.
All 10 bundle cross-references and relative links resolve; quick start steps are correct.

Token efficiency

Live skill content ≈ 14,640 words (~19,000 tokens; tiktoken unavailable, wc -w × 1.3). Largest: SKILL.md (~4,080 w), generic-rest (~2,220 w), webhooks (~1,660 w). Net change is a small content addition (~170 words: the version-track clarification, monorepo-tag guard, RFC 9745 detail, provisioning-state reword). No compression applied - the ~1% redundancy is intentional per-bundle self-sufficiency, independently re-confirmed this pass. Capability signals preserved: Anti-Hallucination Rule, 22 hard rules, full SSRF checklist, emitter-gotchas table, LRO/versioning templates.

Validation

No automated validator ships with this bundle (no scripts/validate-skill.py, catalog.yaml, or bundle.yaml); validation was manual - external source verification (npm, microsoft/typespec + Azure/typespec-azure GitHub releases, rfc-editor.org, typespec.io, Azure docs), internal version-consistency grep, and cross-reference integrity. No TypeSpec compiler in the environment, so examples remain documentation snippets labelled by the skill's own "verify against installed version" guidance.
Bumped frontmatter version to 1.2.4 and last_verified to 2026-06-16.

Honest unknowns

npm and the GitHub release summaries disagreed on the Azure package numbers (an OFFICIAL SOURCE CONFLICT). npm (the authoritative installable source) was used; its four Azure package pages carried recent timestamps and mutually consistent monthly cadences. One npm page (the compiler) served a stale ~2-year-old cache (0.51.0), so the compiler's 1.13.0 figure rests on the GitHub releases page rather than its npm page. All concrete numbers carry an explicit "as of 2026-06-16, verify before pinning" label.

1.2.3 - 2026-06-08

Currency + accuracy pass. Externally validated every version claim and package attribution against npm, the microsoft/typespec and Azure/typespec-azure repos, and typespec.io docs (2026-06-08). No routing, hard-rule, or example-shape changes.

Fixed - accuracy

emitter-gotchas + SKILL.md (version track): @typespec/rest / @typespec/versioning latest stable is 0.81.0 (2026-04-07), not 0.82.0. The previous 0.82.0 was a -dev prerelease, not a published stable release. Corrected the version-track table, the inline example pin, and the split-track note in SKILL.md.
SKILL.md (package attribution): the SdkOperationGroup → SdkClient consolidation and @operationGroup → @client deprecation were mis-attributed to @azure-tools/typespec-azure-core 0.68.0. These are @azure-tools/typespec-client-generator-core (TCGC) changes shipped in the typespec-azure 0.67.0 family (Azure/typespec-azure#3997). Re-attributed in both the Anti-Hallucination grounding list and the asymmetry-traps list. @locationResource deprecation re-attributed to the ARM library (@azure-tools/typespec-azure-resource-manager, #4132); replacement @parentResource(ArmLocationResource<...>) confirmed correct.
generic-rest (@discriminated source): corrected the claim that @discriminated is "from @typespec/http". It is a core TypeSpec standard-library decorator (the TypeSpec namespace from @typespec/compiler), usable without importing @typespec/http.

Fixed - stale version pins (now consistent across all bundles)

azure-data-plane package.json: @typespec/versioning 0.73.0 → 0.81.0; @azure-tools/typespec-azure-core 0.67.1 → 0.68.0; @azure-tools/typespec-autorest 0.67.0 → 0.68.0.
ci-validation devDependencies: @typespec/compiler/http/openapi3 1.11.0 → 1.12.0; @typespec/rest 0.74.0 → 0.81.0. Node CI guidance 20/22 LTS → 22/24 LTS to match the Node 22 minimum stated in SKILL.md.
SKILL.md: hard-rule #15 pin example 1.11.0 → 1.12.0; modern-baseline section refreshed to the verified current versions (compiler/http/openapi3 1.12.0, rest/versioning 0.81.0, Azure tools 0.68.0) and now points to the releases page rather than a single possibly-stale combined tag.

Changed - hardening

webhooks: added an agent-readiness caveat that data: Record<unknown> on the delivery envelope conflicts with the skill's agent-readiness baseline; added a worked discriminated-union alternative keyed on type. Added signing-secret entropy guidance (>= 256-bit CSPRNG).

Verified correct (no change needed)

@typespec/compiler 1.12.0 (2026-05-12) is current stable. AutoRest deprecation effective July 1, 2026 (Azure/autorest#5175). @discriminated option shape, @pollingOperation, @added/@removed/@versioned, @autoRoute/@parentResource, TrackedResource/ProxyResource/ExtensionResource, ResourceProvisioningState, @visibility(Lifecycle.Read), and all SSRF / W3C Trace Context / RFC 8594 / RateLimit-draft citations re-verified accurate. All 10 bundle cross-references resolve.

Notes

No automated skill validator ships with this bundle (no scripts/validate-skill.py, catalog.yaml, or bundle.yaml); validation was manual: external source verification, internal version-consistency grep, and cross-reference integrity.
Bumped frontmatter version to 1.2.3 and last_verified to 2026-06-08.

1.2.2 - 2026-06-06

Issue-grounding pass against the microsoft/typespec tracker.

Added

bundles/emitter-gotchas/guide.md (new bundle): issue-grounded emit-time traps - @statusCode not extracted through alias/generic inheritance (#9034), union→OpenAPI shape depends on target OA version + @discriminator (#826), versioned union/enum examples emitting {} (#9088), Record<T> keys can't carry @pattern/@format (#2842); the split @typespec/* version-tracks trap and clean-reinstall-on-upgrade (#10034); and unsupported emitters (GraphQL #1390, AsyncAPI #2463, WebSocket #4124).
SKILL.md: bundle routing row for bundles/emitter-gotchas/.

Changed

SKILL.md: currency - latest stable compiler is 1.12.0 (2026-05-12), noted alongside the existing 1.11.0-verified deprecation facts; flagged the split @typespec/* version tracks (compiler/http/openapi3 1.12.0 vs rest/versioning 0.82.0). Bumped last_verified to 2026-06-06 and frontmatter version to 1.2.2 (frontmatter previously lagged the changelog at 1.2.0).

1.2.1 - 2026-05-29

Currency refresh pass.

Added

SKILL.md: TypeSpec 1.11.0 deprecation notes (FilterVisibility replaces @withVisibilityFilter, @withLifecycleUpdate and @applyMergePatch deprecated). @azure-tools/typespec-azure-core 0.68.0 breaking changes (SdkOperationGroup → SdkClient, @operationGroup deprecated, @locationResource deprecated). Bumped last_verified to 2026-05-29.

1.2.0 - 2026-05-15

Production-readiness round: webhooks/SSRF coverage, correlation/trace context, file-upload patterns, and tightened deprecation guidance. No breaking changes to v1.1.0 routing or hard rules.

Added - SKILL.md

Hard rule #20: correlation header (traceparent or x-ms-client-request-id) required on request and response for external/partner APIs; never in URL paths or query strings.
Hard rule #21: deprecated operations must carry both #deprecated directive AND the runtime header trio (Deprecation, Sunset, Link rel="successor-version").
Hard rule #22: webhook delivery and client-supplied URL ingestion must document the SSRF runtime policy on the URL field's @doc.
Bundle routing table now lists the new bundles/webhooks/ bundle.

Added - Bundles

NEW bundle - bundles/webhooks/: subscription resource with one-shot signing-secret disclosure pattern, outbound delivery envelope and headers, HMAC-SHA256 signing over timestamp + "." + body with v1= version prefix, 5-minute replay window, full SSRF runtime checklist (HTTPS-only, host/IP allow-list, DNS-rebinding defense, port allow-list, redirect cap, response-size cap, timeouts, egress isolation), retry/back-off schedule with idempotency requirement, subscription verification handshake (challenge/response vs first-delivery confirmation), operations interface with :rotateSecret action, common review rejections.
generic-rest: new "Correlation / trace context" section with TraceContextHeaders and ClientRequestIdHeader reusable models and runtime semantics. New "File upload patterns" section covering pre-signed URL (preferred) vs @multipartBody with criteria for choosing between them. Sunset/Deprecation section expanded: Link header now carries both rel="successor-version" and rel="deprecation", plus an operational checklist (ship deprecation + migration guide together, 6–12 month sunset window, traffic-tracking gate before retirement) and a cross-reference to @removed(Versions.vX) for property-level retirement.

Added - review-checklist

Item 41: correlation header modelled on request and response.
Item 42: deprecated operations carry both directive and header trio with documented sunset window.
Item 43: property-level retirements use @removed(Versions.vX).
Items 44–48: webhook security (SSRF @doc, typed delivery envelope, HMAC + replay window, one-shot secret disclosure, verification handshake) - conditionally applicable.
Items 49–50: file upload pattern chosen and documented, contentType / sizeBytes validated against allow-list and cap - conditionally applicable.

Notes

No package-version changes; modern baseline unchanged from 1.1.0.
No removals - every v1.1.0 item carries forward verbatim.

1.1.0 - 2026-05-15

Substantial quality overhaul: routing precision, security hardening, Azure API review readiness, externally-validated content corrections, and improved usability for new users.

Added - SKILL.md

Quick Start section with the four-command path from zero to a compiled spec.
Production-ready example alongside the existing minimal example: versioned namespace, paginated list with @maximum, error envelope, Repeatability-Request-ID, If-Match, @added operation.
Troubleshooting section covering Node version mismatches, stale tsp-output/, VS Code extension activation in monorepos, peer-dep warnings, Windows path quoting, corporate-proxy CA chains, and duplicate-type-name collisions.
Glossary section: TypeSpec, emitter, decorator, LRO, ARM, data plane, repeatability, visibility, scalar, @key, interface, namespace, model is vs extends, template, union, op, augment decorator (@@).
Naming conventions section: PascalCase models, camelCase properties, PascalCase enums, plural resource collections.
Agent-readiness baseline section: stable operation IDs, @doc on every operation, named response models, no untyped payloads.
Stop conditions subsection under Routing: when to hand off or refuse.
Hard rules #14–#19: HTTPS-only @server URLs, exact patch-version pinning + npm ci, every error has code field, no PII in URL paths or query parameters, @maximum on pagination, @visibility(Lifecycle.Read) on server-assigned fields.
Bundle routing table now lists what each bundle covers.
Front-matter description expanded with keywords: API-first design, contract-first, swagger.

Added - Bundles

generic-rest: per-operation @useAuth(NoAuth) override, rate-limit headers (draft-ietf-httpapi-ratelimit-headers plus Retry-After), error information-disclosure guards, idempotency-key pattern with replay-window note, ReDoS warning with worked examples, PII/data classification guidance, mass-assignment defense via Lifecycle.Read, SSRF guidance for URL inputs, Cache-Control: no-store for sensitive responses, Sunset/Deprecation headers (RFC 8594), @discriminated worked example for polymorphic unions, "no query params in @route" warning.
azure-data-plane: OAuth2 import clarification (NoAuth, BearerAuth, OAuth2Auth, OAuth2FlowType all from @typespec/http), conditional-request safety (ETag, 412), Azure security hard rules, Repeatability header pair (Repeatability-Request-ID + Repeatability-First-Sent), api-version mandatory query parameter, standard Azure ErrorResponse envelope shape, "avoid Legacy.* templates" note.
azure-arm: Concrete TrackedResource example with @armProviderNamespace, @armResourceOperations, and standard CRUD operations; provisioningState enum requirements; Operations API (Microsoft.<RP>/operations); Proxy and Extension resource patterns; Locations guidance; common ARM-review rejections; @parentResource Legacy-template caveat.
lro-pagination-versioning: Security-impacting breaking changes (scope removal, regex tightening, audience changes), polling-location safety, preview version suffix rule (YYYY-MM-DD-preview only), breaking-change classification table, @added/@removed interactions, Operations.GetResourceOperationStatus<T> arity correction.
migration-from-openapi: Pre-conversion checklist, known lossy fields, AutoRest July 2026 deadline call-out, fidelity verification with diff tools.
ci-validation: package.json scripts block, CI gates, caching strategy, Node version pin guidance.
m365-copilot-boundary: Agent-consumability checks, hand-off artifacts list, operation-ID stability warning.
review-checklist: 10 additional items grouped under Security, Agent-readiness, Versioning (items 21–30) and 10 Azure-specific items (31–40).

Changed

All bundles now carry "Inherits hard rules from SKILL.md §Hard rules" header.
Output path standardized to default tsp-output/@typespec/openapi3/openapi.yaml across SKILL.md and all bundles; the emitter-output-dir override removed from bundle tspconfig.yaml snippets.
Package versions in bundle package.json snippets pinned to exact patch versions (no caret ranges).
tsp init quick-start command no longer hardcodes a template name; defers to interactive prompt with a note that template names vary by compiler version.
Hard rule #13 (AutoRest retirement) clarified to distinguish the retiring autorest CLI from the supported @azure-tools/typespec-autorest emitter.
Modern baseline labels (typespec-stable@1.11.0, typespec-azure@0.67.0) reframed as GitHub release-family tags, not installable packages.
Node version requirement updated: TypeSpec 1.x minimum is now Node 22; Azure TypeSpec recommends Node 24 LTS.

Fixed

Page<T> example in SKILL.md no longer references the eTag scalar without importing @azure-tools/typespec-azure-core; uses @header("ETag") on the response instead. Added a note that the generic Page<T> shape (items/url) differs from Azure's Azure.Core.Page<T> (@pageItems value/@nextLink ResourceLocation<T>) and should not be substituted in Azure data-plane work.
Operations.GetResourceOperationStatus<Widget, never> corrected to Operations.GetResourceOperationStatus<Widget> (passing never as StatusResult produces an uninhabitable payload).
RateLimit header citation corrected from "RFC 9239" (which is JavaScript media-type registration) to draft-ietf-httpapi-ratelimit-headers.

1.0.0 - Initial release

Initial skill covering: routing, hard rules (#1–#13), default output contract, modern baseline, project shape, minimal generic example, references, and eight topic bundles (generic-rest, azure-data-plane, azure-arm, lro-pagination-versioning, migration-from-openapi, ci-validation, m365-copilot-boundary, review-checklist).

/typespec-api-design