Registry / testing / json-schema-cycles

json-schema-cycles

library3.0.0jsnpmunverified

Analyze cyclic (recursive) dependencies in JSON Schema definitions. Version 3.0.0 is a pure ESM package requiring Node.js >=14.13.1 or >=16.0.0. Unlike alternatives, it offers both a full analysis (analyzeTypes) that returns detailed cycle information including entrypoints and a fast analysis (analyzeTypesFast) for large schemas where memory or performance is a concern. Only handles local definitions; external $ref must be resolved beforehand.

testing

npm install json-schema-cycles

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-CYCLES

json-schema-cycles

testingjavascriptv3.0.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.

analyzeTypes

✓ import { analyzeTypes } from 'json-schema-cycles'

✗ const { analyzeTypes } = require('json-schema-cycles')

ESM-only package; CommonJS require() will fail. Since v2.

analyzeTypesFast

✓ import { analyzeTypesFast } from 'json-schema-cycles'

✗ import analyzeTypesFast from 'json-schema-cycles'

Default import does not exist; must use named import.

TypeAnalysisFullResult

✓ import { TypeAnalysisFullResult } from 'json-schema-cycles'

✗ import { TypeAnalysisFullResult } from 'graph-cycles'

Type is re-exported from graph-cycles but should be imported from json-schema-cycles for convenience.

Shows how to use both analyzeTypes and analyzeTypesFast with a simple cyclic schema, printing cycles and graph.

import { analyzeTypes, analyzeTypesFast } from 'json-schema-cycles'; const schema = { definitions: { A: { $ref: '#/definitions/B' }, B: { $ref: '#/definitions/A' }, C: { type: 'object', properties: { d: { $ref: '#/definitions/D' } } }, D: { type: 'string' }, } }; // Full analysis const result = analyzeTypes(schema); console.log(result.cycles); // [["A", "B"]] console.log(result.entrypoints); // Fast analysis (safer for large schemas) const fastResult = analyzeTypesFast(schema); console.log(fastResult.cyclic); // Set {"A", "B"} console.log(result.graph); // [["A",["B"]],["B",["A"]],["C",["D"]],["D",[]]]

Debug

Known issues

breakingPackage is pure ESM from v2. Must use import syntax; require() throws ERR_REQUIRE_ESM.

fix

Switch to import statements or use dynamic import() if in CommonJS environment.

affects: >=2.0.0

gotchaanalyzeTypes can crash the process or run out of memory on extremely complex schemas with massive cyclicity.

fix

Prefer analyzeTypesFast for large or deeply recursive schemas.

affects: all

gotchaExternal $refs (e.g., to other files) are not resolved. The schema must contain all definitions locally or be pre-processed with a ref-parser.

fix

Use a JSON Schema ref parser like @apidevtools/json-schema-ref-parser to bundle references into a single schema before passing to json-schema-cycles.

affects: all

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module /path/to/node_modules/json-schema-cycles/dist/index.js from /path/to/project/app.js not supported.

Package is pure ESM since v2, but CommonJS require() is used.

fix

Change to import { analyzeTypes } from 'json-schema-cycles' or use dynamic import() in a CommonJS file.

TypeError: json_schema_cycles_1.analyzeTypes is not a function

Default import used instead of named import (e.g., import jsonSchemaCycles from 'json-schema-cycles').

fix

Use import { analyzeTypes } from 'json-schema-cycles'.

RangeError: Maximum call stack size exceeded

Extremely recursive schema passed to analyzeTypes; it uses deep recursion for full analysis.

fix

Switch to analyzeTypesFast which uses iterative approach and is safer.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

graph-cyclesrequiredCore dependency for cycle detection algorithm; the analysis results are based on graph-cycles types (FullAnalysisResult, FastAnalysisResult).

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/grantila/json-schema-cycles ↗

packagejson-schema-cycles ↗

homepagehttps://github.com/grantila/json-schema-cycles#readme ↗