OpenAPI Specification

The OpenAPI Specification (OAS), published by the OpenAPI Initiative (OAI), defines a language-agnostic description of HTTP APIs (§ 2). With this skill the agent writes, reviews, upgrades and validates OpenAPI Descriptions (OADs) for 3.2, keeps them readable by 3.1 tooling when needed, and names extensions without colliding with anyone else.

Follow the workflow below step by step. Every rule here comes from a source in Sources, with the section it cites. Section numbers are those of OAS 3.2.1 unless a rule says otherwise. When a rule and the pinned source disagree, the source wins; when the source has a newer revision than the pin, follow the refresh steps.

Inputs (fill in, or ask before starting)

• Role: author (writes or generates the OAD), consumer (reads it: client generator, gateway, docs, agent), or reviewer.
• Target version: 3.2 (default) or 3.1, when a consumer cannot read 3.2 yet. Never 3.3: it is not released.
• Revision: the pinned revision in Sources, unless the user names another.
• Sources: when refreshing this skill or when a rule looks out of date, re-read every URL in Sources first, check spec.openapis.org/oas for a newer version or schema iteration, check the v3.3-dev branch and the Security Profiles discussion for movement, and update the pins.

Invariants

1. openapi names the specification version. It is REQUIRED and tooling interprets the document by it (§ 4.1.1). Tooling SHOULD NOT distinguish patch versions, so 3.2.0 and 3.2.1 mean the same feature set (§ 2.1).
2. A document has info and at least one of paths, webhooks or components (§ 4.1.1).
3. operationId is unique among all operations in the API and case-sensitive (§ 4.10.1).
4. Every path template expression has a matching path parameter, defined on the Path Item or on each of its operations (§ 4.8.2), and templated paths that differ only in parameter names MUST NOT both exist (§ 4.8.1).
5. A parameter has either schema or content, never both (§ 4.12.2), is unique by name plus in (§ 4.10.1), and an in: querystring parameter never sits next to in: query parameters (§ 4.12.1).
6. Component keys match ^[a-zA-Z0-9\.\-_]+$ (§ 4.7.1).
7. Security requirements mean OR across the array and AND within one object. Each name is a declared scheme or a scheme URI; {} allows anonymous access; an operation's security: [] removes the top-level requirement (§ 4.30, § 4.10.1).
8. Extensions start with x-, and x-oai- and x-oas- are reserved for the OAI (§ 5).
9. A Reference Object carries only $ref, summary and description; other properties are ignored (§ 4.23.1).
10. When a document sets $self, references to it use that URI (§ 4.1.1).

Workflow

1. Pick the target version and schema. Default to 3.2 at the latest patch; drop to 3.1 only for a named consumer that cannot read 3.2. -> references/versions.md ✓ openapi is set, and you know which official schema validates the document.
2. Lay out the document. Write info, servers, paths with one Operation Object per method, components for reuse, and tags. Give every operation an operationId, because Arazzo steps and Overlay targets join on it. -> references/objects.md ✓ Invariants 2 to 6 and 9 hold.
3. Describe security. Declare schemes under components.securitySchemes, set the root security default, and override per operation. Use the 3.2 fields for device authorization, server metadata and deprecation; on a 3.1 target use the registered x-oai-* fallbacks. -> references/security.md ✓ Every requirement name resolves, every OAuth scope used is declared on its flow, and public operations say so explicitly.
4. Name extensions. Reuse a registered extension when one fits its documented purpose; otherwise use your own registered or registrable namespace prefix. -> references/registries.md ✓ No invented x-oai- or x-oas- names, and no writes into another party's namespace.
5. Upgrade an existing description (only when asked). Change the version, then replace extensions with native 3.2 fields one at a time. -> references/versions.md ✓ The upgraded document validates against the 3.2 schema and still describes the same API.
6. Validate. Run the document through the official JSON Schema for its minor version, and fix what it reports. Then check the rules a schema cannot see (invariants 3, 4 and 7). -> references/validation.md ✓ Schema validation passes with the latest iteration for the minor version.
7. Track 3.3, do not emit it. Read what the v3.3-dev branch and the Security Profiles proposal contain today; record anything you plan around. -> references/drafts.md ✓ No openapi: 3.3.x document, type: profile scheme or Path Item security field is produced.

