Set JSON values very quickly in Go

SJSON
GoDoc

set a json value quickly

SJSON is a Go package that provides a very fast and simple way to set a value in a json document. For quickly retrieving json values check out GJSON.

For a command line interface check out JJ.

Getting Started

Installing

To start using SJSON, install Go and run go get:

$ go get -u github.com/tidwall/sjson

This will retrieve the library.

Set a value

Set sets the value for the specified path. A path is in dot syntax, such as "name.last" or "age". This function expects that the json is well-formed and validated. Invalid json will not panic, but it may return back unexpected results. Invalid paths may return an error.

package main

import "github.com/tidwall/sjson"

const json = `{"name":{"first":"Janet","last":"Prichard"},"age":47}`

func main() {
	value, _ := sjson.Set(json, "name.last", "Anderson")
	println(value)
}

This will print:

{"name":{"first":"Janet","last":"Anderson"},"age":47}

Path syntax

A path is a series of keys separated by a dot. The dot and colon characters can be escaped with \.

{
  "name": {"first": "Tom", "last": "Anderson"},
  "age":37,
  "children": ["Sara","Alex","Jack"],
  "fav.movie": "Deer Hunter",
  "friends": [
	{"first": "James", "last": "Murphy"},
	{"first": "Roger", "last": "Craig"}
  ]
}
"name.last"          >> "Anderson"
"age"                >> 37
"children.1"         >> "Alex"
"friends.1.last"     >> "Craig"

The -1 key can be used to append a value to an existing array:

"children.-1"  >> appends a new value to the end of the children array

Normally number keys are used to modify arrays, but it's possible to force a numeric object key by using the colon character:

{
  "users":{
    "2313":{"name":"Sara"},
    "7839":{"name":"Andy"}
  }
}

A colon path would look like:

"users.:2313.name"    >> "Sara"

Supported types

Pretty much any type is supported:

sjson.Set(`{"key":true}`, "key", nil)
sjson.Set(`{"key":true}`, "key", false)
sjson.Set(`{"key":true}`, "key", 1)
sjson.Set(`{"key":true}`, "key", 10.5)
sjson.Set(`{"key":true}`, "key", "hello")
sjson.Set(`{"key":true}`, "key", map[string]interface{}{"hello":"world"})

When a type is not recognized, SJSON will fallback to the encoding/json Marshaller.

Examples

Set a value from empty document:

value, _ := sjson.Set("", "name", "Tom")
println(value)

// Output:
// {"name":"Tom"}

Set a nested value from empty document:

value, _ := sjson.Set("", "name.last", "Anderson")
println(value)

// Output:
// {"name":{"last":"Anderson"}}

Set a new value:

value, _ := sjson.Set(`{"name":{"last":"Anderson"}}`, "name.first", "Sara")
println(value)

// Output:
// {"name":{"first":"Sara","last":"Anderson"}}

Update an existing value:

value, _ := sjson.Set(`{"name":{"last":"Anderson"}}`, "name.last", "Smith")
println(value)

// Output:
// {"name":{"last":"Smith"}}

Set a new array value:

value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.2", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol","Sara"]

Append an array value by using the -1 key in a path:

value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.-1", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol","Sara"]

Append an array value that is past the end:

value, _ := sjson.Set(`{"friends":["Andy","Carol"]}`, "friends.4", "Sara")
println(value)

// Output:
// {"friends":["Andy","Carol",null,null,"Sara"]

Delete a value:

value, _ := sjson.Delete(`{"name":{"first":"Sara","last":"Anderson"}}`, "name.first")
println(value)

// Output:
// {"name":{"last":"Anderson"}}

Delete an array value:

value, _ := sjson.Delete(`{"friends":["Andy","Carol"]}`, "friends.1")
println(value)

// Output:
// {"friends":["Andy"]}

Delete the last array value:

value, _ := sjson.Delete(`{"friends":["Andy","Carol"]}`, "friends.-1")
println(value)

// Output:
// {"friends":["Andy"]}

Performance

Benchmarks of SJSON alongside encoding/json, ffjson, EasyJSON, and Gabs

