Jsonnet

Jsonnet is a data templating language: a small, purely functional language whose job is to generate configuration data rather than to run programs. You write Jsonnet, and the Jsonnet interpreter evaluates it down to plain JSON — or, via its standard library, to YAML, INI, and other formats. Its central design conceit is elegant: Jsonnet is a strict superset of JSON, so every valid JSON document is already a valid Jsonnet program that simply emits itself. On top of that foundation it layers the features JSON conspicuously lacks — variables, functions, conditionals, arithmetic, string formatting, imports, and object-oriented inheritance — turning repetitive, copy-pasted configuration into concise, parameterized, reusable code.

The name is a portmanteau of JSON and sonnet, pronounced “jay-sonnet.”

History & Origins

Jsonnet was created by Dave Cunningham as a Google 20% project, beginning in early 2014, and was published publicly on GitHub on 6 August 2014. Google later gave it a wider introduction in an April 2015 post on the Google Open Source Blog, “Jsonnet: a more elegant language for composing JSON.” Although the code is owned by Google, the project has always been clear that Jsonnet is not an official Google product — it is open-source code that happens to live under Google’s umbrella.

The language did not appear from nowhere. Its design is a near-direct descendant of BCL, the Borg Configuration Language — one of Google’s most heavily used internal languages for describing how jobs run on its Borg cluster manager. BCL grew out of the reality that configuring “some of the world’s most complex IT systems” by hand, in flat data formats, does not scale: the same values get repeated thousands of times, small changes ripple unpredictably, and there is no good way to factor out shared structure. Jsonnet takes the hard-won lessons of BCL (and Google’s broader configuration-language tradition, including GCL) and repackages them as an open, JSON-compatible language anyone can use.

Design Philosophy

Jsonnet is built on a few deliberate principles:

• A superset of JSON. Any JSON is valid Jsonnet. This means adoption can be incremental — you can take an existing JSON file and start adding variables and functions to it without a rewrite.
• Side-effect free and hermetic. Evaluating a Jsonnet program has no side effects: no file writes, no network calls, no clocks. The same inputs always produce the same output, which makes configuration reproducible and easy to reason about.
• Lazy evaluation. Values are computed only when needed. This allows objects to reference one another freely and supports powerful inheritance patterns without infinite loops or ordering headaches.
• Object orientation for data. Jsonnet treats objects as the unit of composition. Objects can inherit from and override one another, so a base configuration can be specialized for dev, staging, and prod without duplication.
• Generate, don’t execute. Jsonnet is not a general-purpose programming language for building applications; it is a focused tool whose only output is data. That narrow scope is the point — it keeps configuration declarative and analyzable.

By slotting new syntax into the gaps JSON leaves open, Jsonnet adds these capabilities without breaking compatibility.

Key Features

Variables, functions, and references

Local bindings and functions eliminate repetition, and self / $ let fields reference other fields:

// person.jsonnet
local Person(name='Alice') = {
  name: name,
  welcome: 'Hello ' + name + '!',
};
{
  person1: Person(),
  person2: Person('Bob'),
}

Evaluating this produces JSON with two fully-formed person objects.

Object inheritance and overriding

Objects compose with the + operator, and a derived object can override or extend the base. This is the feature that makes Jsonnet so effective for environment-specific configuration:

local base = {
  replicas: 1,
  image: 'myapp:latest',
};
{
  dev: base,
  prod: base + { replicas: 5 },
}

Conditionals, comprehensions, and arithmetic

Jsonnet supports if/then/else, array and object comprehensions, and ordinary arithmetic and string operations — enough expressiveness to compute configuration rather than spell it out by hand.

A standard library and multiple output formats

The built-in std library provides functions for string manipulation, math, sorting, and crucially for manifesting data into different formats — for example std.manifestYamlDoc() for YAML and std.manifestIni() for INI files — so a single Jsonnet source can target many downstream systems.

Imports and modularity

Files can import other Jsonnet files (and importstr raw text), enabling reusable libraries — the mechanism behind ecosystem libraries like Grafonnet.

Tooling

The project ships a reformatter and linter, and there are editor and IDE integrations, reflecting Jsonnet’s intent to be used at scale on large configuration codebases.

Evolution

Jsonnet’s evolution has happened along two axes: the language and standard library on one hand, and its implementations on the other.

The reference and Go implementations share version numbers and a common test suite, progressing through releases such as v0.20.0 (around 2021), v0.21.0 (around May 2023), and v0.22.0 (around 2024), which added conveniences like numeric digit separators (1_500_000) and new standard-library functions. Because release dates differ slightly between the C++ and Go repositories, specific version dates are best confirmed against each project’s release page.

Performance was an early pain point: the C++ implementation could be slow on large configurations, which is precisely the motivation Databricks gave for sjsonnet. In a 2018 write-up Databricks reported substantial speedups on their own Jsonnet workloads — driven largely by caching the results of lazy evaluations so repeated references are not recomputed — though as with any such figure the gains depend heavily on the specific codebase and access patterns being measured.

Current Relevance

Jsonnet found its strongest home in the cloud-native world. As Kubernetes pushed teams toward managing large volumes of YAML, Jsonnet offered a way to generate that YAML programmatically instead of copy-pasting it. The early tool ksonnet (from Heptio) pioneered this approach; after it was discontinued, Grafana Tanka took up the mantle and remains a widely used Jsonnet-based tool for Kubernetes, extending the language with native functions to pull in Helm charts and Kustomize manifests. Grafonnet, also from Grafana, lets teams define Grafana dashboards as Jsonnet code.

Jsonnet sits within a competitive field of modern configuration languages — alongside Dhall, CUE, and KCL — each making different trade-offs between expressiveness, type safety, and simplicity. Jsonnet’s distinguishing bet remains its strict JSON-superset compatibility and its inheritance-based object model. Development continues at a measured pace across the reference, Go, and Scala implementations.

Why It Matters

Jsonnet matters because it took an idea proven inside one of the world’s largest engineering organizations — that configuration should be code, factored and composed like any other software — and made it openly available in a form that anyone already using JSON could adopt incrementally. It helped popularize the “data templating” category and showed that a deliberately narrow, side-effect-free language could solve the very real problem of configuration sprawl without becoming a general-purpose programming language. For the wave of infrastructure-as-code and Kubernetes tooling that followed, Jsonnet was both an influence and, through tools like Tanka and Grafonnet, a working foundation.

Sources

• Jsonnet — official site
• Jsonnet: a more elegant language for composing JSON — Google Open Source Blog (April 2015)
• google/jsonnet — GitHub
• google/go-jsonnet — GitHub
• databricks/sjsonnet — GitHub and Writing a Faster Jsonnet Compiler — Databricks (2018)
• Grafana Tanka and Grafonnet