The data templating language
Jsonnet

Commandline Tool

The commandline tool "jsonnet" will evaluate Jsonnet and emit JSON on stdout. It can evaluate snippets of code, or files (by filename). It is actually a commandline wrapper around the C API, a convenient way to evaluate Jsonnet code from shell scripts, build tools, or languages that do not yet have a library binding.

Building

The commandline tool will be built by simply invoking 'make', as it is the sole default target. It can be built explicitly with 'make jsonnet'.

Usage

The tool is self-documenting:

Usage:
Usage:
jsonnet {<option>} [<filename>]
where <filename> defaults to - (stdin)
and <option> can be:
  -h / --help             This message
  -e / --exec             Treat filename as code (requires explicit filename)
  -J / --jpath <dir>      Specify an additional library search dir
  -V / --var <var>=<val>  Specify an 'external' var to the given value
  -E / --env <var>        Bring in an environment var as an 'external' var
  -m / --multi            Write multiple files, list files on stdout
  -s / --max-stack <n>    Number of allowed stack frames
  -t / --max-trace <n>    Max length of stack trace before cropping
  --gc-min-objects <n>    Do not run garbage collector until this many
  --gc-growth-trigger <n> Run garbage collector after this amount of object growth
  --debug-ast             Unparse the parsed AST without executing it

  --version               Print version
Multichar options are expanded e.g. -abc becomes -a -b -c.
The -- option suppresses option processing for subsequent arguments.
Note that since jsonnet programs can begin with -, it is advised to
use -- with -e if the program is unknown, e.g. jsonnet -e -- "$CODE".

Example

Evaluating a file.

~/jsonnet/examples$ jsonnet landingpage.jsonnet
{
   "person1": {
      "name": "Alice",
      "welcome": "Hello Alice!"
   },
   "person2": {
      "name": "Bob",
      "welcome": "Hello Bob!"
   }
}

Evaluating a snippet.

~/jsonnet/examples$ jsonnet -e '{ x: 1 , y: self.x + 1 } { x: 10 }'
{
   "x": 10,
   "y": 11
}

Multiple file output

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. The following example shows how to do it:

// multiple_output.jsonnet
{
    "a.json": {
        x: 1,
        y: $["b.json"].y,
    },
    "b.json": {
        x: $["a.json"].x,
        y: 2,
    },
}

When executed using jsonnet -m, this will write the generated JSON to files a.json and b.json instead of to stdout. In order to integrate nicely with build tools like make, the files are not touched if they already contain the content that would be written to them. To stdout is printed the list of files (either written or already containing the right data). This makes it easy to drive other tools that operate on the JSON files.

$ jsonnet -m multiple_output.jsonnet
a.json
b.json
$ cat a.json 
{
   "x": 1,
   "y": 2
}
$ cat b.json 
{
   "x": 1,
   "y": 2
}