appear-sh/OAS-Zod-Validator

README

OAS Zod Validator

The open-source OpenAPI Spec Validator using Zod. From Appear.
Learn more »

Appear site · Issues · OSS API Schema Validator tool

OAS Zod Validator

A robust OpenAPI Specification (OAS) validator built with Zod, providing type-safe schema validation for both OAS 3.0.x, 3.1, and 3.2 specifications.

Project status

Maintainers are focused on ctxpipe (ctxpipe.ai). This repository stays open and the published package remains usable. Support from here on is light: issues and PRs are welcome, but responses will be slower and new feature work is unlikely unless it is a clear correctness fix.

Features

Full OpenAPI 3.0.x, 3.1, and 3.2 support
Type-safe validation using Zod
Enhanced error reporting with error codes, suggestions, and spec links
Bundled single-file output (deps are bundled at build time — no install-time link needed for consumers)
Enterprise-ready with strict mode validation
Supports both YAML and JSON formats
Interactive CLI with rich reporting
Comprehensive numeric format validations
Rate limit header enforcement options
Custom format validators
Performance optimization with caching for large schemas
Realworld examples you can quickly validate for assessments

NPX for on the fly spec validation in the CLI

npx @appear.sh/oas-zod-validator path/to/your/spec.json

Installation

npm install @appear.sh/oas-zod-validator

Quick Start

import { validateOpenAPI } from '@appear.sh/oas-zod-validator';

// Validate an OpenAPI spec (JSON or YAML)
const result = validateOpenAPI({
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0',
  },
  paths: {
    '/hello': {
      get: {
        responses: {
          '200': {
            description: 'Success',
          },
        },
      },
    },
  },
});

if (result.valid) {
  console.log('✅ Valid OpenAPI specification');
} else {
  console.error('❌ Validation errors:', result.errors);
}

Enhanced Error Reporting

Every validation error includes rich, actionable information:

if (!result.valid && result.errors) {
  result.errors.issues.forEach((issue) => {
    console.log(issue.errorCode); // "ERR_006"
    console.log(issue.message); // "Object types must define either properties..."
    console.log(issue.suggestion); // "Add `properties: { ... }` to define the object fields..."
    console.log(issue.specLink); // "https://appear.sh/api-toolkit/specs?openapi=3.0.3#schema-object"
    console.log(issue.category); // "schema"
    console.log(issue.severity); // "error" or "warning"
    console.log(issue.path); // ["components", "schemas", "MySchema", "properties"]
  });
}

Property	Description
`errorCode`	Standardized code (e.g., `ERR_006`) for programmatic handling
`message`	Human-readable error description
`suggestion`	Actionable fix guidance
`specLink`	Direct link to relevant OpenAPI spec section
`category`	Error category: `schema`, `format`, `reference`, `pattern`, etc.
`severity`	`error` or `warning`
`path`	JSON path to the error location

Summary Statistics

For aggregate error reporting, use validateOpenAPIEnhanced():

import { validateOpenAPIEnhanced } from '@appear.sh/oas-zod-validator';

const result = validateOpenAPIEnhanced(spec);

if (!result.valid) {
  console.log(result.summary);
  // {
  //   errors: 5,
  //   warnings: 2,
  //   byCategory: { schema: 3, format: 2, reference: 2 },
  //   byCode: { ERR_006: 3, ERR_001: 2, ERR_010: 2 }
  // }
}

CLI Usage

# Install globally
npm install -g @appear.sh/oas-zod-validator

# Validate a spec file
oas-validate api.yaml

# With strict validation options
oas-validate --strict --rate-limits api.json

# Interactive mode with guidance
oas-validate --interactive

# JSON output for CI/CD pipelines
oas-validate --json api.yaml

Advanced Usage

Performance Optimization with Caching

Caching is enabled by default and significantly improves performance for repeated validations of the same specification:

// Validate with default caching (enabled)
const result = validateOpenAPI(spec);

// Disable caching if needed
const resultNoCache = validateOpenAPI(spec, {
  cache: { enabled: false },
});

