dhall-to-json: Compile Dhall Config to JSON
dhall-to-json evaluates a Dhall expression and emits the equivalent JSON after full type checking.
Where dhall-to-yaml targets Kubernetes and Helm-style YAML, dhall-to-json targets JSON config consumers: API payloads, Terraform inputs, and app config files.
What it does
dhall-to-json type-checks and normalizes a Dhall expression, then serializes it to JSON. Null handling is explicit: by default an Optional None is omitted, and --preserve-null keeps it as a JSON null.
Common usage
dhall-to-json --file config.dhall > config.json
# compact single-line JSON
dhall-to-json --compact --file config.dhall > config.json
# keep Optional/None as JSON null
dhall-to-json --preserve-null --file config.dhall > config.jsonOptions
| Flag | What it does |
|---|---|
| --file <path> | Read the Dhall expression from a file |
| --compact | Emit JSON without pretty-printing whitespace |
| --preserve-null | Emit JSON null for Optional None instead of omitting |
| --explain | Explain type errors in detail |
| --output <path> | Write to a file instead of stdout |
In CI
Pin remote imports with a sha256 integrity hash for reproducibility and supply-chain safety. Because output is deterministic, diff the JSON in review. If a downstream tool distinguishes "absent" from null, choose --preserve-null deliberately rather than by accident.
Common errors in CI
"Error: Expression doesn't match annotation" is the type mismatch (Expected vs Actual). "Error: Unbound variable: x" means you referenced an identifier that is not in scope, often a missing let or import. "Error: Cannot convert ... to JSON" appears when an expression contains a type or function that has no JSON representation; normalize it to plain data first.