Tutorial

Let's explore the various features in Jsonnet, and mix some cocktails. All example codes can be edited, allowing you to experience the language interactively. If you're looking at Jsonnet for the first time, this is the right place to be. For help using the implementation, see getting started. For a detailed systematic overview of the language, check out the reference.

Syntax

Any JSON document is a valid Jsonnet program, so we'll focus on what Jsonnet adds to JSON. Let's start with an example that does not involve any computation but uses new syntax.

• Fields that happen to be valid identifiers have no quotes
• Trailing commas at the end of arrays / objects
• Comments
• String literals use " or '. The single quote is easier on the eyes but either can be used to avoid escaping the other, e.g. "Farmer's Gin" instead of 'Farmer\'s Gin'.
• Text blocks ||| allow verbatim text across multiple lines.
• Verbatim strings @'foo' and @"foo" are for single lines.

Using the interactive demo below, try modifying the strings / quantities. Try adding a "Dry Manhattan" which uses dry red vermouth and is garnished with a lemon slice.

Variables

Variables are the simplest way to avoid duplication.

• The local keyword defines a variable.
• Variables defined next to fields end with a comma (,).
• All other cases end with a semicolon (;).

Try factoring out "Simple Syrup" to the top level or to the same level as the pour variable.

References

Another way to avoid duplication is to refer to another part of the structure.

• self refers to the current object.
• $ refers to the outer-most object.
• ['foo'] looks up a field.
• .foo can be used if the field name is an identifier.
• [10] looks up an array element.
• Arbitrarily long paths are allowed.
• Array slices like arr[10:20:2] are allowed, like in Python.
• Strings can be looked up / sliced too, by unicode codepoint.

Another name for a Tom Collins is a Gin Fizz. Try adding an alias for that.

In order to refer to objects between the current and outer-most object, we use a variable to create a name for that level:

Arithmetic

Arithmetic includes numeric operations like multiplication but also various operations on other types.

• Use floating point arithmetic, bitwise ops, boolean logic.
• Strings may be concatenated with +, which implicitly converts one operand to string if needed.
• Two strings can be compared with < (unicode codepoint order).
• Objects may be combined with + where the right-hand side wins field conflicts.
• Test if a field is in an object with in.
• == is deep value equality.
• Python-compatible string formatting is available via %. When combined with ||| this can be used for templating text files.

Try dividing by zero to see what happens.

Functions

Like Python, functions have positional parameters, named parameters, and default arguments. Closures are also supported. The examples below should demonstrate the syntax. Many functions are already defined in the standard library.

Try writing a function is_even that uses the modulo operator % and returns either true or false.

And here's an example with cocktails.

Conditionals

Conditional expressions look like if b then e else e. The else branch is optional and defaults to null.

Try adding the missing Large Virgin Mojito:

Computed Field Names

Jsonnet objects can be used like a std::map or similar datastructures from regular languages.

• Recall that a field lookup can be computed with obj[e]
• The definition equivalent is {[e]: ... }
• self or object locals cannot be accessed when field names are being computed, since the object is not yet constructed.
• If a field name evaluates to null during object construction, the field is omitted. This works nicely with the default false branch of a conditional (see below).

Try adding [self.f]: 'f' to see what happens, while pondering what that could even mean!

Array and Object Comprehension

What if you want to make an array or object and you don't know how many elements / fields they will have at run-time? Jsonnet has Python-style array and object comprehension constructs to allow this.

• Any nesting of for and if can be used.
• The nest behaves like a loop nest, although the body is written first.

Below, a less contrived example. The first cocktail has equal parts of three ingredients. The second iterates over an array of records - name prefix and fruit juice.

Try adding a "Red Screwdriver" with cranberry juice.

Imports

It's possible to import both code and raw data from other files.

• The import construct is like copy/pasting Jsonnet code.
• Files designed for import by convention end with .libsonnet
• Raw JSON can be imported this way too.
• The importstr construct is for verbatim UTF-8 text.
• The importbin construct is for verbatim binary data.

Usually, imported Jsonnet content is stashed in a top-level local variable. This resembles the way other programming languages handle modules. Jsonnet libraries typically return an object, so that they can easily be extended. Neither of these conventions are enforced.

Try including the Cosmopolitan from the library.

The following example shows how to write libraries of functions. It also shows how to define a local variable in the scope of a function. Try adding the Bee's Knees from above using the utility library.

Errors

Errors can arise from the language itself (e.g. an array overrun) or thrown from Jsonnet code. Stack traces provide context for the error.

• To raise an error: error "foo"
• To assert a condition before an expression: assert "foo";
• A custom failure message: assert "foo" : "message";
• Assert fields have a property: assert self.f == 10,
• With custom failure message: assert "foo" : "message",

