Design Principles
JSON++ was designed around three principles.
Principle 1 — Completeness and Compatibility
Any JSON can be represented as JSON++:
An important property of JSON++ is that it does not restrict the space of configurations that can be produced.
The jq++ evaluation function maps JSON++ documents to ordinary JSON documents.
For any valid JSON document J, there exists a JSON++ document X such that jq++(X) = J.
In other words, the evaluation function is surjective onto JSON.
This property ensures that JSON++ can generate any configuration expected by downstream systems, allowing jq++ to be introduced as a pre-processing step without reducing expressiveness.
In practice, this means that adopting JSON++ never forces downstream tools to change their expectations about the resulting configuration structure.[1]
All JSON++ documents are valid JSON: Moreover, JSON++ documents remain valid JSON, which allows existing parsers and tooling to process them without modification.
Principle 2 — JSON Data-Model Compatibility
JSON++ operates at the level of the JSON data model rather than a specific surface syntax. Because many configuration languages such as YAML, HCL, and TOML are routinely translated into JSON during processing, the same reuse mechanisms can be applied to configurations written in those formats. In practice this means that JSON++ concepts naturally extend to JSON-compatible representations such as YAML without requiring changes to the authoring language.
This also implies that the same extension concept naturally applies to other JSON-compatible formats such as YAML.
Principle 3 — Declarative Structural Reuse
JSON++ introduces explicit constructs for expressing structural reuse.
-
Structural composition constructs (
$extends,$includes) let configurations combine documents directly, describing relationships in the data structure itself rather than through external tooling. -
Expression evaluation (
eval:) lets configurations compute values dynamically from the composed result.