@cfworker/json-schema

@cfworker/json-schema is a JSON Schema validator written specifically for environments that can’t use eval or new Function — Cloudflare Workers and other service-worker-style sandboxes — where compiling-validator libraries like Ajv can’t run. It supports drafts 4, 7, 2019-09, and 2020-12, and is validated against the official json-schema-test-suite, a large set of conformance assertions maintained alongside the JSON Schema specification itself, making it one of the more spec-compliant validators available despite not compiling schemas to code.

Internally the library walks the schema tree at validation time rather than precompiling it: a dereference pass resolves every $id, $ref, $anchor, and $recursiveRef in the schema into a flat lookup table keyed by absolute URI, and a recursive validate function walks the instance and schema together, keyword by keyword, tracking which properties/items have been evaluated so keywords like unevaluatedProperties and unevaluatedItems work correctly. A shortCircuit flag controls whether validation stops at the first error or collects every error, and addSchema lets consumers register additional schemas into an existing validator’s lookup table at runtime for $ref resolution across documents.

What You Get

• A Validator class supporting JSON Schema drafts 4, 7, 2019-09, and 2020-12
• Multi-schema resolution via addSchema() and a $ref/$anchor/$recursiveRef-aware dereference pass
• A shortCircuit toggle to either fail fast or collect every validation error in one pass
• Structured OutputUnit errors with instance and schema JSON pointers for precise error reporting
• Zero dependencies and no use of eval/new Function, so it runs in Cloudflare Workers, browsers, and Node alike

Common Use Cases

• Validating incoming request bodies inside a Cloudflare Worker before forwarding them to an origin
• Enforcing config-file or API-payload shape in edge middleware where Ajv’s compiled-function approach isn’t available
• Validating structured data (webhooks, form submissions) in any restricted JS sandbox
• Runtime schema checks in code that must stay portable across Workers, browsers, and Node without polyfills

Under The Hood

Architecture The library is a small, flat module set rather than a layered architecture: dereference.ts performs a single recursive walk of the schema, resolving $id/$ref/$anchor/$recursiveRef into an absolute-URI-keyed lookup table and stamping non-enumerable __absolute_ref__/__absolute_uri__ properties onto schema nodes for later use; validate.ts then does a second recursive walk, this time over both the instance and schema together, threading an Evaluated object down through recursive calls (via prototypal inheritance for scoping) so additionalProperties/unevaluatedProperties/unevaluatedItems can see what sibling keywords already matched. validator.ts is a thin Validator class wrapping these two functions and exposing addSchema for registering more schemas into the same lookup table. There’s no plugin system or extensibility layer — behavior changes require editing the keyword if chain in validate.ts directly, so the core abstraction to preserve is the lookup table’s URI scheme and the evaluated propagation contract.

Tech Stack Pure TypeScript targeting ESNext with WebWorker/Webworker.Iterable lib types (per packages/json-schema/tsconfig.json), built with tshy (hybrid CJS/ESM TypeScript package builder) into separate dist/commonjs and dist/esm outputs, and published from an npm/Lerna-style workspace monorepo (packages/*) alongside sibling packages like @cfworker/cosmos, @cfworker/jwt, and @cfworker/sentry. No runtime dependencies at all — the only devDependencies are TypeScript, tshy, esbuild, wrangler (for Worker-environment testing), and the test stack below.

Code Quality Tests use Mocha and Chai (test/validator.spec.ts, test/index.spec.ts), plus a generated suite (suite-gen.mjs) that pulls in the official json-schema-org JSON-Schema-Test-Suite as a git dependency and runs it through test/unsupported.ts to explicitly track which conformance cases are intentionally skipped — an unusually rigorous approach to spec compliance for a hand-written (non-compiling) validator. Error handling is explicit: validate() throws directly on unsupported instance types (bigint, function, symbol) and on unresolved $refs with a diagnostic message listing known schema URIs, rather than swallowing failures. Formatting is enforced repo-wide via Prettier and a Husky pre-commit hook (lint-staged), though there’s no dedicated ESLint config visible in this package.

What Makes It Unique The defining technical choice is refusing to compile schemas to executable code at all — where Ajv’s speed advantage comes from generating and eval-ing validator functions per schema, this library walks the schema tree at validation time on every call, trading some throughput for the ability to run anywhere eval and new Function are blocked, which is exactly the case inside a Cloudflare Worker’s V8 isolate. Combined with running the full external json-schema-test-suite rather than a hand-picked subset, it targets spec fidelity in a sandboxed runtime as its primary differentiator rather than raw speed or a smaller feature set.