The encoder's name says what it writes

Variant said "encoding/json/v2", which reads as v2's semantics — a zero kept
under omitempty, a nil slice as [], case-sensitive decoding, a map's keys
unsorted. This wire does none of that: the options are v1's, plus sorted keys.
Naming only the engine misleads in exactly the direction that matters, and the
one moment anyone reads it is a startup line in a log.

It is also a declaration rather than a reading of the toolchain. zip marshals
through v2 because this package imports it; GOEXPERIMENT=nojsonv2 does not fall
back to v1, it fails to compile — so the name cannot describe an encoder the
binary is not using.

Co-authored-by: Hanzo Dev <[email protected]>

internal/jsonenc/jsonenc.go

@@ -6,8 +6,19 @@ import (
 	"io"
 )
 
-// Variant names the JSON implementation. zip.New() logs it once at startup.
-const Variant = "encoding/json/v2"
+// Variant names the encoder AND what it says, because the two are chosen
+// separately here and naming only the first misleads in the direction that
+// matters: v2's own semantics keep a zero under omitempty, write a nil slice as
+// [] and a nil map as {}, decode case-sensitively and leave a map's keys
+// unsorted. This wire does none of that.
+//
+// It is a DECLARATION, not a reading of the toolchain. zip marshals through
+// encoding/json/v2 because this package imports it; a build with
+// GOEXPERIMENT=nojsonv2 does not fall back to v1, it fails to compile, so the
+// name can never describe an encoder the binary is not using.
+//
+// zip.New() logs it once at startup, which is the one moment anyone asks.
+const Variant = "encoding/json/v2 (v1 semantics, sorted keys)"
 
 // wire is what zip's JSON says, stated once and passed to every call.
 //

zip.go

@@ -42,9 +42,10 @@ import (
 	"github.com/zap-proto/zip/internal/jsonenc"
 )
 
-// JSONVariant names the JSON implementation on the edge, which zip.New logs
-// once at startup. Per HIP-0106 the wire stack is "JSON only at edge, ZAP
-// between services", so this is the one place the edge's encoder is stated.
+// JSONVariant names the JSON implementation on the edge and the semantics it
+// writes, which zip.New logs once at startup. Per HIP-0106 the wire stack is
+// "JSON only at edge, ZAP between services", so this is the one place the
+// edge's encoder is stated. What it means is in [jsonenc.Variant].
 const JSONVariant = jsonenc.Variant
 
 // Handler is zip's request handler signature. Returning an error causes