Benchmark_SJSON-8                  	 3000000	       805 ns/op	    1077 B/op	       3 allocs/op
Benchmark_SJSON_ReplaceInPlace-8   	 3000000	       449 ns/op	       0 B/op	       0 allocs/op
Benchmark_JSON_Map-8               	  300000	     21236 ns/op	    6392 B/op	     150 allocs/op
Benchmark_JSON_Struct-8            	  300000	     14691 ns/op	    1789 B/op	      24 allocs/op
Benchmark_Gabs-8                   	  300000	     21311 ns/op	    6752 B/op	     150 allocs/op
Benchmark_FFJSON-8                 	  300000	     17673 ns/op	    3589 B/op	      47 allocs/op
Benchmark_EasyJSON-8               	 1500000	      3119 ns/op	    1061 B/op	      13 allocs/op

JSON document used:

{
  "widget": {
    "debug": "on",
    "window": {
      "title": "Sample Konfabulator Widget",
      "name": "main_window",
      "width": 500,
      "height": 500
    },
    "image": { 
      "src": "Images/Sun.png",
      "hOffset": 250,
      "vOffset": 250,
      "alignment": "center"
    },
    "text": {
      "data": "Click Here",
      "size": 36,
      "style": "bold",
      "vOffset": 100,
      "alignment": "center",
      "onMouseUp": "sun1.opacity = (sun1.opacity / 100) * 90;"
    }
  }
}    

Each operation was rotated though one of the following search paths:

widget.window.name
widget.image.hOffset
widget.text.onMouseUp

These benchmarks were run on a MacBook Pro 15" 2.8 GHz Intel Core i7 using Go 1.7 and can be be found here.

Contact

Josh Baker @tidwall

License

SJSON source code is available under the MIT License.

Similar Resources

A Go package for handling common HTTP JSON responses.

go-respond A Go package for handling common HTTP JSON responses. Installation go get github.com/nicklaw5/go-respond Usage The goal of go-respond is to

Sep 26, 2022

JSON query in Golang

gojq JSON query in Golang. Install go get -u github.com/elgs/gojq This library serves three purposes: makes parsing JSON configuration file much easie

Dec 28, 2022

Automatically generate Go (golang) struct definitions from example JSON

gojson gojson generates go struct definitions from json or yaml documents. Example $ curl -s https://api.github.com/repos/chimeracoder/gojson | gojson

Jan 1, 2023

A JSON diff utility

JayDiff A JSON diff utility. Install Downloading the compiled binary Download the latest version of the binary: releases extract the archive and place

Dec 11, 2022

Fast and flexible JSON encoder for Go

Fast and flexible JSON encoder for Go

Jettison Jettison is a fast and flexible JSON encoder for the Go programming language, inspired by bet365/jingo, with a richer features set, aiming at

Dec 21, 2022

Create go type representation from json

json2go Package json2go provides utilities for creating go type representation from json inputs. Json2go can be used in various ways: CLI tool Web pag

Dec 26, 2022

Console JSON formatter with query feature

Console JSON formatter with query feature

Console JSON formatter with query feature. Install: $ go get github.com/miolini/jsonf Usage: Usage of jsonf: -c=true: colorize output -d=false: de

Dec 4, 2022

Fluent API to make it easier to create Json objects.

