Registry / testing / oas-schema-walker

oas-schema-walker

library1.1.5jsnpmunverified

A lightweight utility (v1.1.5, stable, infrequent releases) for recursively walking OpenAPI 3.0 schema objects and applying a callback to each subschema. Unlike general JSON-schema traversal libraries, it is optimized for OAS 3 schemas, handling only local references and providing a persistent state object for tracking recursion depth and visited nodes. Key differentiators: minimal dependencies, no external schema resolution, and a simple callback-based API for schema transformation or validation.

testing

npm install oas-schema-walker

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · OAS-SCHEMA-WALKER

oas-schema-walker

testingjavascriptv1.1.5

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.

walkSchema

✓ import { walkSchema } from 'oas-schema-walker'

✗ const { walkSchema } = require('oas-schema-walker')

ESM-only across all versions; CommonJS require is unsupported.

getDefaultState

✓ import { getDefaultState } from 'oas-schema-walker'

✗ import getDefaultState from 'oas-schema-walker'

Named export, not default.

walkSchema + getDefaultState

✓ import { walkSchema, getDefaultState } from 'oas-schema-walker'

Both commonly imported together.

Demonstrates walking a nested OAS 3 schema object with a callback that modifies each schema.

import { walkSchema, getDefaultState } from 'oas-schema-walker'; const schema = { type: 'object', properties: { name: { type: 'string' }, address: { type: 'object', properties: { street: { type: 'string' } } } } }; const state = getDefaultState(); walkSchema(schema, state, (schema, parent, state) => { if (schema.type === 'string') { schema.minLength = 1; // add a constraint } console.log('Visited:', schema.type); });

Debug

Known issues

gotchawalkSchema does not resolve $ref references; only local (no external) references are followed. For external refs, you must pre-resolve.

fix

Use a resolver like swagger-parser before walking, or handle $ref yourself.

affects: >=1.0.0

gotchaThe callback's parent parameter may be undefined for the root schema; always guard against undefined.

fix

Check if parent is an object before accessing properties: if (parent && parent.properties) { ... }

affects: >=1.0.0

deprecatedNone currently deprecated; API stable across versions.

fix

N/A

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: walkSchema is not a function

Incorrect import (default import instead of named) or using CommonJS require.

fix

Use: import { walkSchema } from 'oas-schema-walker'

Cannot read properties of undefined (reading 'type')

Callback accessing parent properties without checking undefined.

fix

Guard parent access: if (!parent) return;

Maximum call stack size exceeded

Circular $ref references without state tracking; walkSchema uses state to avoid infinite recursion, but if state is not reused properly.

fix

Always call getDefaultState() for a fresh walk; do not reuse state across separate walks on circular schemas.

Upgrade

Version history

1.1.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/Mermade/oas-kit ↗

packageoas-schema-walker ↗

homepagehttps://github.com/Mermade/oas-kit#readme ↗