# oas-normalize

> Tooling for converting, validating, and parsing OpenAPI, Swagger, and Postman API definitions

Latest version **18.0.2** (published 2026-09-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install oas-normalize
pnpm add oas-normalize
yarn add oas-normalize
bun add oas-normalize
```

## Health

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

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 18.0.2 |
| Published | 2026-09-04 |
| First published | 2018-05-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 5 |
| Unpacked size | 100.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 400 |
| Maintainers | gkoberger, domharrington, mjcuva, jonursenbach, rafegoldberg, darrenyong |
| Keywords | api, apidoc, apis, documentation, microservice, oai, oas, openapi, openapi document, openapi initiative, openapi spec, openapi specification, postman, swagger |

## Links

- npm: https://www.npmjs.com/package/oas-normalize
- Repository: https://github.com/readmeio/oas
- Homepage: https://github.com/readmeio/oas#readme
- Issues: https://github.com/readmeio/oas/issues
- npm.io page: https://npm.io/package/oas-normalize

## Dependencies (5)

- [js-yaml](https://npm.io/package/js-yaml.md) ^5.4.1
- [openapi-types](https://npm.io/package/openapi-types.md) ^12.1.3
- [swagger2openapi](https://npm.io/package/swagger2openapi.md) ^7.0.8
- [@readme/openapi-parser](https://npm.io/package/@readme/openapi-parser.md) ^9.0.0
- [@readme/postman-to-openapi](https://npm.io/package/@readme/postman-to-openapi.md) ^4.1.0

## Alternatives

- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads

## Recent versions

- 18.0.2 (latest) — 2026-09-04
- 18.0.1 — 2026-09-02
- 18.0.0 — 2026-08-25
- 17.0.1 — 2026-08-07
- 17.0.0 — 2026-08-04
- 16.1.2 — 2026-07-28
- 16.1.1 — 2026-07-01
- 16.1.0 — 2026-07-01
- 16.0.5 — 2026-06-04
- 16.0.4 — 2026-04-02
- 16.0.3 — 2026-03-31
- 16.0.2 — 2026-03-03
- 16.0.0 — 2026-03-02
- 15.7.1 — 2026-02-05
- 15.7.0 — 2026-01-08
- … 98 more at https://npm.io/package/oas-normalize/versions

## README

<p align="center">
  <a href="https://npm.im/oas-normalize">
    <img src="https://user-images.githubusercontent.com/33762/200434622-23946869-1965-46f8-8deb-f284b8d0b92c.png" alt="oas-normalize" />
  </a>
</p>

<p align="center">
  Tooling for converting, validating, and parsing OpenAPI, Swagger, and Postman API definitions.
</p>

<p align="center">
  <a href="https://npm.im/oas-normalize"><img src="https://img.shields.io/npm/v/oas-normalize?style=for-the-badge" alt="NPM Version"></a>
  <a href="https://npm.im/oas-normalize"><img src="https://img.shields.io/node/v/oas-normalize?style=for-the-badge" alt="Node Version"></a>
  <a href="https://npm.im/oas-normalize"><img src="https://img.shields.io/npm/l/oas-normalize?style=for-the-badge" alt="MIT License"></a>
  <a href="https://github.com/readmeio/oas/tree/main/packages/oas-normalize"><img src="https://img.shields.io/github/actions/workflow/status/readmeio/oas/ci.yml?branch=main&style=for-the-badge" alt="Build status"></a>
</p>

<p align="center">
  <a href="https://readme.com"><img src="https://raw.githubusercontent.com/readmeio/.github/main/oss-badge.svg" /></a>
</p>

## Installation

```bash
npm install oas-normalize
```

## Usage

```ts
import OASNormalize from 'oas-normalize';

const oas = new OASNormalize(
  'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore-expanded.yaml',
  // ...or a JSON object, YAML, a file path, stringified JSON, whatever you have.
);

await oas
  .validate()
  .then(() => {
    // The API definition is valid!
  })
  .catch(err => {
    console.error(err);
  });
```

> [!WARNING]
> Support for Postman collections is experimental. If you've supplied a Postman collection to the library, it will **always** be converted to OpenAPI, using [`@readme/postman-to-openapi`](https://npm.im/@readme/postman-to-openapi) before doing any bundling, validating, etc.

### `.load()`

Load and retrive the API definition that `oas-normalize` was initialized with. Every method of `oas-normalize` utilizes this internally however if you would like to retrieve the original API _definition_ supplied (for example if all you had was a URL, a file path, or a buffer), you can use `.load()` to automatically resolve and return its contents.

```ts
const file = await oas.load();
console.log(file);
```

### `.bundle()`

Bundle up the given API definition, resolving any external `$ref` pointers in the process.

```ts
const definition = await oas.bundle();
console.log(definition);
```

### `.convert()`

Convert a given API definition into an OpenAPI definition JSON object.

```ts
await oas
  .convert()
  .then(definition => {
    // Definition will always be an OpenAPI JSON object, regardless if a
    // Swagger definition, Postman collection, or even YAML was supplied.
    console.log(definition);
  })
  .catch(err => {
    console.error(err);
  });
```

### `.deref()`

Dereference the given API definition, resolving all `$ref` pointers in the process.

```ts
const definition = await oas.bundle();
console.log(definition);
```

### `.validate()`

Validate a given API definition. This supports Swagger 2.0 and OpenAPI 3.x API definitions, as well as Postman 2.x collections.

```ts
try {
  await oas.validate();
  // The API definition is valid!
} catch (err) {
  console.error(err);
}
```

#### Error Handling

All errors will be thrown as a `ValidationError` exception with contextual error messages that direct the user to the line(s) where their errors are present:

```
OpenAPI schema validation failed.

REQUIRED must have required property 'url'

   7 |   },
   8 |   "servers": [
>  9 |     {
     |     ^ ☹️  url is missing here!
  10 |       "urll": "http://petstore.swagger.io/v2"
  11 |     }
  12 |   ],
