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
}
Sometimes it is useful to generate output that is not in JSON format. You can do this by writing Jsonnet code which evaluates to a string containing whatever your desired format is. When executed with jsonnet -S or jsonnet --string jsonnet will manifest the string result as plain text rather than a JSON-formatted string.
// ini_output.jsonnet
std.manifestIni({
sections: {
main: {
host: "127.0.0.1",
port: "9000",
},
database: {
path: "/var/data",
},
},
})
When executed using jsonnet -S ini_output.jsonnet, this will output the generated INI formatted text directly.
$ jsonnet -S ini_output.jsonnet [database] path = /var/data [main] host = 127.0.0.1 port = 9000
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 multiple implementations of the Jsonnet interpreter. The original interpreter was written in C++. However, there is a newer implementation written in Go, and this generally has better performance, as well as the benefits of being written in a memory safe language. The Go implementation also includes a linter, which is not available in the C++ implementation. Both the C++ and Go versions are tested against the same test suite.
Beyond the 'official' C++ and Go implementations, there are also various implementations written independently by other people, such as Rust and Haskell implementations, along with language bindings / wrappers for some other languages (such as PHP, and JavaScript). These are listed on the Bindings page.