Jsongo Fluent API to make it easier to create Json objects. Install go get github.com/ricardolonga/jsongo Usage To create this: { "name":"Ricar

Nov 7, 2022

Arbitrary transformations of JSON in Golang

kazaam Description Kazaam was created with the goal of supporting easy and fast transformations of JSON data with Golang. This functionality provides

Dec 18, 2022
Comments
  • how to delete all element keys for a map field?

    how to delete all element keys for a map field?

    Purpose

    a :=  `{"records": {"1":{"id":"1","name":"a"},"2":{"id":"2","name":"b"}}}`
    
    Delete(a, `records.*.id`)
    
    should became:
    {"records": {"1":{"name":"a"},"2":{"name":"b"}}}
    

    but this records.*.id can not work.

  • Mismatched Encoding / Decoding of Byte Values

    Mismatched Encoding / Decoding of Byte Values

    great project, thanks for your contribution to open source!

    i'm consistently experiencing some unusual behavior when setting byte values (the impacted code is here and here): when byte values are set, they are converted to a string and then (by default) encoded using the standard library's json.Marshal function, but (for reasons i don't understand) it appears that json.Unmarshal does not decode the value back to the original byte value. here's an example showing how SJSON's behavior mimics the behavior of the standard library, plus a "working example" using strconv to get the original bytes.

    as an aside, was it a design decision for SJSON to not encode bytes as a base64 encoded string? that is how the standard library works and it would also solve the problem of consistently decoding back to the original value.

    thanks!

  • Why can't this scenario assign a value to a list?

    Why can't this scenario assign a value to a list?

    type StudentInfo struct {
    	StudentId string   `json:"student_id"`
    	Class     []string `json:"class"`
    }
    
    type Item struct {
    	StudentInfo []*StudentInfo `json:"student_info"`
    }
    
    func main() {
    	item := &Item{
    		[]*StudentInfo{
    			{
    				StudentId: "1",
    				Class:     []string{"class1"},
    			},
    		},
    	}
    	itemBytes, _ := json.Marshal(item)
    	ret, _ := sjson.Set(string(itemBytes), `student_info.#(student_id=="1").class.-1`, "class2")
    	fmt.Println(ret)
    }
    

    my desired result is {"student_info":[{"student_id":"1","class":["class1","class2"]}]},but the actual result is {"student_info":[{"student_id":"1","class":["class1"]}]}

  • Need to set array of values to array of objects.

    Need to set array of values to array of objects.

    need to set multiple values for an array of objects

    package main
    
    import (
    	"fmt"
    
    	"github.com/tidwall/sjson"
    )
    
    const jsondata = `{"data":[]}`
    
    func main() {
    	data := make([]string, 0)
    	data = append(data, "sos", "msa", "kkh")
    	value, err := sjson.Set(jsondata, "data.#.name", data)
    	if err != nil {
    		fmt.Println(err)
    	}
    	println(value)
    
    }
    

    expected result

    {data:[{name:"sos"},{name:"msa"},{name:"kkh"}]
    

    output result

    {"data":[]}
    

    from my understanding of the source code, I have observed that the value is converted to a string and replaced at the exact path. is there any possible way to implement this?. However, we will be able to map the array by providing an index number instead of #

    value, err := sjson.Set(jsondata, "data.0.name", data[0])
    value, err = sjson.Set(value, "data.1.name", data[1])
    
Related tags
converts text-formats from one to another, it is very useful if you want to re-format a json file to yaml, toml to yaml, csv to yaml, ... etc

re-txt reformates a text file from a structure to another, i.e: convert from json to yaml, toml to json, ... etc Supported Source Formats json yaml hc

Sep 23, 2022
A very rudimentary JSON compare package in GO

simple_json_compare A very rudimentary JSON compare package Sample code package main import ( "fmt" "github.com/CalypsoSys/simple_json_compare" )

Oct 20, 2021
JSON diff library for Go based on RFC6902 (JSON Patch)

jsondiff jsondiff is a Go package for computing the diff between two JSON documents as a series of RFC6902 (JSON Patch) operations, which is particula

Dec 4, 2022
Fast JSON encoder/decoder compatible with encoding/json for Go
Fast JSON encoder/decoder compatible with encoding/json for Go

Fast JSON encoder/decoder compatible with encoding/json for Go

Jan 6, 2023
Package json implements encoding and decoding of JSON as defined in RFC 7159

Package json implements encoding and decoding of JSON as defined in RFC 7159. The mapping between JSON and Go values is described in the documentation for the Marshal and Unmarshal functions

Jun 26, 2022
Json-go - CLI to convert JSON to go and vice versa
Json-go - CLI to convert JSON to go and vice versa

Json To Go Struct CLI Install Go version 1.17 go install github.com/samit22/js

Jul 29, 2022
JSON Spanner - A Go package that provides a fast and simple way to filter or transform a json document

JSON SPANNER JSON Spanner is a Go package that provides a fast and simple way to

Sep 14, 2022
Abstract JSON for golang with JSONPath support

Abstract JSON Abstract JSON is a small golang package provides a parser for JSON with support of JSONPath, in case when you are not sure in its struct

Jan 5, 2023
Fast JSON parser and validator for Go. No custom structs, no code generation, no reflection

fastjson - fast JSON parser and validator for Go Features Fast. As usual, up to 15x faster than the standard encoding/json. See benchmarks. Parses arb

Jan 5, 2023
Small utility to create JSON objects
Small utility to create JSON objects

gjo Small utility to create JSON objects. This was inspired by jpmens/jo. Support OS Mac Linux Windows Requirements Go 1.1.14~ Git Installtion Build $

Dec 8, 2022