TypeSpec

TypeSpec is a language and toolset, developed by Microsoft, for defining data models and service APIs and generating artifacts such as OpenAPI from them. With this skill the agent writes TypeSpec for HTTP APIs, configures the OpenAPI 3 emitter, versions the API, and checks the emitted OpenAPI.

Follow the workflow below step by step. Every rule here comes from a source in Sources. TypeSpec documentation has no numbered sections, so rules cite the documentation page and heading (for example "HTTP Operations, Implicit body resolution"). When a rule and the pinned source disagree, the source wins; when the packages have moved past the pin, follow the refresh steps.

Inputs (fill in, or ask before starting)

• Role: API designer (writes TypeSpec), emitter user (configures output), or reviewer.
• Target OpenAPI version or versions: 3.0.0, 3.1.0 or 3.2.0. The emitter's default is 3.0.0 only.
• Whether the API is versioned, and the list of versions.
• Revision: compiler, http, openapi and openapi3 at 1.16.0, and versioning at 0.86.0, unless the project pins others. Use the project's package.json versions when they differ.
• Sources: when refreshing this skill or when a rule looks out of date, re-read every URL in Sources, check npm for newer @typespec/* releases, read the changelogs since the pin, and update the pins.

Invariants

1. Declaration names are unique within a scope, even across kinds: a model and a namespace cannot share a name (Language basics, Declarations).
2. The service is a namespace marked @service, with @server for each endpoint; libraries are brought in with import and using (Getting started, Defining a REST Service).
3. Without @body, everything not marked @header, @query or @path is the request body, and every response property not marked @header or @statusCode is the response body (HTTP Operations, Implicit body resolution).
4. @body defines the body exactly; @bodyRoot allows metadata properties inside it (HTTP Operations, @body vs @bodyRoot).
5. A response marked @error is the error response: 4xx,5xx by default, emitted as the OpenAPI default response (HTTP Operations, Status codes; OpenAPI v3 emitter, Error Responses).
6. @useAuth on a child replaces the parent's schemes; a tuple means all of them, a union means one of them (HTTP Authentication, Application hierarchy).
7. Set openapi-versions explicitly. It accepts 3.0.0, 3.1.0 and 3.2.0 and defaults to ["3.0.0"] (openapi3 emitter options).
8. Versioned TypeSpec describes the current state of the API; versioning decorators record the version where each change happened and the previous value (Versioning guide).
9. Unions emit anyOf unless the named union has @oneOf, and extends emits allOf while spread and is copy properties (OpenAPI v3 emitter, Model Composition).
10. tsp init with an external template URL can run untrusted packages; use only templates you trust (CLI usage).

Workflow

1. Set up the project. Node.js 22 or later, @typespec/compiler, a main.tsp, and a tspconfig.yaml that emits @typespec/openapi3. -> references/project.md ✓ tsp compile . succeeds and writes to tsp-output/.
2. Model the data. Use models, scalars, enums, unions, templates and doc comments. -> references/language.md ✓ Invariant 1 holds, and every public type has a doc comment.
3. Describe the HTTP surface. Routes, verbs, parameters, bodies, status codes, errors and authentication. -> references/http.md ✓ Invariants 3 to 6 hold, and every operation returns its error type in a union.
4. Configure the OpenAPI emitter. Choose openapi-versions, the output file, operation-id-strategy and other options, and add @typespec/openapi decorators where needed. -> references/openapi3-emitter.md ✓ Invariant 7 holds, and features that exist only in 3.2 are not expected in 3.0 output.
5. Version the API (only when it is versioned). Add @versioned, the versions enum, and change decorators. -> references/versioning.md ✓ Invariant 8 holds, and one OpenAPI file is emitted per version.
6. Check the output. Compile with warnings as errors, then validate each emitted file against the official OpenAPI JSON Schema for its version. -> references/openapi3-emitter.md ✓ No warnings, and every emitted file validates.

Verify before done

• tsp compile . --warn-as-error exits with code zero (Configuration, warn-as-error).
• tsp format leaves the .tsp files unchanged (CLI usage).
• Each emitted OpenAPI file validates against the official OAS JSON Schema for its openapi version; the openapi skill lists the schemas.
• Every versioned output (openapi.v1.yaml, openapi.v2.yaml, ...) reflects the right shape for that version (Versioning guide).
• Operation IDs are stable and unique; set @operationId where the default would change on refactoring (OpenAPI v3 emitter, Operation ID).
• Authentication appears as securitySchemes and security requirements in the output (OpenAPI v3 emitter, Security Definitions).

Reference index

• references/project.md: installation, tspconfig.yaml, the tsp CLI and linting. Load for steps 1 and 6.
• references/language.md: language basics with examples. Load for step 2.
• references/http.md: @typespec/http decorators, body and status code rules, files, visibility and authentication. Load for step 3.
• references/openapi3-emitter.md: emitter options, OpenAPI version support, the TypeSpec to OpenAPI mapping, @typespec/openapi decorators and tsp-openapi3. Load for steps 4 and 6.
• references/versioning.md: @typespec/versioning decorators and patterns. Load for step 5.

Related skills

• openapi for the OpenAPI documents TypeSpec emits, their versions and validation: npx skills add ScaleDockHQ/scaledock-skills --skill openapi.
• openapi-overlay for changes to emitted OpenAPI that should stay outside the TypeSpec source: npx skills add ScaleDockHQ/scaledock-skills --skill openapi-overlay.

Sources

Status uses the publishing body's own maturity term. Checked is the date the source was last read.

• TypeSpec documentation: Living documentation for the latest release, as published, checked 2026-10-02.
• Language basics overview: Living documentation, as published, checked 2026-10-02.
• Getting started with TypeSpec for REST APIs: Living documentation, as published, checked 2026-10-02.
• CLI usage: Living documentation, as published, checked 2026-10-02.
• Configuration: Living documentation, as published, checked 2026-10-02.
• HTTP Operations: Living documentation, as published, checked 2026-10-02.
• HTTP Authentication: Living documentation, as published, checked 2026-10-02.
• HTTP decorators reference: Living documentation, as published, checked 2026-10-02.
• @typespec/http 1.16.0 auth.tsp: Released, 1.16.0 (2026-09-09), checked 2026-10-02.
• OpenAPI v3 emitter guide: Living documentation, as published, checked 2026-10-02.
• @typespec/openapi3 emitter options: Living documentation, as published, checked 2026-10-02.
• @typespec/openapi3 1.16.0 README: Released, 1.16.0 (2026-09-09), checked 2026-10-02.
• @typespec/openapi3 1.16.0 package.json: Released, 1.16.0 (2026-09-09), checked 2026-10-02.
• @typespec/openapi3 1.16.0 emitter options schema: Released, 1.16.0 (2026-09-09), checked 2026-10-02.
• @typespec/openapi3 1.16.0 emitter source: Released, 1.16.0 (2026-09-09), checked 2026-10-02.
• @typespec/openapi3 changelog: Changelog, commit 843c089 (2026-10-02), entries through 1.16.0, checked 2026-10-02.
• @typespec/compiler changelog: Changelog, commit 843c089 (2026-10-02), entries through 1.16.0, checked 2026-10-02.
• OpenAPI3 to TypeSpec: Living documentation, as published, checked 2026-10-02.
• @typespec/openapi decorators: Living documentation, as published, checked 2026-10-02.
• Versioning guide: Living documentation, as published, checked 2026-10-02.
• Versioning decorators reference: Living documentation, as published, checked 2026-10-02.
• @typespec/versioning 0.86.0 package: Released, 0.86.0 (2026-09-09), pre-1.0, draft posture: build, checked 2026-10-02.