Jsonnet: a more elegant language for composing JSON

Monday, April 20, 2015

A few months ago, we quietly released Jsonnet: a simple yet rich configuration language (i.e., a programming language for specifying data). Many systems can be configured with JSON, but writing it by hand is troublesome. Jsonnet is packed with useful data-specification features that expand into JSON for other systems to act upon. Below is a trivial example of such expansion:

// Jsonnet Example
   person1: {
       name: "Alice",
       welcome: "Hello " + + "!",
   person2: self.person1 { name: "Bob" },
  "person1": {
     "name": "Alice",
     "welcome": "Hello Alice!"
  "person2": {
     "name": "Bob",
     "welcome": "Hello Bob!"
Jsonnet doesn’t just generate JSON: Jsonnet is also an extension of JSON. By adding new constructs between the gaps of existing JSON syntax, Jsonnet adds useful features without breaking backwards compatibility. Any valid JSON is also a valid Jsonnet program that simply emits that JSON unchanged, and existing systems that consume JSON (or its cousin YAML) can be easily modified to accept data in the full Jsonnet language. As such, Jsonnet is an example of a templating language, but one specifically designed for JSON data and less error-prone than other techniques.
“Jsonnet” is a portmanteau of JSON and sonnet. We chose that name to convey that data expressed in Jsonnet is easier to write and maintain because it is more elegant and concise, like a poem. This is not just due to syntactic niceties like comments and permissive quotes/commas, but because Jsonnet has all the modern multi-paradigm programming language conveniences needed to manage complexity. One key benefit is the ability to use Jsonnet's mixin and import features to write modular configuration template libraries, allowing the creation of domain-specific configuration languages for particular applications.
Most configuration languages are created ad-hoc for the needs of a given application, accruing features over time and becoming unwieldy. From day one, Jsonnet was designed as a coherent programming language, benefitting from both academic techniques and our experience implementing production languages. Unlike most configuration languages, Jsonnet has a full operational semantics, ensuring matching behavior from third party implementations as well as mathematical analysis. It is a very small and carefully chosen extension to JSON that can express both object-oriented and declarative styles. More importantly, unlike regular programming languages, Jsonnet is hermetic:  Its evaluation is independent of any implicit environmental factors, ensuring that high level configuration will resolve to the same thing every time.
Jsonnet is open source. It’s currently available as a library with C and Python bindings, and also as a command line utility. A real-world example configuration can be found on the website, where 217 lines (9.7kB) of Jsonnet expand into 740 lines (25kB) of configuration for other tools. Learn more about Jsonnet by reading the tutorial and experimenting with our javascript demo!

by Dave Cunningham, New York Technical Infrastructure team