// Configure cache size
const resultWithLargeCache = validateOpenAPI(spec, {
  cache: { maxSize: 1000 },
});

// Reset the cache manually
import { resetCache } from '@appear.sh/oas-zod-validator';
resetCache();

// Configure the global cache
import { configureCache } from '@appear.sh/oas-zod-validator';
configureCache({ maxSize: 2000 });

The caching system optimizes:

OpenAPI document validation
YAML/JSON parsing
Reference resolution

This is particularly beneficial for:

Large API specifications
CI/CD pipelines with repeated validations
Development workflows with incremental changes

Custom Format Validation

// Define custom format validators
const phoneValidator = (value: string) => {
  return /^\+[1-9]\d{1,14}$/.test(value);
};

// Use in validation
const result = validateOpenAPI(spec, {
  customFormats: {
    phone: phoneValidator,
  },
});

Combining Multiple Options

const result = validateOpenAPI(spec, {
  strict: true,
  allowFutureOASVersions: true,
  strictRules: {
    requireRateLimitHeaders: true,
  },
  customFormats: {
    phone: phoneValidator,
  },
});

Configuration File

Create .oas-validate.json for persistent options:

{
  "strict": true,
  "allowFutureOASVersions": false,
  "requireRateLimitHeaders": true,
  "format": "pretty"
}

Documentation

Performance and large specs

For very large specs (multi‑MB), the validator provides options to reduce CPU and memory while preserving correctness:

fastMode: Enables structural validation and skips heavy checks. Equivalent to enabling skipExamples and skipPatternChecks.
noLocation: Skips computing source locations; avoids building ASTs/Document for files (big speedup on large files).
autoFastThresholdBytes: Auto‑enable fast mode when content size exceeds this threshold. Defaults to ~15 MiB.
maxErrors: Cap the number of reported issues. Useful to short‑circuit runaway errors in huge inputs.
skipExamples: Skip validating example values.
skipPatternChecks: Skip expensive regex validations.

CLI flags:

--fast, --no-location, --max-errors <n>, --auto-fast-threshold <bytes>, --skip-examples, --skip-pattern-checks, --quiet.

Caching:

Validation results, schema parsing and $ref targets are cached with a true LRU.
Cache keys are compact and stable (hashed document signature + minimal options that affect semantics).
Adaptive memory options are supported; see getValidationCache for knobs.

Development

# Install dependencies
npm install

# Run tests (uses Vitest)
npm test

# Run tests in verbose mode (uses Vitest)
VERBOSE_INTEGRATION=1 npm test

# Watch mode for development
npm run test:watch

# Build
npm run build

Requires Node.js 20+; Node 22+ LTS is recommended (the repo ships an .nvmrc pinning Node 22).

This project uses TypeScript with ESM modules and Vitest for testing. It follows strict coding practices and maintains high test coverage.

Contributing

Contributions are welcome! Please follow these steps:

Fork & Clone: Fork the repository and clone it locally.
Branch: Create a new branch for your feature or bug fix.
Develop: Make your code changes. Ensure tests pass (npm test).
Add a Changeset: This project uses Changesets to manage releases and generate changelogs. If your change impacts the package (e.g., bug fix, new feature, performance improvement), you must add a changeset file. Run the following command:
```
npm run changeset
```
Follow the prompts:
- Select oas-zod-validator as the package.
- Choose the appropriate SemVer bump level (patch, minor, or major) based on your changes.
- Write a concise description of your change. This description will appear in the CHANGELOG.md.
Commit: Commit your code changes and the generated markdown file located in the .changeset/ directory (e.g., .changeset/sweet-donkeys-cry.md).
Push & PR: Push your branch and open a Pull Request against the main branch.

Maintainers will handle versioning and releases from changeset files on merged PRs. Review and release cadence is light while work is concentrated on ctxpipe.

License

MIT © Thomas Peterson + Jakub Riedl @ https://www.appear.sh & https://ctxpipe.ai

Core maintainers

