ADR 0014: Use encoding/json/v2

• Status: Accepted
• Date: 2026-10-24
• Supersedes: none

Context

The brief says to use encoding/json/v2 if it is stable in our Go version. Go 1.27 includes encoding/json/v2 as a stable package. No GOEXPERIMENT setting is necessary.

Decision

Use encoding/json/v2 and encoding/json/jsontext for all new JSON code. Do not use encoding/json (v1) in new code.

Alternatives

1. encoding/json (v1). This is stable for a long time, but it is slower and has less precise options for empty and zero values.
2. An outside JSON library. This adds a dependency, which the brief does not permit.

Consequences

• Field tags use v2 rules. Use omitzero to omit a zero value. The v2 omitempty omits values that encode as empty JSON, such as "" and null.
• jsontext.Value holds raw JSON when Tollgate must not decode a field.