oav

Batteries-included distribution of oav-core. Adds YAML readers and the oav CLI on top of the lean validator package; the programmatic surface is identical.

import { createValidator, createYamlFileReader } from "@aahoughton/oav";
import { loadSpec } from "@aahoughton/oav/spec";

const { document } = await loadSpec({
  reader: createYamlFileReader(),
  entry: "openapi.yaml",
});
const validator = createValidator(document);

When to use which

| Package | When to use | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | oav | Includes YAML readers and the oav CLI binary. Pulls in yaml, commander, and esbuild (CLI-only). | | oav-core | Lean. Zero runtime dependencies. JSON specs only (or pre-parsed objects via the memory reader). Use on Cloudflare Workers, Vercel Edge, Lambda@Edge, or anywhere the YAML/CLI footprint isn't worth it. |

oav re-exports every subpath of oav-core at matching paths (oav/schema, oav/spec, oav/formats, oav/core, oav/schema/internals, oav/validator/internals). Code written against one swaps to the other by changing the package name in imports — no surface changes.

What this package adds

• createYamlFileReader() — file reader for .yaml / .yml paths. Calling oav-core's createFileReader() on a YAML path throws an install-hint pointing here.
• createSmartHttpReader() — HTTP reader that parses both JSON and YAML by inspecting Content-Type / file extension.
• parseYamlString(source) — exposed for callers loading YAML out-of-band (e.g. fetched from a config service).
• The oav CLI binary — oav resolve, oav validate, oav compile-schema, oav compile-spec. See packages/cli/README.md for commands and flags.

Everything else (createValidator, compileSchema, error helpers, formatters, formatSummary, toProblemDetails, HTTP-status helpers, …) is re-exported from oav-core. Documentation for those lives in:

• packages/core/README.md — error tree, formatters, HTTP helpers.
• packages/validator/README.md — the HTTP validator.
• packages/schema/README.md — the JSON Schema compiler.
• packages/spec/README.md — multi-file loader, resolver, overlays.
• packages/formats/README.md — built-in string format validators.

Framework integration

oav is a validator, not a middleware package. Companion adapter packages cover the framework wiring: oav-express4, oav-express5, oav-fastify. See INTEGRATION.md for adapter recipes plus manual integration patterns for Next.js, Hono, Bun, and Deno via the Web Standards adapter.

See also

• Top-level README.md — full rationale, install matrix, comparison.
• INTEGRATION.md — adapter recipes, security wiring, response validation, file uploads, migration.
• OVERLAYS.md — extending an externally-owned base spec at load time.
• COMPARISON.md — feature comparison vs Ajv.