Getting Started with OpenAPI Specification Repository

← OpenAPI Specification

When to use this API

When you need to programmatically fetch an OpenAPI JSON Schema for validation, or look up which extensions and namespaces are officially registered with the OpenAPI Initiative. This is the canonical source for the machine-readable schemas that define what an OpenAPI 3.x document must contain, and for the registries tracking vendor extensions, format identifiers, and namespace prefixes. Most endpoints serve HTML specification prose for human browsing; the two machine-readable surfaces are the JSON Schema endpoint and the registries API. For reading spec text in a browser, hit the HTML endpoints directly; for programmatic introspection or validation wiring, use the JSON endpoints.

Fetching the OpenAPI 3.1 validation schema

"What fields does an OpenAPI 3.1 document require?" The /oas/{version}/schema/{date} endpoint returns the JSON Schema (Draft 2020-12) that defines the OpenAPI document structure. This is the schema validators run under the hood — fetch it once and you have the exact structural constraints for any 3.1.x document.

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

{
  "$id": "https://spec.openapis.org/oas/3.1/schema/2021-05-20",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "openapi": {"type": "string", "pattern": "^3\\.1\\.\\d+(-.+)?$"},
    "info": {"$ref": "#/$defs/info"},
    "jsonSchemaDialect": {"type": "string", "format": "uri", "default": "https://spec.openapis.org/oas/3.1/dialect/base"},
    "servers": {"type": "array", "items": {"$ref": "#/$defs/server"}},
    "paths": {"$ref": "#/$defs/paths"},
    "webhooks": {"type": "object", "additionalProperties": {"$ref": "#/$defs/path-item-or-reference"}},
    "components": {"$ref": "#/$defs/components"},
    "security": {"type": "array", "items": {"$ref": "#/$defs/security-requirement"}},
    "tags": {"type": "array", "items": {"$ref": "#/$defs/tag"}},
    "externalDocs": {"$ref": "#/$defs/external-documentation"}
  },
  "required": ["openapi", "info"],
  "anyOf": [
    {"required": ["paths"]},
    {"required": ["components"]},
    {"required": ["webhooks"]}
  ]
}

The anyOf constraint is the non-obvious detail: an OpenAPI 3.1 document must have paths OR components OR webhooks — not all three. A document with only components (defining reusable schemas with no routes) is valid, which supports the "type-library" pattern where an OpenAPI document is purely a schema container. The jsonSchemaDialect property defaults to an OpenAPI-specific dialect URI, meaning 3.1 documents can use full JSON Schema keywords like const, oneOf, and unevaluatedProperties inside schema objects without declaring them — a change from 3.0 where those keywords were forbidden.

An OpenAPI 3.1 document requires openapi and info at minimum, plus at least one of paths, components, or webhooks. A schema-only document with just components and no routes is valid.

Discovering registered extension namespaces

"Who can create OpenAPI extensions and what prefixes are reserved?" The registries API lists seven registry categories, then each registry drills into its entries. The namespace registry is the one that answers governance questions — it lists the prefix namespaces that extension authors must not collide with.

curl "https://spec.openapis.org/api/registries.json" | head -c 10000

["extension", "namespace", "format", "tag-kind", "media-type", "draft-feature", "alternative-schema"]

curl "https://spec.openapis.org/api/namespace.json" | head -c 10000

{
  "fdx": {
    "slug": "fdx",
    "description": "Extensions created and used by Financial Data Exchange (FDX)",
    "url": "/registry/namespace/fdx",
    "owner": "DavidBiesack"
  },
  "ms": {
    "slug": "ms",
    "description": "Extensions created and used by Microsoft",
    "url": "/registry/namespace/ms",
    "owner": "DarrelMiller"
  },
  "oai": {
    "slug": "oai",
    "description": "Reserved for uses defined by the OAI",
    "url": "/registry/namespace/oai",
    "owner": "DarrelMiller"
  },
  "oas-draft": {
    "slug": "oas-draft",
    "description": "Extensions created by OAI to indicate proposed changes to the OAS specification",
    "url": "/registry/namespace/oas-draft",
    "owner": "DarrelMiller"
  },
  "oas": {
    "slug": "oas",
    "description": "Reserved for uses defined by the OAI",
    "url": "/registry/namespace/oas",
    "owner": "DarrelMiller"
  },
  "sap": {
    "slug": "sap",
    "description": "Extensions created and used by SAP",
    "url": "/registry/namespace/sap",
    "owner": "ralfhandl, pavelkornev"
  },
  "scalar": {
    "slug": "scalar",
    "description": "Extensions created and used by Scalar",
    "url": "/registry/namespace/scalar",
    "owner": "marclave, hanspagel, amritk"
  }
}

The OAI reserves three namespaces for its own use: oai, oas, and oas-draft. The oas-draft namespace is the most interesting — it is the staging area for extensions that are being proposed as additions to the OpenAPI specification itself, meaning x-oas-draft-* properties on a document are effectively pre-standard features. The fdx namespace, owned by the Financial Data Exchange, signals that OpenAPI's extension ecosystem reaches into regulated industries where financial-data interoperability standards matter. Before minting a new x- extension prefix, check this registry to avoid colliding with an existing namespace.

The OpenAPI Initiative reserves three namespace prefixes — oai, oas, and oas-draft — for its own use. Vendor namespaces include ms (Microsoft), sap (SAP), fdx (Financial Data Exchange), and scalar (Scalar). The oas-draft namespace is for extensions being proposed as spec additions. Check this registry before minting a new extension prefix.

Pitfalls

One-line summary for the user

I can fetch the OpenAPI 3.1 JSON Schema for document validation and list registered extension namespaces from spec.openapis.org — but most endpoints serve HTML spec prose rather than structured data, so this API is for schema introspection and registry lookups, not for querying runtime data.