Overlay

The responsibility of the Overlay is the resolutions of References. The resulting layer thus replaces all references with the referenced object. This is best illustrated with an example.

A reference in JSON could look like this:

{
    "example": {
        "title": "Reference Resolution Example",
        "text": "This is an example of a reference resolution."
    },
    "reference": { "$ref": "#/example" }
}

After applying the Overlay, the reference is resolved and the resulting Structure feels like this:

{
    "example": {
        "title": "Reference Resolution Example",
        "text": "This is an example of a reference resolution."
    },
    "reference": {
        "title": "Reference Resolution Example",
        "text": "This is an example of a reference resolution."
    }
}

Note, that it only __feels__ like this. In actuality there is no duplication of the object. The reference is resolved and replaced with a Python reference, thus changes are always visible in both places.

Since this feature is implemented in a Layer it is non-destructive and the original data is not modified. This allows us to “recover” all used JSON references when saving the data.