@openapi-spec/types provides TypeScript types for the OpenAPI Specification, covering versions 3.0, 3.1, and 3.2. Every object and field is modelled after the specification, and every field carries the specification's own description as JSDoc with a link to its section, so the spec is readable from your editor. The package ships types only, no runtime code.

Each version module targets the latest patch release of its minor line:

| Module | Specification | Notes | | -------------------------- | ---------------------------------------------------------- | ------------------------------------------------ | | @openapi-spec/types/v3.0 | OpenAPI 3.0.4 | | | @openapi-spec/types/v3.1 | OpenAPI 3.1.2 | Reuses 3.0 types for objects that did not change | | @openapi-spec/types/v3.2 | OpenAPI 3.2.0 | Reuses 3.1 types for objects that did not change |

Usage

// Every version as a namespace
import type { OpenAPIV3_0, OpenAPIV3_1, OpenAPIV3_2 } from '@openapi-spec/types'

// Or one version directly
import type { OpenAPIObject, SchemaObject } from '@openapi-spec/types/v3.1'

const doc: OpenAPIObject = {
  openapi: '3.1.2',
  info: { title: 'Pet Store', version: '1.0.0' },
  paths: {},
}

// SchemaObject takes an optional data type for its data-carrying fields:
// `enum`, `default`, `example`, and from 3.1 on `const` and `examples`
const status = {
  type: 'string',
  enum: ['available', 'pending', 'sold'],
  default: 'available',
} satisfies SchemaObject<string>

Conventions

• Type names follow the specification's section names: InfoObject, PathItemObject, SchemaObject, and so on.
• Fields the specification marks as deprecated carry an @deprecated tag.
• Rules the type system can express are enforced: allowed fields, value shapes, and version-specific literals such as style values. Rules it cannot express, like mutually exclusive fields or "at least one of", are stated in the JSDoc instead.

The types are checked against the official example documents and the specification's own schema test corpus. See tests/README.md.

Sponsors

Like what we build over at middleapi? You can help keep it going through GitHub Sponsors or Open Collective. Every bit helps! 🚀

Organization Sponsors

Sponsors

Backers

With thanks to 36 past sponsors who helped get openapi-spec here.

License

Distributed under the MIT License. See LICENSE for more information.