# @scalar/openapi-types

> Modern OpenAPI types

Latest version **0.9.6** (published 2026-09-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install @scalar/openapi-types
pnpm add @scalar/openapi-types
yarn add @scalar/openapi-types
bun add @scalar/openapi-types
```

## Health

**Score 70/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; popular repo.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.9.6 |
| Published | 2026-09-16 |
| First published | 2024-08-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=22 |
| Dependencies | 0 |
| Unpacked size | 419.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 16153 |
| Author | Scalar |
| Maintainers | cameronrohani, marclave, scalar_geoff, hwkr, hanspagel, amritk, scalar-machine |
| Keywords | openapi, scalar, swagger, typescript |

## Links

- npm: https://www.npmjs.com/package/@scalar/openapi-types
- Repository: https://github.com/scalar/scalar
- Issues: https://github.com/scalar/scalar/issues/new/choose
- npm.io page: https://npm.io/package/@scalar/openapi-types

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.9.6 (latest) — 2026-09-16
- 0.9.5 — 2026-08-20
- 0.9.4 — 2026-07-31
- 0.9.3 — 2026-07-16
- 0.9.2 — 2026-07-15
- 0.9.1 — 2026-06-02
- 0.9.0 — 2026-05-21
- 0.8.0 — 2026-04-21
- 0.7.0 — 2026-04-03
- 0.6.1 — 2026-03-18
- 0.6.0 — 2026-03-04
- 0.5.4 — 2026-03-03
- 0.5.3 — 2025-12-10
- 0.5.2 — 2025-12-04
- 0.5.1 — 2025-11-03
- … 25 more at https://npm.io/package/@scalar/openapi-types/versions

## README

# Scalar OpenAPI Types

[![Version](https://img.shields.io/npm/v/@scalar/openapi-types)](https://www.npmjs.com/package/@scalar/openapi-types)
[![Downloads](https://img.shields.io/npm/dm/@scalar/openapi-types)](https://www.npmjs.com/package/@scalar/openapi-types)
[![License](https://img.shields.io/npm/l/@scalar/openapi-types)](https://www.npmjs.com/package/@scalar/openapi-types)
[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)

Strict, well-documented OpenAPI TypeScript types based on official JSON Schemas, with specification links in comments.

---

Scalar is an open-source API platform for teams who want beautiful developer interfaces without vendor lock-in.

- **[API References](https://scalar.com/products/api-references/getting-started)** — Interactive API documentation from OpenAPI and AsyncAPI specs.
- **[Developer Docs](https://scalar.com/products/docs/getting-started)** — Write in Markdown/MDX, generate API references, sync with two-way Git.
- **[SDK Generator](https://scalar.com/products/sdk-generator/getting-started)** — Type-safe SDKs and CLIs in TypeScript, Python, Go, PHP, Java, and Ruby.
- **[API Client](https://scalar.com/products/api-client/getting-started)** — Open-source, offline-first Postman alternative built on OpenAPI.

20M+ monthly npm installs · 15,500+ GitHub stars · MIT licensed · [scalar.com](https://scalar.com)

---

## Installation

```bash
npm add @scalar/openapi-types
```

## Versions

* OpenAPI 3.2
* OpenAPI 3.1
* OpenAPI 3.0
* Swagger 2.0

## Usage

```ts
import type { Document } from '@scalar/openapi-types/3.2'

const file: Document = {
  openapi: '3.2.0',
  info: {
    title: 'Hello World',
    version: '1.0.0',
  },
  paths: {},
}
```

### Individual Exports

If your bundler doesn't work with barrel files, you can explicitly import objects, too:

```ts
import type { Document } from '@scalar/openapi-types/3.2/document'

const file: Document = {
  openapi: '3.2.0',
  info: {
    title: 'Hello World',
    version: '1.0.0',
  },
  paths: {},
}
```

## Helpers

`@scalar/openapi-types/helpers` ships a small set of runtime helpers for working
with the type definitions above. They are written to work with `SchemaObject`
across all supported OpenAPI versions (2.0, 3.0, 3.1, and 3.2).

### `isDereferenced(value)`

Type guard that returns `true` when `value` is not a `ReferenceObject` (i.e. it
does not have a string `$ref` property). Useful when walking a document that may
mix references and inline objects. Like the schema discriminators, it narrows
the reference members out of a `SchemaObject | ReferenceObject` union from any
supported OpenAPI version.

```ts
import { isDereferenced } from '@scalar/openapi-types/helpers'

const schema = components.schemas?.Pet

if (isDereferenced(schema)) {
  // `schema` is narrowed to the inline SchemaObject and `$ref` is ruled out
  schema.type
}
```

### Schema discriminators

Schema discriminators narrow a `SchemaObject` union to the variant whose `type`
matches the guard, so type-specific properties (such as `properties`, `items`,
or `minLength`) become accessible without a manual cast.

| Helper                | Matches when…                                          |
| --------------------- | ------------------------------------------------------ |
| `isObjectSchema`      | `type === 'object'`                                    |
| `isArraySchema`       | `type === 'array'`                                     |
| `isStringSchema`      | `type === 'string'`                                    |
| `isNumberSchema`      | `type === 'number'`                                    |
| `isIntegerSchema`     | `type === 'integer'`                                   |
| `isNumericSchema`     | `type === 'number'` or `type === 'integer'`            |
| `isBooleanSchema`     | `type === 'boolean'`                                   |
| `isNullSchema`        | `type === 'null'` (OpenAPI 3.1+)                       |
| `isMultiTypeSchema`   | `type` is an array of primitive types (OpenAPI 3.1+)   |
| `isUntypedSchema`     | `type` is not set                                      |
| `isBooleanJsonSchema` | the schema itself is the literal `true` or `false`     |

```ts
import { isArraySchema, isObjectSchema } from '@scalar/openapi-types/helpers'
import type { SchemaObject } from '@scalar/openapi-types/3.1'

function describe(schema: SchemaObject) {
  if (isObjectSchema(schema)) {
    return Object.keys(schema.properties ?? {})
  }

  if (isArraySchema(schema)) {
    return schema.items
  }

  return null
}
```

> `isBooleanSchema` matches an OpenAPI schema with `type: 'boolean'`.
> `isBooleanJsonSchema` matches the JSON Schema shorthand where the schema
> itself is `true` (allow any value) or `false` (allow no value). Use the one
> that fits your check.

## Community

We are API nerds. You too? Let's chat on Discord: <https://discord.gg/scalar>

## License

The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).

---
_Source: https://npm.io/package/@scalar/openapi-types · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._