Registry / devops / json-schema-walker

json-schema-walker

library3.3.0jsnpmunverified

json-schema-walker v3.3.0 is a TypeScript library that traverses all schema objects in a JSON Schema document and invokes callbacks before/after visiting subschemas. It supports both async (with $ref resolution) and sync (without $ref) traversal, cloning, and multiple JSON Schema drafts (via vocabularies). Released under MIT, it is loosely based on CloudFlare's json-schema-tools. The library ships TypeScript types and requires Node >=17. Key differentiators include built-in $ref dereferencing with circular reference handling and a simple walker pattern.

devops testing

npm install json-schema-walker

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-WALKER

json-schema-walker

devopsjavascriptv3.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Walker

✓ import { Walker } from 'json-schema-walker'

✗ const Walker = require('json-schema-walker')

CommonJS require will not work for named export. Use ESM import.

WalkerOptions

✓ import type { WalkerOptions } from 'json-schema-walker'

TypeScript type-only import for options.

vocabularies

✓ import { Walker } from 'json-schema-walker'; // Access via instance: walker.vocabularies.DRAFT_07

✗ import { vocabularies } from 'json-schema-walker'

vocabularies is not directly exported; it's accessed from a Walker instance.

Demonstrates async walk: load a JSON Schema, apply a callback that adds a flag to every schema object, then output the transformed schema.

import { Walker } from 'json-schema-walker'; const schema = { type: 'object', properties: { name: { type: 'string' }, age: { type: 'number' } } }; const walker = new Walker(); await walker.loadSchema(schema, { cloneSchema: true, dereference: false }); const convertSchema = (s: any): any => { s._visited = true; return s; }; await walker.walk(convertSchema, walker.vocabularies.DRAFT_07); console.log(walker.rootSchema); // Output includes _visited: true on all schema objects.

Debug

Known issues

breakingVersion 3.0.0 dropped CommonJS support. Package is now ESM-only.

fix

Use ES module import syntax (import { ... } from ...) instead of require().

affects: >=3.0.0

breakingWalker constructor signature changed in v3: no longer accepts parameters.

fix

Create Walker with no arguments: new Walker().

affects: >=3.0.0

deprecatedThe 'walk' method now requires a second argument (vocabulary). Omitting it is deprecated.

fix

Provide a vocabulary, e.g., walker.vocabularies.DRAFT_07.

affects: >=3.0.0 <3.3.0

gotchaSynchronous methods loadSchemaSync and walkSync do not resolve $ref. They will silently leave $ref unresolved.

fix

Use async loadSchema/walk if your schema contains $ref.

affects: >=3.0.0

gotchacloneSchema option defaults to false. If you don't clone, the original schema object is mutated.

fix

Set cloneSchema: true unless you intend to mutate the original.

affects: >=3.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported.

The package is ESM-only since v3.

fix

Use import() or dynamic import. Alternatively, add "type": "module" to your package.json.

TypeError: walker.walk is not a function

You are using the synchronous method incorrectly or imported the wrong symbol.

fix

Ensure you created a Walker instance: const w = new Walker(); await w.walk(...);

ReferenceError: vocabularies is not defined

vocabularies is not directly exported; it's an instance property.

fix

Use walker.vocabularies (e.g., walker.vocabularies.DRAFT_07).

Upgrade

Version history

3.3.0latest on npm

Audit

Dependencies

json-schema-ref-parseroptionalused for $ref dereferencing in async walking

lodash.clonedeepoptionalused for schema cloning when cloneSchema option is true

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/jonluca/json-schema-walker ↗

packagejson-schema-walker ↗

homepagehttps://github.com/jonluca/json-schema-walker ↗