@appear.sh/oas-zod-validator NPM

OAS Zod Validator

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

Features

Full OpenAPI 3.0.x and 3.1 support
Type-safe validation using Zod
Detailed error messages with path information
Zero external runtime dependencies
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 '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);
}

CLI Usage

# Install globally
npm install -g 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 'oas-zod-validator';
resetCache();

// Configure the global cache
import { configureCache } from '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

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

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.