Active work is on ctxpipe-ai/ctxpipe.

X: https://x.com/tom_mkv
X: https://x.com/jakubriedl

For bug reports, feature requests, or contributions, use this repository's issues. Expect light support.

README

OAS Zod Validator

The open-source OpenAPI Spec Validator using Zod. From Appear.
Learn more »

Appear site · Issues · OSS API Schema Validator tool

OAS Zod Validator

A robust OpenAPI Specification (OAS) validator built with Zod, providing type-safe schema validation for both OAS 3.0.x, 3.1, and 3.2 specifications.

Project status

Features

Full OpenAPI 3.0.x, 3.1, and 3.2 support
Type-safe validation using Zod
Enhanced error reporting with error codes, suggestions, and spec links
Bundled single-file output (deps are bundled at build time — no install-time link needed for consumers)
Enterprise-ready with strict mode validation
Supports both YAML and JSON formats
Interactive CLI with rich reporting
Comprehensive numeric format validations
Rate limit header enforcement options
Custom format validators
Performance optimization with caching for large schemas
Realworld examples you can quickly validate for assessments

NPX for on the fly spec validation in the CLI

npx @appear.sh/oas-zod-validator path/to/your/spec.json

Installation

npm install @appear.sh/oas-zod-validator

Quick Start

import { validateOpenAPI } from '@appear.sh/oas-zod-validator';

// Validate an OpenAPI spec (JSON or YAML)
const result = validateOpenAPI({
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0',
  },
  paths: {
    '/hello': {
      get: {
        responses: {
          '200': {
            description: 'Success',
          },
        },
      },
    },
  },
});

if (result.valid) {
  console.log('✅ Valid OpenAPI specification');
} else {
  console.error('❌ Validation errors:', result.errors);
}

Enhanced Error Reporting

Every validation error includes rich, actionable information:

if (!result.valid && result.errors) {
  result.errors.issues.forEach((issue) => {
    console.log(issue.errorCode); // "ERR_006"
    console.log(issue.message); // "Object types must define either properties..."
    console.log(issue.suggestion); // "Add `properties: { ... }` to define the object fields..."
    console.log(issue.specLink); // "https://appear.sh/api-toolkit/specs?openapi=3.0.3#schema-object"
    console.log(issue.category); // "schema"
    console.log(issue.severity); // "error" or "warning"
    console.log(issue.path); // ["components", "schemas", "MySchema", "properties"]
  });
}

Property	Description
`errorCode`	Standardized code (e.g., `ERR_006`) for programmatic handling
`message`	Human-readable error description
`suggestion`	Actionable fix guidance
`specLink`	Direct link to relevant OpenAPI spec section
`category`	Error category: `schema`, `format`, `reference`, `pattern`, etc.
`severity`	`error` or `warning`
`path`	JSON path to the error location

Summary Statistics

For aggregate error reporting, use validateOpenAPIEnhanced():

import { validateOpenAPIEnhanced } from '@appear.sh/oas-zod-validator';

const result = validateOpenAPIEnhanced(spec);

if (!result.valid) {
  console.log(result.summary);
  // {
  //   errors: 5,
  //   warnings: 2,
  //   byCategory: { schema: 3, format: 2, reference: 2 },
  //   byCode: { ERR_006: 3, ERR_001: 2, ERR_010: 2 }
  // }
}

CLI Usage

# Install globally
npm install -g @appear.sh/oas-zod-validator

# Validate a spec file
oas-validate api.yaml

# With strict validation options
oas-validate --strict --rate-limits api.json

# Interactive mode with guidance
oas-validate --interactive

# JSON output for CI/CD pipelines
oas-validate --json api.yaml

Advanced Usage

Performance Optimization with Caching

Caching is enabled by default and significantly improves performance for repeated validations of the same specification:

// Validate with default caching (enabled)
const result = validateOpenAPI(spec);

// Disable caching if needed
const resultNoCache = validateOpenAPI(spec, {
  cache: { enabled: false },
});

