Jsonnet — Data Templating Language for Configuration

Introduction

Jsonnet is a configuration language designed by Google to tame the complexity of large-scale JSON and YAML configurations. It is a pure functional language that evaluates to JSON, letting you use variables, arithmetic, conditionals, array comprehensions, imports, and functions to generate configurations that would otherwise require massive duplication. Jsonnet is widely used for Kubernetes manifests, Grafana dashboards, and Terraform configurations.

What Jsonnet Does

• Extends JSON with variables, functions, conditionals, and imports to reduce configuration duplication
• Evaluates to standard JSON or YAML output that any existing tool can consume
• Supports code reuse through imports, libraries, and mixins for large configuration sets
• Provides a standard library with string manipulation, math, array, and object functions
• Enables parameterized templates that generate environment-specific configs from shared definitions

Architecture Overview

Jsonnet is a hermetic, purely functional language. The evaluator parses .jsonnet files into an AST, performs lazy evaluation with memoization, and outputs JSON. There are two main implementations: the original C++ jsonnet binary and go-jsonnet, a Go reimplementation with better error messages and library embedding support. External variables and top-level arguments allow injecting values at evaluation time without modifying source files. The jsonnet-bundler tool manages third-party library dependencies.

Self-Hosting & Configuration

• Install via Homebrew (brew install jsonnet), Go (go install github.com/google/go-jsonnet/cmd/jsonnet@latest), or pre-built binaries
• Write .jsonnet files using JSON syntax extended with Jsonnet features
• Use import statements to split configuration across multiple files and libraries
• Install shared libraries with jsonnet-bundler (jb install github.com/grafana/jsonnet-libs)
• Integrate into CI by running jsonnet to generate configs and piping output to kubectl apply or terraform

Key Features

• Pure functional evaluation guarantees deterministic output with no side effects
• Deep merging of objects with the + operator simplifies layering base and override configs
• Array and object comprehensions eliminate repetitive boilerplate in config files
• Late binding with self and super keywords enables mixin-style composition patterns
• Output formats include JSON, multi-file JSON, YAML, and raw string mode

Comparison with Similar Tools

• CUE — Type-safe configuration language with validation built in; more complex than Jsonnet's template-first approach
• Helm — Kubernetes package manager using Go templates; Jsonnet offers a full programming language instead of string templating
• Kustomize — Overlay-based Kubernetes config tool; Jsonnet provides more programmatic control through functions and imports
• Dhall — Typed configuration language with strong guarantees; Jsonnet is simpler to learn for teams familiar with JSON
• Starlark — Python dialect used in Bazel; domain-specific while Jsonnet targets general configuration generation

FAQ

Q: Is Jsonnet only for Kubernetes? A: No. Jsonnet generates standard JSON and can be used for any system that reads JSON or YAML, including Grafana, Terraform, CI configs, and more.

Q: What is the difference between jsonnet and go-jsonnet? A: go-jsonnet is a Go reimplementation with compatible output, better error messages, and easy embedding as a Go library. Both produce identical JSON output.

Q: Can I validate Jsonnet output against a schema? A: Jsonnet itself does not validate output. You can pipe the generated JSON into schema validators like ajv or use CUE for typed configuration.

Q: How do I manage Jsonnet library dependencies? A: Use jsonnet-bundler (jb) to install and version third-party Jsonnet libraries from Git repositories.

Sources

• https://github.com/google/jsonnet
• https://jsonnet.org