sjson

SJSON is a Go package for setting and deleting values within a JSON document using a simple dot-syntax path, without needing to unmarshal the document into a Go struct or map first. It operates directly on the raw JSON bytes or string, rewriting only the affected region, which makes single-field updates to large JSON payloads significantly faster and more memory-efficient than a full decode-modify-encode round trip.

Paths support nested objects, array indexing, array appends via the -1 key, and escaped literal keys containing dots. Values can be set from any Go type — primitives, slices, maps, or arbitrary structs via the standard library’s encoding/json fallback — and an Optimistic mode with in-place byte replacement lets callers who know a key already exists skip most of the allocation overhead entirely. It pairs naturally with GJSON, the companion package by the same author for reading JSON values by path, and both are designed to be used together as a lightweight alternative to full unmarshal/marshal cycles.

What You Get

• Path-based Set/Delete for JSON strings and byte slices via dot-syntax paths
• Support for setting values of any Go type — primitives, slices, maps, and arbitrary structs (via json.Marshal fallback)
• Array operations: index-based sets, out-of-bounds padding with null, and -1 append syntax
• SetRaw/SetRawBytes for injecting pre-marshalled JSON blocks without double-encoding
• An Optimistic + ReplaceInPlace option pair for near-zero-allocation in-place updates on existing keys

Common Use Cases

• Patching a single field in a large JSON API response or config file without a full unmarshal
• Building JSON payloads incrementally at CLI or middleware layers where defining a Go struct is unnecessary overhead
• Rewriting config files or webhook bodies in place while preserving unrelated fields and formatting
• Combining with GJSON for read-modify-write flows on JSON documents your program doesn’t otherwise model as Go types

Under The Hood

Architecture SJSON is a single flat package (sjson.go, ~750 lines) with no internal sub-packages or layering — appropriate for its narrow scope. Every public entry point (Set, SetBytes, SetRaw, Delete, and their Options variants) funnels into one private set() function, which parses the dot-syntax path into a slice of pathResult structs via parsePath, then either rewrites an existing value in place (appendRawPaths, using gjson.Get to locate the target byte range) or constructs new nested JSON structure from scratch (appendBuild). Path traversal and value location are delegated entirely to the sibling GJSON package rather than reimplemented, so SJSON’s own logic is essentially one recursive tree-rewrite algorithm layered on top of GJSON’s read path. Unsafe pointer casts between string and []byte headers avoid copies when converting between the string-based public API and the byte-slice internals.

Tech Stack Written in Go (module declares go 1.14), with exactly two runtime dependencies: github.com/tidwall/gjson (the companion read-path library used for locating values) and github.com/tidwall/pretty (used only in tests, for sorting/normalizing JSON during assertions). There is no web framework, ORM, or database — this is a pure, dependency-light algorithmic library. Build and CI are plain go build/go test via a GitHub Actions workflow (.github/workflows/go.yml) that checks out, fetches deps, builds, and runs the test suite on push and PR against master.

Code Quality The test suite (sjson_test.go, ~350 lines against ~750 lines of implementation) is table-driven, exercising Set, SetRaw, Delete, and their byte-slice variants through shared helper functions that normalize JSON before comparison. Errors are explicit and typed (a small errorType implementing the error interface) and propagated rather than swallowed — including from the encoding/json.Marshal fallback path for unrecognized value types. Naming follows idiomatic Go conventions (exported CamelCase, unexported lowerCamelCase), and CI runs go build plus go test on every push and PR, though there is no dedicated linter configuration in the repo.

What Makes It Unique SJSON’s core engineering bet is avoiding the decode-modify-encode round trip entirely: it rewrites only the byte range affected by a path update, and its Optimistic + ReplaceInPlace option pair goes further, mutating the caller’s byte slice directly via unsafe pointer tricks when a key is known to already exist — a deliberate, documented trade-off for near-zero-allocation updates in hot paths. This is a standard, well-understood technique (raw-byte JSON patching) rather than a novel algorithmic contribution, but the implementation is unusually disciplined about performance for a small, focused utility library.