# @redocly/openapi-core

> See https://github.com/Redocly/redocly-cli

Latest version **2.56.1** (published 2026-09-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @redocly/openapi-core
pnpm add @redocly/openapi-core
yarn add @redocly/openapi-core
bun add @redocly/openapi-core
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.56.1 |
| Published | 2026-09-30 |
| First published | 2020-11-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1516 |
| Maintainers | romanhotsiy, alawar, adamaltman, marshevskyy, volodymyr-rutskyi |
| Keywords | linter, OpenAPI, Swagger, OpenAPI linter, Swagger linter, AsyncAPI linter, Arazzo linter, oas |

## Links

- npm: https://www.npmjs.com/package/@redocly/openapi-core
- Repository: https://github.com/Redocly/redocly-cli
- Issues: https://github.com/Redocly/redocly-cli/issues
- npm.io page: https://npm.io/package/@redocly/openapi-core

## 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

- 2.56.1 (latest) — 2026-09-30
- 0.0.0-snapshot.1790673161 (snapshot) — 2026-09-29
- 1.34.20 (v1-archive) — 2026-09-09
- 2.0.0-next.10 (next) — 2025-07-24
- 2.56.0 — 2026-09-30
- 0.0.0-snapshot.1790672883 — 2026-09-29
- 0.0.0-snapshot.1790672768 — 2026-09-29
- 2.55.0 — 2026-09-28
- 0.0.0-snapshot.1790608326 — 2026-09-28
- 0.0.0-snapshot.1790590402 — 2026-09-28
- 2.54.3 — 2026-09-25
- 0.0.0-snapshot.1790327117 — 2026-09-25
- 0.0.0-snapshot.1790241665 — 2026-09-24
- 0.0.0-snapshot.1790175435 — 2026-09-23
- 0.0.0-snapshot.1790175030 — 2026-09-23
- … 761 more at https://npm.io/package/@redocly/openapi-core/versions

## README

# openapi-core

See https://github.com/Redocly/redocly-cli

> [!IMPORTANT]
> The `openapi-core package` is designed for our internal use; the interfaces that are considered safe to use are documented below.
> Some of the function arguments are not documented below because they are not intended for public use.
> Avoid using any functions or features that are not documented below.
> If your use case is not documented below, please open an issue.

## Basic usage

### Lint from file system

[Lint](https://redocly.com/docs/cli/commands/lint/) a file.

```js
import { lint, loadConfig } from '@redocly/openapi-core';

const pathToApi = 'openapi.yaml';
const config = await loadConfig({ configPath: 'optional/path/to/redocly.yaml' });
const lintResults = await lint({ ref: pathToApi, config });
```

The content of `lintResults` describes any errors or warnings found during linting; an empty array means no problems were found.
For each problem, the rule, severity, feedback message and a location object are provided.
To learn more, [check the `lint` function section](#lint).

### Bundle from file system

[Bundle](https://redocly.com/docs/cli/commands/bundle/) an API description into a single structure.

```js
import { bundle, loadConfig } from '@redocly/openapi-core';

const pathToApi = 'openapi.yaml';
const config = await loadConfig({ configPath: 'optional/path/to/redocly.yaml' });
const bundleResults = await bundle({ ref: pathToApi, config });
```

In `bundleResults`, the `bundle.parsed` field has the bundled API description.
For more information, [check the `bundle` function section](#bundle).

### Lint from memory with config

[Lint](https://redocly.com/docs/cli/commands/lint/) an API description, with configuration defined. This is useful if the API description you're working with isn't a file on disk.

```js
import { lintFromString, createConfig, stringifyYaml } from '@redocly/openapi-core';

const config = await createConfig(
  {
    extends: ['minimal'],
    rules: {
      'operation-description': 'error',
    },
  },
  {
    // optionally provide config path for resolving $refs and proper error locations
    configPath: 'optional/path/to/redocly.yaml',
  }
);
const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
const lintResults = await lintFromString({
  source,
  // optionally pass path to the file for resolving $refs and proper error locations
  absoluteRef: 'optional/path/to/openapi.yaml',
  config,
});
```

### Lint from memory with a custom plugin

[Lint](https://redocly.com/docs/cli/commands/lint/) an API description, with configuration including a [custom plugin](https://redocly.com/docs/cli/custom-plugins/) to define a rule.

```js
import { lintFromString, createConfig, stringifyYaml } from '@redocly/openapi-core';

const CustomRule = (ruleOptions) => {
  return {
    Operation() {
      // some rule logic
    },
  };
};

const config = await createConfig({
  extends: ['recommended'],
  plugins: [
    {
      id: 'pluginId',
      rules: {
        oas3: {
          customRule1: CustomRule,
        },
        oas2: {
          customRule1: CustomRule, // if the same rule can handle both oas3 and oas2
        },
      },
      decorators: {
        // ...
      },
    },
  ],
  // enable rule
  rules: {
    'pluginId/customRule1': 'error',
  },
  decorators: {
    // ...
  },
});

const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
const lintResults = await lintFromString({
  source,
  // optionally pass path to the file for resolving $refs and proper error locations
  absoluteRef: 'optional/path/to/openapi.yaml',
  config,
});
```

### Bundle from memory

[Bundle](https://redocly.com/docs/cli/commands/bundle/) an API description into a single structure, using default configuration.

```js
import { bundleFromString, createConfig } from '@redocly/openapi-core';

const config = await createConfig({}); // create empty config
const source = stringifyYaml({ openapi: '3.0.1' /* ... */ }); // you can also use JSON.stringify
const bundleResults = await bundleFromString({
  source,
  // optionally pass path to the file for resolving $refs and proper error locations
  absoluteRef: 'optional/path/to/openapi.yaml',
  config,
});
```

### Load and lint a configuration file

[Lint](https://redocly.com/docs/cli/commands/lint/) a configuration file to validate its structure and rules.

```js
import { lintConfig, loadConfig } from '@redocly/openapi-core';

const config = await loadConfig({ configPath: 'redocly.yaml' });
const configProblems = await lintConfig({ config });
```

## API

### `createConfig`

Creates a config object from a JSON or YAML string or JS object.
Resolves remote config from `extends` (if there are URLs or local fs paths).

```ts
async function createConfig(
  // JSON or YAML string or object with Redocly config
  config: string | RawUniversalConfig,
  options?: {
    // optional path to the config file for resolving $refs and proper error locations
    configPath?: string;
  }
): Promise<Config>;
```

### `loadConfig`

Loads a config object from a file system. If `configPath` is not provided,
it tries to find `redocly.yaml` in the current working directory.

```ts
async function loadConfig(options?: {
  // optional path to the config file for resolving $refs and proper error locations
  configPath?: string;
  // allows to add custom `extends` instead of the one from the config file
  customExtends?: string[];
  // whether to resolve plugin paths without importing the plugin code
  skipPluginEval?: boolean;
}): Promise<Config>;
```

Use `skipPluginEval` to read a config without executing any plugin code, for example when the plugins come from an untrusted source.
The returned config is incomplete: rules and decorators from plugins aren't loaded, and `extends` isn't resolved, so the presets it lists are ignored.

### `lintConfig`

Lint a configuration file to validate its structure and rules.

```ts
async function lintConfig(options: {
  // config object to validate
  config: Config;
  // optional severity level for validation
  severity?: ProblemSeverity;
  // optional external reference resolver
  externalRefResolver?: BaseResolver;
  // optional override for config types
  externalConfigTypes?: Record<string, NodeType>;
}): Promise<NormalizedProblem[]>;
```

### `lint`

Lint an OpenAPI document from the file system.

```ts
async function lint(options: {
  // path to the OpenAPI document root
  ref: string;
  // config object
  config: Config;
  // optional external reference resolver
  externalRefResolver?: BaseResolver;
}): Promise<NormalizedProblem[]>;
```

### `lintFromString`

Lint an OpenAPI document from a string.

```ts
async function lintFromString(options: {
  // OpenAPI document string
  source: string;
  // optional path to the OpenAPI document for resolving $refs and proper error locations
  absoluteRef?: string;
  // config object
  config: Config;
  // optional external reference resolver
  externalRefResolver?: BaseResolver;
}): Promise<NormalizedProblem[]>;
```

### `bundle`

Bundle an OpenAPI document from the file system.

```ts
async function bundle(options: {
  // path to the OpenAPI document root
  ref?: string;
  // optional document object (alternative to ref)
  doc?: Document;
  // config object
  config: Config;
  // whether to fully dereference $refs, resulting document won't have any $ref
  // warning: this can produce circular objects
  dereference?: boolean;
  // whether to remove unused components (schemas, parameters, responses, etc)
  removeUnusedComponents?: boolean;
  // whether to keep $ref pointers to the http URLs and resolve only local fs $refs
  keepUrlRefs?: boolean;
  // optional external reference resolver
  externalRefResolver?: BaseResolver;
  // optional base path for resolution
  base?: string | null;
}): Promise<{
  bundle: {
    parsed: object; // OpenAPI document object as js object
  };
  problems: NormalizedProblem[];
  fileDependencies;
  rootType;
  refTypes;
  visitorsData;
}>;
```

### `bundleFromString`

Bundle an OpenAPI document from a string.

```ts
async function bundleFromString(options: {
  // OpenAPI document string
  source: string;
  // optional path to the OpenAPI document for resolving $refs and proper error locations
  absoluteRef?: string;
  // config object
  config: Config;
  // whether to fully dereference $refs, resulting document won't have any $ref
  // warning: this can produce circular objects
  dereference?: boolean;
  // whether to remove unused components (schemas, parameters, responses, etc)
  removeUnusedComponents?: boolean;
  // whether to keep $ref pointers to the http URLs and resolve only local fs $refs
  keepUrlRefs?: boolean;
  // optional external reference resolver
  externalRefResolver?: BaseResolver;
}): Promise<{
  bundle: {
    parsed: object; // OpenAPI document object as js object
  };
  problems: NormalizedProblem[];
  fileDependencies;
  rootType;
  refTypes;
  visitorsData;
}>;
```

### `stringifyYaml`

Helper function to stringify a javascript object to YAML.

```ts
function stringifyYaml(obj: object): string;
```

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