Access version

When the user asks what fields an OpenAPI 3.x document requires, how to validate a spec, or what changed between OpenAPI specification versions — reach for the JSON Schema endpoints at spec.openapis.org.

access-version · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/access-version. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/access-version/SKILL.md.

When to use this skill

When the user asks what fields an OpenAPI 3.x document requires, how to validate an OpenAPI spec, or what changed between specification versions — reach for the JSON Schema endpoints at spec.openapis.org. For checking which extension prefixes are reserved, use the namespace registry instead. For reading spec prose in a browser, this is the wrong skill.

Your best first call

curl "https://spec.openapis.org/oas/3.1/schema/2021-05-20"

No auth. No key. Returns the JSON Schema (Draft 2020-12) that defines what a conforming OpenAPI 3.1 document looks like. Swap 3.1 for 3.0 to get the 3.0 schema; swap 2021-05-20 for the date of a different schema revision.

Key structural fields:

required — always ["openapi", "info"]
anyOf — requires at least one of paths, components, or webhooks; a document with only components and no routes is valid — the "type-library" pattern where an OpenAPI file is purely a schema container
jsonSchemaDialect — defaults to https://spec.openapis.org/oas/3.1/dialect/base, meaning 3.1 documents can use const, oneOf, and unevaluatedProperties inside schema objects without declaring them. In 3.0, those keywords were forbidden.

Fallbacks (when the best first call isn't enough)

Extension namespace lookup → https://spec.openapis.org/api/namespace.json returns the registry of reserved x- prefixes (oai, oas, oas-draft, ms, sap, fdx, scalar). Use when the question is about who owns an extension prefix, not about document structure.

Pitfalls

The /registries/ path returns 404. The documented path is broken. Use /api/{registry}.json instead — e.g., /api/namespace.json, /api/extension.json.
HTML paths use v-prefixed versions; JSON Schema paths do not. The spec HTML lives at /oas/v3.1.0.html but the JSON Schema lives at /oas/3.1/schema/2021-05-20 — no v prefix, no patch version, a date suffix instead. Mixing them up is the most common error.
The schema date is not the spec release date. 2021-05-20 is when that JSON Schema file was published, not when OpenAPI 3.1.0 was released (February 2021). Each schema revision gets its own date-stamped URL.

One-line summary for the user

I can fetch the JSON Schema that defines what an OpenAPI 3.x document must contain from spec.openapis.org — no auth needed, but most of the site serves HTML prose rather than JSON.

APIs this skill uses

OpenAPI Specification · primary · verified

Access to OpenAPI Initiative specifications including OpenAPI, Arazzo, and Overlay specifications. Provides JSON schemas and HTML documentation for various specification versions.

Generated from

OpenAPI Specification tutorial Getting Started with OpenAPI Specification Repository

SKILL.md source (frontmatter + body)

---
name: access-version
description: When the user asks what fields an OpenAPI 3.x document requires, how to validate a spec, or what changed between OpenAPI specification versions — reach for the JSON Schema endpoints at spec.openapis.org.
---

## When to use this skill

When the user asks what fields an OpenAPI 3.x document requires, how to validate an OpenAPI spec, or what changed between specification versions — reach for the JSON Schema endpoints at `spec.openapis.org`. For checking which extension prefixes are reserved, use the namespace registry instead. For reading spec prose in a browser, this is the wrong skill.

## Your best first call

```bash
curl "https://spec.openapis.org/oas/3.1/schema/2021-05-20"
```

No auth. No key. Returns the JSON Schema (Draft 2020-12) that defines what a conforming OpenAPI 3.1 document looks like. Swap `3.1` for `3.0` to get the 3.0 schema; swap `2021-05-20` for the date of a different schema revision.

Key structural fields:

- `required` — always `["openapi", "info"]`
- `anyOf` — requires at least one of `paths`, `components`, or `webhooks`; a document with only `components` and no routes is valid — the "type-library" pattern where an OpenAPI file is purely a schema container
- `jsonSchemaDialect` — defaults to `https://spec.openapis.org/oas/3.1/dialect/base`, meaning 3.1 documents can use `const`, `oneOf`, and `unevaluatedProperties` inside schema objects without declaring them. In 3.0, those keywords were forbidden.

## Fallbacks (when the best first call isn't enough)

- **Extension namespace lookup** → `https://spec.openapis.org/api/namespace.json` returns the registry of reserved `x-` prefixes (`oai`, `oas`, `oas-draft`, `ms`, `sap`, `fdx`, `scalar`). Use when the question is about who owns an extension prefix, not about document structure.

## Pitfalls

- **The `/registries/` path returns 404.** The documented path is broken. Use `/api/{registry}.json` instead — e.g., `/api/namespace.json`, `/api/extension.json`.
- **HTML paths use `v`-prefixed versions; JSON Schema paths do not.** The spec HTML lives at `/oas/v3.1.0.html` but the JSON Schema lives at `/oas/3.1/schema/2021-05-20` — no `v` prefix, no patch version, a date suffix instead. Mixing them up is the most common error.
- **The schema date is not the spec release date.** `2021-05-20` is when that JSON Schema file was published, not when OpenAPI 3.1.0 was released (February 2021). Each schema revision gets its own date-stamped URL.

## One-line summary for the user

I can fetch the JSON Schema that defines what an OpenAPI 3.x document must contain from spec.openapis.org — no auth needed, but most of the site serves HTML prose rather than JSON.

« Back to all skills