0
# JSON Schema Traverse
1

2
JSON Schema Traverse is a lightweight JavaScript utility library that provides systematic traversal of JSON Schema objects. It recursively visits each schema node, executing user-defined callback functions with rich contextual information including JSON pointers, parent relationships, and schema hierarchy.
3

4
## Package Information
5

6
- **Package Name**: json-schema-traverse
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install json-schema-traverse`
10

11
## Core Imports
12

13
```javascript
14
const traverse = require('json-schema-traverse');
15
```
16

17
For ES modules with TypeScript:
18

19
```typescript
20
import traverse from 'json-schema-traverse';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const traverse = require('json-schema-traverse');
27

28
const schema = {
29
  properties: {
30
    name: { type: 'string' },
31
    age: { type: 'integer' },
32
    address: {
33
      type: 'object',
34
      properties: {
35
        street: { type: 'string' },
36
        city: { type: 'string' }
37
      }
38
    }
39
  }
40
};
41

42
// Simple callback traversal
43
traverse(schema, (schema, jsonPtr, rootSchema) => {
44
  console.log(`Visiting: ${jsonPtr}`);
45
  console.log('Schema:', schema);
46
});
47

48
// Pre/post order traversal
49
traverse(schema, {
50
  cb: {
51
    pre: (schema, jsonPtr) => console.log(`Entering: ${jsonPtr}`),
52
    post: (schema, jsonPtr) => console.log(`Exiting: ${jsonPtr}`)
53
  }
54
});
55
```
56

57
## Capabilities
58

59
### Main Traverse Function
60

61
Traverses a JSON Schema object recursively, calling a callback function for each schema node encountered.
62

63
```javascript { .api }
64
/**
65
 * Traverses a JSON Schema object recursively
66
 * @param {SchemaObject} schema - The JSON Schema object to traverse
67
 * @param {Options} opts - Configuration options for traversal
68
 * @param {Callback} [cb] - Optional callback function (can be provided in opts)
69
 */
70
function traverse(schema, opts, cb);
71

72
/**
73
 * Legacy signature for backward compatibility
74
 * @param {SchemaObject} schema - The JSON Schema object to traverse  
75
 * @param {Callback} cb - Callback function to execute for each schema node
76
 */
77
function traverse(schema, cb);
78
```
79

80
### Callback Function Signature
81

82
The callback function receives detailed context about each visited schema node.
83

84
```javascript { .api }
85
/**
86
 * Callback function executed for each schema node during traversal
87
 * @param {SchemaObject} schema - Current schema object being visited
88
 * @param {string} jsonPtr - JSON Pointer path from root to current schema
89
 * @param {SchemaObject} rootSchema - The original root schema object
90
 * @param {string} [parentJsonPtr] - JSON Pointer path to parent schema
91
 * @param {string} [parentKeyword] - Keyword containing this schema (e.g., 'properties', 'items')
92
 * @param {SchemaObject} [parentSchema] - Parent schema object
93
 * @param {string|number} [keyIndex] - Property name or array index in parent
94
 */
95
type Callback = (
96
  schema: SchemaObject,
97
  jsonPtr: string,
98
  rootSchema: SchemaObject,
99
  parentJsonPtr?: string,
100
  parentKeyword?: string,
101
  parentSchema?: SchemaObject,
102
  keyIndex?: string | number
103
) => void;
104
```
105

106
### Pre/Post Order Callbacks
107

108
For advanced traversal patterns, callbacks can be provided as an object with separate pre and post functions.
109

110
```javascript { .api }
111
/**
112
 * Pre/post callback configuration object
113
 */
114
interface CallbackConfig {
115
  /** Called before traversing child elements */
116
  pre?: Callback;
117
  /** Called after all child elements have been traversed */
118
  post?: Callback;
119
}
120
```
121

122
### Options Configuration
123

124
Configuration object to control traversal behavior.
125

126
```javascript { .api }
127
/**
128
 * Configuration options for schema traversal
129
 */