Try modifying the code below to trigger the assertion failures, and observe the error messages and stack traces that result.

You might wonder why the divide-by-zero is not triggered in the equal_parts function, since that code occurs before the std.length() check. Jsonnet is a lazy language, so variable initializers are not evaluated until the variable is used. Evaluation order is very hard to notice. It only becomes relevant when code throws errors, or takes a long time to execute. For more discussion of laziness, see design rationale.

Parameterize Entire Config

Jsonnet is hermetic: It always generates the same data no matter the execution environment. This is an important property but there are times when you want a few carefully chosen parameters at the top level. There are two ways to do this, with different properties.

• External variables, which are accessible anywhere in the config, or any file, using std.extVar("foo").
• Top-level arguments, where the whole config is expressed as a function.

To illustrate the differences, We'll show how the same example is expressed in each case.

External variables

The following example binds two external variables, listed below. Any Jsonnet value can be bound to an external variable, even functions.

• prefix is bound to the string "Happy Hour "
• brunch is bound to true

The values are configured when the Jsonnet virtual machine is initialized, by passing either 1) Jsonnet code (which evaluates to the value), 2) or a raw string. The latter is just a convenience, because escaping a string to pass it as Jsonnet code can be tedious. To make this concrete, the above variables can be configured with the following commandline:

jsonnet --ext-str prefix="Happy Hour " \
        --ext-code brunch=true ...
      

Top-level arguments

Alternatively the same code can be written using top-level arguments, where the whole config is written as a function. How does this differ to using external variables?

• Values must be explicitly threaded through files
• Default values can be provided
• A config with top-level arguments can also be imported as a library and called as a function with parameters passed in

Generally, top-level arguments are the safer and easier way to parameterize an entire config, because the variables are not global and it's clear what parts of the config are dependent on their environment. However, they do require more explicit threading of the values into other imported code. Here's the equivalent invocation of the Jsonnet command-line tool:

jsonnet --tla-str prefix="Happy Hour " \
        --tla-code brunch=true ...
      

Object-Orientation

In general, object-orientation makes it easy to define many variants from a single "base". Unlike Java, C++ and Python, where classes extend other classes, in Jsonnet, objects extend other objects. We have already discussed some of the raw ingredients for this, albeit in isolation:

• Objects (which we inherit from JSON)
• The object composition operator +, which merges two objects, choosing the right hand side when fields collide
• The self keyword, a reference to the current object

When these features are combined together and with the following new features, things get a lot more interesting:

• Hidden fields, defined with ::, which do not appear in generated JSON
• The super keyword is used to access fields on a base object.
• The +: field syntax for overriding deeply nested fields

The following example is contrived but demonstrates a few of the features using the classical language of object-orientation, "derived" and "base".

Let's make it more concrete by mixing deriving some cocktails that are quite similar from a template that draws out their similarities. The + operator is actually implicit in these examples. In the common case where you write foo + { ... }, i.e. the + is immediately followed by a {, then the + can be elided. Try explicitly adding the + in the 4 cases, below.

The key to making Jsonnet object-oriented is that the self keyword is "late bound". In other words, self.foo can have its meaning altered by overriding it on the right hand side of a +. This would not be the case in a simple "object merge" semantics of +, where self.foo would be fully evaluated to a concrete value before we did the +. In the above example, the left hand side of the + is templates.Sour (the + is implicit) and the right hand side is an object that overrides spirit. So in the templates.Sour definition (in templates.libsonnet) that causes the reference to drink.spirit in the ingredients list to return "Whiskey" rather than raise the error 'Must override "spirit"'.

Most of the abstraction in the above example could have been achieved with functions instead of object-orientation. Indeed, last time we spoke about sours, we used functions for that very purpose. In general, the choice of whether to use functions or object-orientation is quite a complex one, and can be driven as much by instinct as by anything else. The most obvious difference is that with object-orientation, you can override any field from the resulting object, whereas with functions you can only pass arguments for the specific parameters of the function. So, e.g., if the templates.Sour had been implemented as a function that did not parameterize the ingredients list in general way, then it would not have been possible to add that extra ingredient to form the Nor'Easter.

So far, every example has used a literal object on the right hand side of the +. This is consistent with the majority of object-oriented languages. But Jsonnet is more general in that is has mixins. A Mixin allows you to take some "overrides" and instead of just applying them to an existing object to get a new object, you can pass them around as a first class value and apply them to any object you want. The following example shows mixins being used to modify cocktails in a general way:

Thank you for completing the Jsonnet tutorial! We hope you enjoyed the accompanying beverages. At this point, you should be able to build concoctions of your own. If you want to read about the Jsonnet language in greater and more systematic detail, we recommend the language reference.