Verify before done

• The document validates against the official schema for its minor version, latest iteration (references/validation.md); use schema-base when Schema Objects must be checked too.
• Every operationId is unique (§ 4.10.1) and every path template has its parameter (§ 4.8.2).
• Every Security Requirement name resolves to a declared scheme or a scheme URI (§ 4.30), and the OAuth scopes listed are among the available scopes of that scheme's flows (§ 4.29.1, § 4.30.1).
• Operations that need no authentication say so with security: [] or an {} entry, rather than by omission (§ 4.10.1).
• Every extension is registered for the object it sits on, or lives under your own namespace (§ 5, Extension Registry).
• A 3.1 target uses no 3.2-only field; the x-oai-* fallback is used where the registry defines one (references/security.md).
• Nothing from the 3.3 development line is emitted.

Reference index

• references/versions.md: 3.2.0 and 3.2.1 changes, 3.1 compatibility, the 3.1 to 3.2 upgrade path, and the registered fallbacks for 3.2 fields. Load for steps 1 and 5.
• references/objects.md: document structure, paths, operations, parameters, tags, references and schema dialects, with a minimal 3.2 example. Load for step 2.
• references/security.md: Security Scheme, OAuth Flows, OAuth Flow and Security Requirement Objects, 3.1 fallbacks, and the security considerations. Load for step 3.
• references/registries.md: the OAI Extension and Namespace registries, the reserved prefixes, and how to register. Load for step 4.
• references/validation.md: the official JSON Schemas, schema versus schema-base, iteration rules, and what a schema cannot check. Load for step 6.
• references/drafts.md: the 3.3 development line and the Security Profiles proposal, with draft posture. Load for step 7.

Related skills

• openapi-overlay to change an OAD repeatably without editing it: npx skills add ScaleDockHQ/scaledock-skills --skill openapi-overlay.
• openapi-arazzo to describe multi-step workflows over OpenAPI operations: npx skills add ScaleDockHQ/scaledock-skills --skill openapi-arazzo.
• typespec to design an API in TypeSpec and emit the OAD from it: npx skills add ScaleDockHQ/scaledock-skills --skill typespec.
• asyncapi for event-driven and message-based APIs: npx skills add ScaleDockHQ/scaledock-skills --skill asyncapi.

Sources

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

• OpenAPI Specification v3.2.1: Released, 3.2.1 (2026-09-10), checked 2026-10-02.
• OAS 3.2.0 release notes: Released, 3.2.0 (2025-09-19), checked 2026-10-02.
• OpenAPI Specification v3.1.2: Released, 3.1.2 (2025-09-19), checked 2026-10-02.
• Upgrading from OpenAPI 3.1 to 3.2: OAI guide (non-normative), page as published, checked 2026-10-02.
• OpenAPI Specification versions and schema iterations: OAI index, latest v3.2.1, checked 2026-10-02.
• OAS 3.2 JSON Schema: Published schema, iteration 2026-08-30, checked 2026-10-02.
• OAS 3.2 JSON Schema with Schema Object validation: Published schema, iteration 2026-08-30, checked 2026-10-02.
• OAS 3.1 JSON Schema: Published schema, iteration 2026-08-03, checked 2026-10-02.
• OAS 3.1 JSON Schema with Schema Object validation: Published schema, iteration 2026-08-03, checked 2026-10-02.
• OAS v3.3-dev branch text: In development, commit aa2f6c0 (2026-09-24), checked 2026-10-02. Draft posture: track.
• Proposal: Supporting Loose-Coupling in Security Schemes and Security Requirements Objects (Security Profiles): Proposal under discussion (moved from OpenAPI-Specification discussion #5304), expanded design notes 2026-05-05, checked 2026-10-02. Draft posture: track.
• OpenAPI Initiative newsletter, June 2026: OAI announcement, 2026-06-09, checked 2026-10-02.
• OAI registries: Living registries, as published, checked 2026-10-02.
• Extension Registry: Living registry, as published, checked 2026-10-02.
• Namespace Registry: Living registry, as published, checked 2026-10-02.
• Registry contribution guide: OAI repository guide, main branch, checked 2026-10-02.