JSON parser

The JSON parser is built on top of Python’s json module and adds 2 additional features:

• JSON references

• JSON imports

JSON References

References point to another JSON dictionary somewhere in the same or another document and copy over that dictionary into the parent of the reference statement:

{
  "template": {
    "A": "value",
    "B": "value"
  },
  "copy": {
    "$ref": "#/template"
  }
}

Will be parsed into:

{
  "template": {
    "A": "value",
    "B": "value"
  },
  "copy": {
    "A": "value",
    "B": "value"
  }
}

Note

Imported keys will not override keys that are already present. This way you can specify local data to customize what you import. If both keys are dictionaries, they are merged; with again priority for the local data.

Reference statement

The reference statement consists of the $ref key and a 2-part value. The first part of the statement before the # is the document-clause and the second part the reference-clause. If the # is omitted the entire value is considered a reference-clause.

The document clause can be empty or omitted for same document references. When a document clause is given it can be an absolute or relative path to another JSON document.

The reference clause must be a JSON path, either absolute or relative to a JSON dictionary. JSON paths use the / to traverse a JSON document:

{
  "walk": {
    "down": {
      "the": {
        "path": {}
      }
    }
  }
}

In this document the deepest JSON path is /walk/down/the/path.

Warning

Pay attention to the initial / of the reference clause! Without it, you’re making a reference relative to the current position. With an initial / you make a reference absolute to the root of the document.

JSON Imports

Imports are the bigger cousin of the reference. They can import multiple dictionaries from a common parent at the same time as siblings:

{
  "target": {
    "A": "value",
    "B": "value",
    "C": "value"
  },
  "parent": {
    "D": "value",
    "$import": {
      "ref": "#/target",
      "values": ["A", "C"]
    }
  }
}

Will be parsed into:

{
  "target": {
    "A": "value",
    "B": "value",
    "C": "value"
  },
  "parent": {
    "A": "value",
    "C": "value"
  }
}

Note

If you don’t specify any values all nodes will be imported.

Note

The same merging rules apply as to the reference.

The import statement

The import statement consists of the $import key and a dictionary with 2 keys:

• The ref key (note there’s no $) which will be treated as a reference statement. And used to point at the import’s reference target.

• The values key which lists which keys to import from the reference target.