@powerduck/openapi-parser

@powerduck/openapi-parser

Upgrade any OpenAPI document — Swagger 2.0, OpenAPI 3.0, 3.1, or 3.2 — to OpenAPI 3.2, in one call.

A thin wrapper over @scalar/openapi-parser and @scalar/openapi-upgrader. It does not reimplement parsing, validation, or upgrading; it wires them together and gives every failure a single, predictable shape with a machine-readable error code.

Features

• One function, every version — Swagger 2.0, OpenAPI 3.0.x, 3.1.x, and 3.2.x all upgrade to a validated 3.2 document.
• JSON and YAML string input — Pass a pre-parsed object or a raw JSON/YAML string. Parsing is delegated to @scalar/openapi-parser's validate().
• Machine-readable error codes — Every failure mode surfaces an OpenApiUpgradeError with a UpgradeErrorCode enum value. No string matching in production code.
• Zero input mutation — The input document is deep-copied (via structuredClone) before any upgrade stage runs. Your object is never modified.
• Circular-reference guard — Detects cyclic input before it can cause stack overflows in downstream upgraders. Configurable depth.
• Output validation — The upgraded 3.2 document is schema-validated by default. Disable via options if you need raw output.
• Dual ESM + CJS — import in modern Node and bundlers, require() in Electron main process and legacy code.

Install

npm install @powerduck/openapi-parser

Requires Node.js 18 or later.

Usage

import { upgradeOasTo32 } from "@powerduck/openapi-parser";
import { readFile } from "node:fs/promises";

// From a YAML string
const yaml = await readFile("./swagger.yaml", "utf8");
const document = await upgradeOasTo32(yaml);

// From a JSON string
const doc = await upgradeOasTo32('{"openapi":"3.1.0","info":{...}}');

// From a parsed object
const doc2 = await upgradeOasTo32({ openapi: "3.0.3", info: {...}, paths: {} });

console.log(document.openapi); // "3.2.0"

With options

const document = await upgradeOasTo32(input, {
  validateResult: true,   // validate the upgraded 3.2 document (default: true)
  checkVersion: true,      // assert output declares 3.2.x (default: true)
  maxDepth: 64,            // circular-reference scan depth (default: 64, 0 = disabled)
});

How it works

1. Input guard — The input must be a string or a plain object. Anything else (null, arrays, numbers) is rejected with INVALID_INPUT.
2. Circular-reference scan — Object input is walked up to maxDepth to detect cycles. Cyclic input is rejected with CIRCULAR_REFERENCE.
3. Deep copy — Object input is cloned via structuredClone, so downstream upgraders cannot mutate the caller's document.
4. Parse and validate — The input is handed to validate() from @scalar/openapi-parser. That single call parses the string (if it is one), checks the document against its own spec version, and reports which version that is.
5. First-stage upgrade — If the detected version is 2.0 or 3.0.x, the document goes through upgrade(), which lands it on 3.1. 3.1 and 3.2 documents skip this stage.
6. Second-stage upgrade — Every document goes through the 3.1 → 3.2 upgrader, so all callers get output from the same normalisation path.
7. Version assertion — The output is checked to declare OpenAPI 3.2.x (unless checkVersion: false).
8. Output validation — The upgraded document is schema-validated (unless validateResult: false).

API

upgradeOasTo32(input, options?)

Upgrades a Swagger 2.0 or OpenAPI 3.x document to OpenAPI 3.2.

Parameters:

Name	Type	Required	Description
input	OpenApiDocument | string	Yes	A Swagger 2.0 or OpenAPI 3.x document, as a plain object or as a JSON / YAML string.
options	UpgradeOptions	No	Optional configuration.

Returns: Promise<Oas32Document> — A validated OpenAPI 3.2 document.

Throws: OpenApiUpgradeError — See Error Codes for all possible failure modes.

UpgradeOptions

Property	Type	Default	Description
validateResult	boolean	true	Run schema validation on the upgraded 3.2 document.
checkVersion	boolean	true	Assert that the upgraded document declares OpenAPI 3.2.x.
maxDepth	number	64	Maximum nesting depth to scan for circular references. Set to 0 to disable the guard.

OpenApiUpgradeError

class OpenApiUpgradeError extends Error {
  readonly code: UpgradeErrorCode;
  readonly issues: readonly OpenApiValidationIssue[];
  readonly cause?: unknown;
}

isOpenApiUpgradeError(value)

Type guard. Returns true when the value is an OpenApiUpgradeError instance.

try {
  await upgradeOasTo32(input);
} catch (error) {
  if (isOpenApiUpgradeError(error)) {
    switch (error.code) {
      case UpgradeErrorCode.InvalidInput:
        console.error("Bad input:", error.message);
        break;
      case UpgradeErrorCode.CircularReference:
        console.error("Cyclic document detected");
        break;
      default:
        console.error(`Upgrade failed (${error.code}):`, error.message);
    }
  } else {
    throw error; // unexpected, rethrow
  }
}

Error Codes

Code	Value	When it happens
InvalidInput	"INVALID_INPUT"	The input is not a string or a plain object (null, array, number, etc.).
ParseOrValidateFailed	"PARSE_OR_VALIDATE_FAILED"	The input could not be parsed, or failed initial schema validation. .issues carries the validator's issues.
FirstUpgradeFailed	"FIRST_UPGRADE_FAILED"	The 2.0/3.0 → 3.1 upgrader threw or returned no specification.
SecondUpgradeFailed	"SECOND_UPGRADE_FAILED"	The 3.1 → 3.2 upgrader threw.
VersionAssertionFailed	"VERSION_ASSERTION_FAILED"	The upgraded document does not declare OpenAPI 3.2.x.
ValidationFailed	"VALIDATION_FAILED"	The upgraded document failed schema validation.
CircularReference	"CIRCULAR_REFERENCE"	The input document contains a circular reference.

Exports

// Main function
import { upgradeOasTo32 } from "@powerduck/openapi-parser";

// Error handling
import {
  OpenApiUpgradeError,
  UpgradeErrorCode,
  isOpenApiUpgradeError,
  type UpgradeOptions,
  type OpenApiValidationIssue,
} from "@powerduck/openapi-parser";

// Document types
import type {
  Oas20Document,
  Oas30Document,
  Oas31Document,
  Oas32Document,
  OpenApiDocument,
  OpenApiInput,
  UpgradedDocument,
} from "@powerduck/openapi-parser";

// OpenAPI 3.2 schema object types
import type {
  SchemaObject,
  OperationObject,
  ParameterObject,
  PathItemObject,
  RequestBodyObject,
  ResponseObject,
  ServerObject,
  TagObject,
  MediaTypeObject,
} from "@powerduck/openapi-parser";

// Re-exported @scalar helpers (for advanced use)
import { dereference, upgrade, validate } from "@powerduck/openapi-parser";

Electron / CommonJS

const { upgradeOasTo32 } = require("@powerduck/openapi-parser");

upgradeOasTo32(specContent).then((doc) => {
  console.log(doc.openapi); // "3.2.0"
});

Development

npm install
npm run build       # tsup: ESM + CJS + .d.ts
npm run typecheck   # tsc --noEmit
npm test            # vitest run
npm run verify      # smoke-test both ESM and CJS builds

Links

• Official Website
• Documentation
• Live Demo
• GitHub
• npm

License

MIT