// Configure cache size
const resultWithLargeCache = validateOpenAPI(spec, {
  cache: { maxSize: 1000 },
});

// Reset the cache manually
import { resetCache } from '@appear.sh/oas-zod-validator';
resetCache();

// Configure the global cache
import { configureCache } from '@appear.sh/oas-zod-validator';
configureCache({ maxSize: 2000 });

The caching system optimizes:

OpenAPI document validation
YAML/JSON parsing
Reference resolution

This is particularly beneficial for:

Large API specifications
CI/CD pipelines with repeated validations
Development workflows with incremental changes

Custom Format Validation

// Define custom format validators
const phoneValidator = (value: string) => {
  return /^\+[1-9]\d{1,14}$/.test(value);
};

// Use in validation
const result = validateOpenAPI(spec, {
  customFormats: {
    phone: phoneValidator,
  },
});

Combining Multiple Options

const result = validateOpenAPI(spec, {
  strict: true,
  allowFutureOASVersions: true,
  strictRules: {
    requireRateLimitHeaders: true,
  },
  customFormats: {
    phone: phoneValidator,
  },
});

Configuration File

Create .oas-validate.json for persistent options:

{
  "strict": true,
  "allowFutureOASVersions": false,
  "requireRateLimitHeaders": true,
  "format": "pretty"
}

Documentation

Performance and large specs

For very large specs (multi‑MB), the validator provides options to reduce CPU and memory while preserving correctness:

fastMode: Enables structural validation and skips heavy checks. Equivalent to enabling skipExamples and skipPatternChecks.
noLocation: Skips computing source locations; avoids building ASTs/Document for files (big speedup on large files).
autoFastThresholdBytes: Auto‑enable fast mode when content size exceeds this threshold. Defaults to ~15 MiB.
maxErrors: Cap the number of reported issues. Useful to short‑circuit runaway errors in huge inputs.
skipExamples: Skip validating example values.
skipPatternChecks: Skip expensive regex validations.

CLI flags:

--fast, --no-location, --max-errors <n>, --auto-fast-threshold <bytes>, --skip-examples, --skip-pattern-checks, --quiet.

Caching:

Validation results, schema parsing and $ref targets are cached with a true LRU.
Cache keys are compact and stable (hashed document signature + minimal options that affect semantics).
Adaptive memory options are supported; see getValidationCache for knobs.

Development

# Install dependencies
npm install

# Run tests (uses Vitest)
npm test

# Run tests in verbose mode (uses Vitest)
VERBOSE_INTEGRATION=1 npm test

# Watch mode for development
npm run test:watch

# Build
npm run build

Requires Node.js 20+; Node 22+ LTS is recommended (the repo ships an .nvmrc pinning Node 22).

This project uses TypeScript with ESM modules and Vitest for testing. It follows strict coding practices and maintains high test coverage.

Contributing

Contributions are welcome! Please follow these steps:

Fork & Clone: Fork the repository and clone it locally.
Branch: Create a new branch for your feature or bug fix.
Develop: Make your code changes. Ensure tests pass (npm test).
Add a Changeset: This project uses Changesets to manage releases and generate changelogs. If your change impacts the package (e.g., bug fix, new feature, performance improvement), you must add a changeset file. Run the following command:
```
npm run changeset
```
Follow the prompts:
- Select oas-zod-validator as the package.
- Choose the appropriate SemVer bump level (patch, minor, or major) based on your changes.
- Write a concise description of your change. This description will appear in the CHANGELOG.md.
Commit: Commit your code changes and the generated markdown file located in the .changeset/ directory (e.g., .changeset/sweet-donkeys-cry.md).
Push & PR: Push your branch and open a Pull Request against the main branch.

Maintainers will handle versioning and releases from changeset files on merged PRs. Review and release cadence is light while work is concentrated on ctxpipe.

License

Core maintainers

Active work is on ctxpipe-ai/ctxpipe.

X: https://x.com/tom_mkv
X: https://x.com/jakubriedl

For bug reports, feature requests, or contributions, use this repository's issues. Expect light support.