github.com/ubgo/textdata/jsonc/diff compares two JSONC documents by meaning: which values were added, removed or changed, at which path, and where each value starts in each file. Comments, layout, key order, trailing commas and number spelling (1 vs 1.0) do not count. Use it to answer "does prod's config differ from the default, and where" in a review tool, a drift check or a diff command; use diff(1) or clikit/textdiff when you care about bytes.
go get github.com/ubgo/textdata/jsonc@latestdiff is a package inside the jsonc module. You need two parsed *jsonc.Doc values. The runnable program for this page is examples/jsonc-tools/diff, which compares these two files:
// prod.jsonc
{
"replicas": 1,
"server": {"host": "0.0.0.0", "port": 443, "tls": true},
"hosts": ["z.example", "a.example", "b.example"],
"log.level": "warn"
}diff.Diff(a, b) returns the changes that turn a into b. Each Change carries:
| Field | Meaning |
|---|---|
Kind |
diff.Added (only in b), diff.Removed (only in a), diff.Changed (in both, different value or kind) |
Path |
canonical dotted path: server.port, hosts[2], "log.level" (a key with a dot is quoted), "" for the root |
Pointer |
the same path as an RFC 6901 JSON Pointer: /server/port, /log.level |
Old, New |
the values, decoded like encoding/json with UseNumber (map[string]any, []any, string, json.Number, bool, nil); nil on the side that has none |
OldPos, NewPos |
where the value starts in each file (pos.Pos, prints as line:col); the zero Pos (prints -) on the side that has none |
printChanges · examples/jsonc-tools/diff/main.go:94-104
func printChanges(w io.Writer, a, b *jsonc.Doc) error {
changes, err := diff.Diff(a, b)
if err != nil {
return err // a document with syntax errors is refused
}
for _, c := range changes {
fmt.Fprintf(w, "%-7s %-13s %v -> %v (%s %s, %s %s)\n",
c.Kind, c.Path, c.Old, c.New, baseName, c.OldPos, prodName, c.NewPos)
}
return nil
}The order is deterministic: depth first, object keys in byte order, array elements by index.
Kind is a closed set of string constants ("added", "removed", "changed"), the same strings textdatactl jsonc diff --json prints. Switch or group on the constants, never on literals. When you feed a path back into a jsonc.Doc method (Get, Set, Delete, Pos), use Pointer: it is never ambiguous, even for a key that contains a dot or starts with /.
summarize · examples/jsonc-tools/diff/main.go:114-130
func summarize(w io.Writer, a, b *jsonc.Doc) error {
changes, err := diff.Diff(a, b)
if err != nil {
return err
}
byKind := map[diff.Kind][]diff.Change{}
for _, c := range changes {
byKind[c.Kind] = append(byKind[c.Kind], c)
}
for _, k := range kindOrder {
fmt.Fprintf(w, "%s: %d\n", k, len(byKind[k]))
for _, c := range byKind[k] {
fmt.Fprintf(w, " %-13s %s\n", c.Path, c.Pointer)
}
}
return nil
}When the documents mean the same thing, Diff returns an empty, non-nil slice. Reordered keys, other comments, another layout and 1.0 vs 1 all give zero changes.
countChanges · examples/jsonc-tools/diff/main.go:136-139
func countChanges(a, b *jsonc.Doc) (int, error) {
changes, err := diff.Diff(a, b)
return len(changes), err
}diff.Equal(x, y) is the equality rule Diff uses, exported for values you decoded yourself the same way (encoding/json with UseNumber), for example in a test that applies changes and checks the result. Numbers compare by value: two integer literals exactly at any size (no float64 rounding), any other pair as float64. Objects ignore key order; arrays compare by position.
compareValues · examples/jsonc-tools/diff/main.go:146-156
func compareValues(w io.Writer) {
pairs := []struct{ x, y any }{
{json.Number("1"), json.Number("1.0")},
{json.Number("9007199254740993"), json.Number("9007199254740992")},
{map[string]any{"a": true, "b": nil}, map[string]any{"b": nil, "a": true}},
{[]any{"a", "b"}, []any{"b", "a"}},
}
for _, p := range pairs {
fmt.Fprintf(w, "%v == %v: %t\n", p.x, p.y, diff.Equal(p.x, p.y))
}
}cd examples/jsonc-tools/diff && go run .== base -> prod
removed debug true -> <nil> (base.jsonc 4:12, prod.jsonc -)
changed hosts[0] a.example -> z.example (base.jsonc 6:13, prod.jsonc 4:13)
changed hosts[1] b.example -> a.example (base.jsonc 6:26, prod.jsonc 4:26)
added hosts[2] <nil> -> b.example (base.jsonc -, prod.jsonc 4:39)
changed "log.level" info -> warn (base.jsonc 7:16, prod.jsonc 5:16)
changed server.port 8080 -> 443 (base.jsonc 3:22, prod.jsonc 3:41)
added server.tls <nil> -> true (base.jsonc -, prod.jsonc 3:53)
== by kind
added: 2
hosts[2] /hosts/2
server.tls /server/tls
removed: 1
debug /debug
changed: 4
hosts[0] /hosts/0
hosts[1] /hosts/1
"log.level" /log.level
server.port /server/port
== base -> same meaning, new layout
changes: 0
== Equal
1 == 1.0: true
9007199254740993 == 9007199254740992: false
map[a:true b:<nil>] == map[a:true b:<nil>]: true
[a b] == [b a]: false
The numbers: 7 changes (2 added, 1 removed, 4 changed). replicas (1.0 vs 1) and server.host are absent because they mean the same.
The same from the command line, which exits 1 when the files differ, like diff(1):
textdatactl jsonc diff base.jsonc prod.jsonc
textdatactl jsonc diff base.jsonc prod.jsonc --json | jq '.data.changes[].path'- Arrays compare by index. Inserting
z.exampleat the front ofhostsshows as twochangedentries and oneaddedat the end, not one insertion. That keeps the diff cheap, deterministic and always replayable; reorder-aware comparison is not offered. - A change of kind is one entry. When a value turns from an object into an array or a scalar,
Diffreports oneChangedat that path with the whole old and new value; it does not descend. - Added and removed carry the whole value. A new section is one
Addedentry whoseNewis amap[string]any, not one entry per key inside it. - Duplicate keys read last-wins, like
jsonc.Doc.Get; an earlier duplicate is invisible to the diff. - Use
Pointer, notPath, for lookups. The dottedPathquotes keys with dots ("log.level") and is meant for people;Pointeris the form to pass back tojsonc.Docmethods. - Numbers keep their literal.
Old/Newholdjson.Number, notfloat64; compare them withdiff.Equal, not==on strings ("1"and"1.0"are different strings but equal numbers). - Invalid input is refused. A document with syntax errors returns its error (
jsonc.ErrInvalid); a nil document returnsdiff.ErrNilDoc. An empty document reads asnull. - Plugins and
${VAR}expansion are not applied.Diffcompares the values as written in the files.
- Format a JSONC file, Generate a JSONC file, Validate with a JSON Schema
- Package reference: jsonc/diff README (API, rules, guarantees)
- CLI: jsonc/cli README § verbs (
diff) - Example:
examples/jsonc-tools/diff; the package's ownExample - API: pkg.go.dev/github.com/ubgo/textdata/jsonc/diff