130
interface Options {
131
  /** 
132
   * Whether to traverse objects in unknown keywords
133
   * When true, traverses schema objects in keywords not recognized by JSON Schema
134
   */
135
  allKeys?: boolean;
136
  
137
  /** Callback function or callback configuration object */
138
  cb?: Callback | CallbackConfig;
139
}
140
```
141

142
### Static Keyword Maps
143

144
The traverse function exposes static properties that define which JSON Schema keywords are processed during traversal.
145

146
```javascript { .api }
147
/** Keywords containing single schema objects */
148
traverse.keywords = {
149
  additionalItems: true,
150
  items: true,
151
  contains: true,
152
  additionalProperties: true,
153
  propertyNames: true,
154
  not: true,
155
  if: true,
156
  then: true,
157
  else: true
158
};
159

160
/** Keywords containing arrays of schema objects */  
161
traverse.arrayKeywords = {
162
  items: true,
163
  allOf: true,
164
  anyOf: true,
165
  oneOf: true
166
};
167

168
/** Keywords containing objects with schema properties */
169
traverse.propsKeywords = {
170
  $defs: true,
171
  definitions: true,
172
  properties: true,
173
  patternProperties: true,
174
  dependencies: true
175
};
176

177
/** Keywords to skip during traversal (non-schema keywords) */
178
traverse.skipKeywords = {
179
  default: true,
180
  enum: true,
181
  const: true,
182
  required: true,
183
  maximum: true,
184
  minimum: true,
185
  exclusiveMaximum: true,
186
  exclusiveMinimum: true,
187
  multipleOf: true,
188
  maxLength: true,
189
  minLength: true,
190
  pattern: true,
191
  format: true,
192
  maxItems: true,
193
  minItems: true,
194
  uniqueItems: true,
195
  maxProperties: true,
196
  minProperties: true
197
};
198
```
199

200
## Types
201

202
```javascript { .api }
203
/**
204
 * JSON Schema object interface
205
 */
206
interface SchemaObject {
207
  /** Optional schema identifier */
208
  $id?: string;
209
  /** Optional schema version */
210
  $schema?: string;
211
  /** Allow any additional properties */
212
  [x: string]: any;
213
}
214
```
215

216
## Advanced Usage Examples
217

218
### Collecting All Schema Types
219

220
```javascript
221
const traverse = require('json-schema-traverse');
222

223
const schema = {
224
  type: 'object',
225
  properties: {
226
    name: { type: 'string' },
227
    items: {
228
      type: 'array',
229
      items: { type: 'number' }
230
    }
231
  }
232
};
233

234
const types = [];
235
traverse(schema, (schema) => {
236
  if (schema.type) {
237
    types.push(schema.type);
238
  }
239
});
240

241
console.log(types); // ['object', 'string', 'array', 'number']
242
```
243

244
### Building Schema Path Map
245

246
```javascript
247
const traverse = require('json-schema-traverse');
248

249
const pathMap = new Map();
250

251
traverse(schema, (schema, jsonPtr, rootSchema, parentJsonPtr, parentKeyword) => {
252
  pathMap.set(jsonPtr, {
253
    schema,
254
    parentKeyword,
255
    parentPtr: parentJsonPtr
256
  });
257
});
258

259
// Access schema at specific path
260
const nameSchema = pathMap.get('/properties/name');
261
```
262

263
### Traversing Unknown Keywords
264

265
```javascript  
266
const schema = {
267
  customKeyword: {
268
    type: 'string',
269
    description: 'Custom schema'
270
  }
271
};
272

273
// Without allKeys, only visits root schema
274
traverse(schema, (schema, jsonPtr) => {
275
  console.log(`Visited: ${jsonPtr}`);
276
});
277
// Output: "Visited: "
278

279
// With allKeys, visits custom keyword schemas  
280
traverse(schema, { allKeys: true }, (schema, jsonPtr) => {
281
  console.log(`Visited: ${jsonPtr}`);
282
});
283
// Output: 
284
// "Visited: "
285
// "Visited: /customKeyword"
286
```
287

288
### Error Handling
289

290
The traverse function expects well-formed schema objects. It will silently skip:
291
- Non-object values (except at the root level)
292
- Array values (unless they are arrays of schemas in array keywords)
293
- Schema references ($ref) are passed through as-is without resolution