```

If you also wish to treat certain errors as warnings you can do so by supplying your `.validate()` call with a [`@readme/openapi-parser`](https://npm.im/@readme/openapi-parser) ruleset:

```ts
try {
  const result = await oas.validate({
    parser: {
      validate: {
        rules: {
          openapi: {
            'path-parameters-not-in-path': 'warning',
          },
        },
      },
    },
  });

  if (result.warnings.length) {
    console.warn('🚸 The API is valid but has some warnings.');
    console.warn(result.warnings);
  } else {
    console.log('🍭 The API is valid!');
  }
} catch (err) {
  console.error(err);
}
```

If you want to always receive a `ValidationResult` object back (which includes a flag that indicates if the supplied API definition is valid or not), you can set the `shouldThrowIfInvalid` option to `false`:

```ts
const result = await oas.validate({ shouldThrowIfInvalid: false });
console.log(result);

/*
{
  valid: false,
  errors: [
    { message: 'REQUIRED must have required property "url"' },
  ],
  warnings: [],
  additionalErrors: 0,
  specification: 'OpenAPI',
} */
```

> [!NOTE]
> For full documentation on the available rulesets, as well as tooling to transform `ValidateResult` objects into a human-readable strings, check out the documentation for [`@readme/openapi-parser`](https://npm.im/@readme/openapi-parser).

### `.version()`

Load and retrieve version information about a supplied API definition.

```ts
const { specification, version } = await oas.version();

console.log(specification); // openapi
console.log(version); // 3.1.0
```

### Options

##### Enable local paths

For security reasons, you need to opt into allowing fetching by a local path. To enable this supply the `enablePaths` option to the class instance:

```ts
const oas = new OASNormalize('./petstore.json', { enablePaths: true });
```

##### Colorized errors

If you wish errors from `.validate()` to be styled and colorized, supply `colorizeErrors: true` to the class instance:

```ts
const oas = new OASNormalize('https://example.com/petstore.json', {
  colorizeErrors: true,
});
```

When enabled thrown validation error messages will now resemble the following:

<img src="https://user-images.githubusercontent.com/33762/137796648-7e1157c2-cee4-466e-9129-dd2a743dd163.png" width="600" />

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