The League of Extraordinary Packages

Our Packages:

Presented by The League of Extraordinary Packages

Getting Started



Circular References

This package fully supports recursive references. Consider the following example 1:

  "person": {
    "properties": {
        "name": {
          "type": "string"
        "spouse": {
          "type": {
            "$ref": "#/person"        // circular reference


If the dereferencer attempted to fully resolve this reference, the dereferencer would continue looping infintely. Instead of resolving references immediately, the $ref is replaced with a reference object.

The reference object is resolved lazily by the validator. The validator will stop resolving once it runs out of data to validate or the maximum depth has been exceeded.


Because a $ref may be circular, attempting to inline the $ref would be impossible.

When serialized, all references are transformed into the original { "$ref": "#/some/reference" } format instead of attempting to inline them.

  1. The example is from the json-schema-ref-parser docs.