The easiest way to execute some Jsonnet code is invoking an interpreter via the commandline as so:
jsonnet -e <code>
Or a filename:
jsonnet <file>
This dumps the JSON on stdout. The tool is self-documenting with --help. You can experiment with the Jsonnet files in the examples/ directory of the C++ Github repo.
To get Jsonnet, you can build it from either the C++ or the Go repositories. See below for the differences between them. Each repo has a README.md containing build instructions.
Evaluating a file.
$ jsonnet landingpage.jsonnet
{
"person1": {
"name": "Alice",
"welcome": "Hello Alice!"
},
"person2": {
"name": "Bob",
"welcome": "Hello Bob!"
}
}
Evaluating a snippet.
$ jsonnet -e '{ x: 1 , y: self.x + 1 } { x: 10 }'
{
"x": 10,
"y": 11
}
The Jsonnet commandline tool has a special mode for generating multiple JSON files from a single Jsonnet file. This can be useful if you want to avoid writing lots of small Jsonnet files, or if you want to take advantage of cross-references and interdependencies between the files. The idea is to create a single JSON structure, the top level of which defines the various files:
// multiple_output.jsonnet
{
"a.json": {
x: 1,
y: $["b.json"].y,
},
"b.json": {
x: $["a.json"].x,
y: 2,
},
}
When executed using jsonnet -m <dir>, this will write the generated JSON to files a.json and b.json in the given directory, instead of the whole thing being written to stdout. In order to integrate nicely with build tools like make, the files are not touched if they already contain the given content. To stdout is printed the list of target files, one per line. This makes it easy to drive other tools that operate on the JSON files, e.g. via xarg.
$ jsonnet -m . multiple_output.jsonnet
a.json
b.json
$ cat a.json
{
"x": 1,
"y": 2
}
$ cat b.json
{
"x": 1,
"y": 2
}
Unlike JSON, YAML can represent several objects in the same file, separated by ---. The Jsonnet commandline parameter -y causes the tool to expect the Jsonnet execution to yield an array. Config designed for this mode typically looks like this: It then outputs that array as a sequence of JSON documents separated by ---, which any YAML parser will interpret as a YAML stream.
// yaml_stream.jsonnet
local
a = {
x: 1,
y: b.y,
},
b = {
x: a.x,
y: 2,
};
[a, b]
When executed using -y, this will output that array as a sequence of JSON documents separated by --- and terminated with .... Any YAML parser should interpret this as a YAML stream (people have reported broken parsers, so try it out first).
$ jsonnet -y yaml_stream.jsonnet
---
{
"x": 1,
"y": 2
}
---
{
"x": 1,
"y": 2
}
...
There are two feature-compatible implementations of the Jsonnet interpreter. The first one we built was the C++ interpreter, and it is still the most mature / widely used. The new Go implementation has the benefits of simpler code (due to leveraging goroutines and the GO garbage collector). Our long term plan is to migrate everyone to the Go implementation eventually. Both implementations are tested against the same test suite (which is quite thorough). Please report any deviations. The performance of the C++ implementation is currently a bit better, but for most people this should not be a factor and we're intending to address it over time, anyway.
Another factor is that the formatter is currently only implemented in the C++ repo, and the linter is only implemented in the Go repo.
The C++ implementation can be compiled with emscripten to produce a JavaScript implementation of Jsonnet. This is how we implement the interactive demos on this site. A native implementation of Jsonnet in JavaScript would probably be faster. In fact, a GopherJs transpile of the Go Jsonnet implementation may work better as well. However, the emscripten version is easy to build, and is sufficient for many purposes.
To compile it, first install emscripten and ensure em++ and emcc are in your path. Then make libjsonnet.js.
An unofficial nodejs package of Jsonnet is also available.