@apidevtools/json-schema-ref-parser
Version:
Parse, Resolve, and Dereference JSON Schema $ref pointers
273 lines (272 loc) • 14.4 kB
JavaScript
import $Ref from "./ref.js";
import Pointer from "./pointer.js";
import * as url from "./util/url.js";
import { getSchemaBasePath, getSchemaIdMode } from "./util/schema-resources.js";
import { TimeoutError } from "./util/errors.js";
export default dereference;
/**
* Crawls the JSON schema, finds all JSON references, and dereferences them.
* This method mutates the JSON schema object, replacing JSON references with their resolved value.
*
* @param parser
* @param options
*/
function dereference(parser, options) {
const start = Date.now();
const rootScopeBase = parser.$refs._root$Ref.dynamicIdScope
? getSchemaBasePath(parser.$refs._root$Ref.path, parser.schema, parser.$refs._root$Ref.legacyIdScope)
: parser.$refs._root$Ref.path;
// console.log('Dereferencing $ref pointers in %s', parser.$refs._root$Ref.path);
const dereferenced = crawl(parser.schema, parser.$refs._root$Ref.path, rootScopeBase, parser.$refs._root$Ref.dynamicIdScope, parser.$refs._root$Ref.legacyIdScope, "#", new Set(), new Set(), new Map(), parser.$refs, options, start, 0);
parser.$refs.circular = dereferenced.circular;
parser.schema = dereferenced.value;
}
/**
* Recursively crawls the given value, and dereferences any JSON references.
*
* @param obj - The value to crawl. If it's not an object or array, it will be ignored.
* @param path - The full path of `obj`, possibly with a JSON Pointer in the hash
* @param pathFromRoot - The path of `obj` from the schema root
* @param parents - An array of the parent objects that have already been dereferenced
* @param processedObjects - An array of all the objects that have already been processed
* @param dereferencedCache - An map of all the dereferenced objects
* @param $refs
* @param options
* @param startTime - The time when the dereferencing started
* @param depth - The current recursion depth
* @returns
*/
function crawl(obj, path, scopeBase, dynamicIdScope, legacyIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth) {
let dereferenced;
const result = {
value: obj,
circular: false,
};
checkDereferenceTimeout(startTime, options);
const derefOptions = (options.dereference || {});
const maxDepth = derefOptions.maxDepth ?? 500;
if (depth > maxDepth) {
throw new RangeError(`Maximum dereference depth (${maxDepth}) exceeded at ${pathFromRoot}. ` +
`This likely indicates an extremely deep or recursive schema. ` +
`You can increase this limit with the dereference.maxDepth option.`);
}
const isExcludedPath = derefOptions.excludedPathMatcher || (() => false);
if (derefOptions?.circular === "ignore" || !processedObjects.has(obj)) {
if (obj && typeof obj === "object" && !ArrayBuffer.isView(obj) && !isExcludedPath(pathFromRoot)) {
parents.add(obj);
processedObjects.add(obj);
const currentScopeBase = scopeBase;
if ($Ref.isAllowed$Ref(obj, options)) {
dereferenced = dereference$Ref(obj, path, currentScopeBase, dynamicIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth);
result.circular = dereferenced.circular;
result.value = dereferenced.value;
}
else {
for (const key of Object.keys(obj)) {
checkDereferenceTimeout(startTime, options);
const keyPath = Pointer.join(path, key);
const keyPathFromRoot = Pointer.join(pathFromRoot, key);
if (isExcludedPath(keyPathFromRoot)) {
continue;
}
const value = obj[key];
const childLegacyIdScope = getSchemaIdMode(value, legacyIdScope);
const childScopeBase = dynamicIdScope && value && typeof value === "object" && !ArrayBuffer.isView(value)
? getSchemaBasePath(currentScopeBase, value, childLegacyIdScope)
: currentScopeBase;
let circular;
if ($Ref.isAllowed$Ref(value, options)) {
dereferenced = dereference$Ref(value, keyPath, childScopeBase, dynamicIdScope, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth);
circular = dereferenced.circular;
// Avoid pointless mutations; breaks frozen objects to no profit
if (obj[key] !== dereferenced.value) {
// If we have properties we want to preserve from our dereferenced schema then we need
// to copy them over to our new object.
const preserved = new Map();
if (derefOptions?.preservedProperties) {
if (typeof obj[key] === "object" && !Array.isArray(obj[key])) {
derefOptions?.preservedProperties.forEach((prop) => {
if (prop in obj[key]) {
preserved.set(prop, obj[key][prop]);
}
});
}
}
// Clone the dereferenced value if cloneReferences is enabled and this is not a
// circular reference. This prevents mutations to one location from affecting others.
let assignedValue = dereferenced.value;
if (derefOptions?.cloneReferences && !circular && assignedValue && typeof assignedValue === "object") {
assignedValue = structuredClone(assignedValue);
}
obj[key] = assignedValue;
// If we have data to preserve and our dereferenced object is still an object then
// we need copy back our preserved data into our dereferenced schema.
if (derefOptions?.preservedProperties) {
if (preserved.size && typeof obj[key] === "object" && !Array.isArray(obj[key])) {
preserved.forEach((value, prop) => {
obj[key][prop] = value;
});
}
}
derefOptions?.onDereference?.(value.$ref, obj[key], obj, key);
}
}
else {
if (!parents.has(value)) {
dereferenced = crawl(value, keyPath, childScopeBase, dynamicIdScope, childLegacyIdScope, keyPathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth + 1);
circular = dereferenced.circular;
// Avoid pointless mutations; breaks frozen objects to no profit
if (obj[key] !== dereferenced.value) {
obj[key] = dereferenced.value;
}
}
else {
circular = foundCircularReference(keyPath, $refs, options);
}
}
// Set the "isCircular" flag if this or any other property is circular
result.circular = result.circular || circular;
}
}
parents.delete(obj);
}
}
return result;
}
/**
* Dereferences the given JSON Reference, and then crawls the resulting value.
*
* @param $ref - The JSON Reference to resolve
* @param path - The full path of `$ref`, possibly with a JSON Pointer in the hash
* @param pathFromRoot - The path of `$ref` from the schema root
* @param parents - An array of the parent objects that have already been dereferenced
* @param processedObjects - An array of all the objects that have already been dereferenced
* @param dereferencedCache - An map of all the dereferenced objects
* @param $refs
* @param options
* @returns
*/
function dereference$Ref($ref, path, scopeBase, dynamicIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth) {
const isExternalRef = $Ref.isExternal$Ref($ref);
const shouldResolveOnCwd = isExternalRef && options?.dereference?.externalReferenceResolution === "root";
const resolutionBase = shouldResolveOnCwd ? url.cwd() : dynamicIdScope ? scopeBase : path;
const $refPath = url.resolve(resolutionBase, $ref.$ref);
const cache = dereferencedCache.get($refPath);
if (cache) {
// If the object we found is circular we can immediately return it because it would have been
// cached with everything we need already and we don't need to re-process anything inside it.
//
// If the cached object however is _not_ circular and there are additional keys alongside our
// `$ref` pointer here, fall through and process it normally. Extended references create a new
// value, so returning the cached target (or merging it ad hoc) would make their result depend on
// which reference happened to be visited first.
if (!cache.circular) {
if (!$Ref.isExtended$Ref($ref)) {
return cache;
}
}
else {
// If both our cached value and our incoming `$ref` are the same then we can return what we
// got out of the cache, otherwise we should re-process this value. We need to do this because
// the current dereference caching mechanism doesn't take into account that `$ref` are neither
// unique or reference the same file.
//
// For example if `schema.yaml` references `definitions/child.yaml` and
// `definitions/parent.yaml` references `child.yaml` then `$ref: 'child.yaml'` may get cached
// for `definitions/child.yaml`, resulting in `schema.yaml` being having an invalid reference
// to `child.yaml`.
//
// This check is not perfect and the design of the dereference caching mechanism needs a total
// overhaul.
if (typeof cache.value === "object" && "$ref" in cache.value && "$ref" in $ref) {
if (cache.value.$ref === $ref.$ref) {
// Fire onCircular for cached circular refs so callers are notified of every occurrence
foundCircularReference(path, $refs, options);
return cache;
}
else {
// no-op - fall through to re-process (handles external ref edge case)
}
}
else {
foundCircularReference(path, $refs, options);
return cache;
}
}
}
const pointer = $refs._resolve($refPath, path, options);
if (pointer === null) {
return {
circular: false,
value: null,
};
}
// Check for circular references
const directCircular = pointer.circular;
let circular = directCircular || pointer.chainCircular || parents.has(pointer.value);
if (circular) {
foundCircularReference(path, $refs, options);
}
// Dereference the JSON reference
let dereferencedValue = $Ref.dereference($ref, pointer.value, options);
// Crawl the dereferenced value (unless it's circular)
if (!circular) {
// Pointer resolution has already applied every $id scope along the resolved path. Re-applying
// the resolved value's $id here would duplicate relative folder-changing identifiers.
const dereferencedScopeBase = pointer.$ref.dynamicIdScope ? pointer.scopeBase : pointer.$ref.path;
// Determine if the dereferenced value is circular
const dereferenced = crawl(dereferencedValue, pointer.path, dereferencedScopeBase, pointer.$ref.dynamicIdScope, pointer.legacyIdScope, pathFromRoot, parents, processedObjects, dereferencedCache, $refs, options, startTime, depth + 1);
circular = dereferenced.circular;
dereferencedValue = dereferenced.value;
}
if (circular && !directCircular && options.dereference?.circular === "ignore") {
// The user has chosen to "ignore" circular references, so don't change the value
dereferencedValue = $ref;
}
if (directCircular && dereferencedValue !== $ref) {
// The pointer is a DIRECT circular reference (i.e. it references itself).
// So replace the $ref path with the absolute path from the JSON Schema root
dereferencedValue.$ref = pathFromRoot;
}
const dereferencedObject = {
circular,
value: dereferencedValue,
};
// only cache if no extra properties than $ref
if (Object.keys($ref).length === 1) {
dereferencedCache.set($refPath, dereferencedObject);
}
return dereferencedObject;
}
/**
* Check if we've run past our allowed timeout and throw an error if we have.
*
* @param startTime - The time when the dereferencing started.
* @param options
*/
function checkDereferenceTimeout(startTime, options) {
if (options && options.timeoutMs) {
if (Date.now() - startTime > options.timeoutMs) {
throw new TimeoutError(options.timeoutMs);
}
}
}
/**
* Called when a circular reference is found.
* It sets the {@link $Refs#circular} flag, executes the options.dereference.onCircular callback,
* and throws an error if options.dereference.circular is false.
*
* @param keyPath - The JSON Reference path of the circular reference
* @param $refs
* @param options
* @returns - always returns true, to indicate that a circular reference was found
*/
function foundCircularReference(keyPath, $refs, options) {
$refs.circular = true;
options?.dereference?.onCircular?.(keyPath);
if (!options.dereference.circular) {
const error = new ReferenceError(`Circular $ref pointer found at ${keyPath}`);
throw error;
}
return true;
}