µjson — A minimal JSON parser and transformer in Go

is a minimal JSON parser and transformer that works on . It works by parsing input and calling the given callback function when encountering each item. µjson unstructured (and trusted) JSON Motivation Sometimes we just want to make some minimal changes to a JSON document or do some generic transformations without fully unmarshalling it. For example, removing blacklisted keys from response JSON. Why spend all the cost on unmarshalling into a just to immediately marshal it again. The following code is taken from : map[string]interface{} StackOverflow { : { : , : , : { : , : } }, : { : , : , : [ { : }, { : } ] } } "responseHeader" "status" 0 "QTime" 0 "params" "q" "solo" "wt" "json" "response" "numFound" 2 "start" 0 "docs" "name" "foo" "name" "bar" With , we can quickly write to remove completely from all responses, once and forever. More on that later. µjson a simple transformation "responseHeader" The original scenario that leads me to write the package is because of . When working in Go and PostgreSQL, I use (instead of ) for because it’s more effective and has enormous space for randomly generated ids. It’s not as big as UUID, 128 bits, but still big enough for production use. In PostgreSQL, those ids can be stored as and being effectively indexed. But for JavaScript, it can only process integer up to 53 bits (JavaScript has BigInt but that’s a different story, and using it will make things even more complicated). int64 int64 string ids bigint So we need to wrap those int64s into strings before sending them to JavaScript. In Go and PostgreSQL, the JSON is but JavaScript will see it as (note that the value is quoted). In Go, we can define a custom type and implement the interface. But in PostgreSQL, that’s just not possible or too complicated. I wrote a service that receives JSON from PostgreSQL and converts it to be consumable by JavaScript. The service also removes some blacklisted keys or does some other transformations (for example, change to ). {"order_id": 12345678} {"order_id": "12345678"} json.Marshaler orderId order_id So I wrote a simple JSON parser and transformer. It can: Print all keys and values in order Reformat input Remove all whitespaces Remove blacklisted keys Wrap int64s into strings before handing to JavaScript Extract some values … and more. Important: Behavior is undefined for invalid JSON, use on trusted input only! For untrusted input, you might want to run it through json.Valid() before handing it to µjson . Let’s see how work by examples: µjson 1. Print all keys and values in order The callback function is called when an object key/value or an array key is encountered. It receives 3 params in order: , and . level key value is the indentation level of the JSON, if you format it properly. It starts from 0. It increases after entering an object or array and decreases after leaving. level is the raw key of the current object or empty otherwise. It can be a double-quoted string or empty. key is the raw value of the current item or a bracket. It can be a string, number, boolean, null, or one of the following brackets: . Values will never be empty. value { } [ ] It’s important to note that key and value are provided as raw. Strings are always double-quoted. It’s there for keeping the library fast and ignoring unnecessary operations. For example, when you only want to reformat the output JSON properly; you don’t want to unquote those strings and then immediately quote them again; you just need to output them unmodified. And there are and when you need to get the original strings. ujson.Unquote() ujson.AppendQuote() When processing arrays and objects, first the open bracket ( , ) will be provided as value, followed by its children, and the close bracket ( , ). When encountering open brackets, you can make the callback function return to skip the object/array entirely. [ { ] } false main { input := [] ( ) ujson.Walk(input, { fmt.Printf( , level, key, value) }) } package import "fmt" import "github.com/olvrng/ujson" func main () byte `{ "id": 12345, "name": "foo", "numbers": ["one", "two"], "tags": {"color": "red", "priority": "high"}, "active": true }` func (level , key, value [] ) int byte bool "%2v% 12s : %s\n" return true : { : : : [ : : : ] : { : : : } : : } 0 1 "id" 12345 1 "name" "foo" 1 "numbers" 2 "one" 2 "two" 1 1 "tags" 2 "color" "red" 2 "priority" "high" 1 1 "active" true 0 0. The simplest examples To easily get an idea on , and , here are the simplest examples: level key value main { input0 := [] ( ) ujson.Walk(input0, { fmt.Printf( , level, key, value) }) input1 := [] ( ) ujson.Walk(input1, { fmt.Printf( , level, key, value) }) input2 := [] ( ) ujson.Walk(input2, { fmt.Printf( , level, key, value) }) } package import "fmt" import "github.com/olvrng/ujson" func main () byte `true` func (level , key, value [] ) int byte bool "level=%v key=%s value=%s\n" return true // output: // level=0 key= value=true byte `{ "key": 42 }` func (level , key, value [] ) int byte bool "level=%v key=%s value=%s\n" return true // output: // level=0 key= value={ // level=1 key="key" value=42 // level=0 key= value=} byte `[ true ]` func (level , key, value [] ) int byte bool "level=%v key=%s value=%s\n" return true // output: // level=0 key= value=[ // level=1 key= value=true // level=0 key= value=] In the first example, there is only a single boolean value. The callback function is called once with , is empty and . level=0 key value=true In the second example, the callback function is called 3 times. Two times for open and close brackets with , key is empty and value is the bracketed character. The other time for the only key with , is and . Note that the key is quoted and you need to call to retrieve the unquoted string. level=0 level=1 key "key" value=42 ujson.Unquote() The last example is like the second, but with an array instead. Keys are always empty inside arrays. 2. Reformat input In this example, the input JSON is formatted with correct indentation. As processing the input key by key, the callback function reconstructs the JSON. It outputs each key/value pair in its own line, prefixed with spaces equal to the param level. There is a catch, though. Valid JSON requires commas between values in objects and arrays. So there is for checking whether a comma should be inserted. ujson.ShouldAddComma() main { input := [] ( ) b := ([] , , ) err := ujson.Walk(input, { (b) != && ujson.ShouldAddComma(value, b[ (b) ]) { b = (b, ) } b = (b, ) i := ; i { b = (b, key...) b = (b, ...) } b = (b, value...) }) err != { (err) } fmt.Printf( , b) } package import "fmt" import "github.com/olvrng/ujson" func main () byte `{"id":12345,"name":"foo","numbers":["one","two"],"tags":{"color":"red","priority":"high"},"active":true}` make byte 0 1024 func (level , key, value [] ) int byte bool if len 0 len -1 append ',' append '\n' for 0 append '\t' if len 0 append append `: ` append return true if nil panic "%s\n" { : , : , : [ , ], : { : , : }, : } "id" 12345 "name" "foo" "numbers" "one" "two" "tags" "color" "red" "priority" "high" "active" true There is a built-in method when you want to remove all the whitespaces. ujson.Reconstruct() 3. Remove blacklisted keys This example demonstrates removing some keys from the input JSON. The key param is compared with a pre-defined list. If there is a match, the blacklisted key and its value are dropped. The callback function returns false for skipping the entire value (which may be an object or array). Note that the list is quoted, i.e. and instead of and . For more advanced checking, you may want to run on the key. "numbers" "active" number active ujson.Unquote() main { input := [] ( ) blacklistFields := [][] { [] ( ), [] ( ), } b := ([] , , ) err := ujson.Walk(input, { _, blacklist := blacklistFields { bytes.Equal(key, blacklist) { } } (b) != && ujson.ShouldAddComma(value, b[ (b) ]) { b = (b, ) } (key) > { b = (b, key...) b = (b, ) } b = (b, value...) }) err != { (err) } fmt.Printf( , b) } package import "bytes" import "fmt" import "github.com/olvrng/ujson" func main () byte `{ "id": 12345, "name": "foo", "numbers": ["one", "two"], "tags": {"color": "red", "priority": "high"}, "active": true }` byte byte `"numbers"` // note the quotes byte `"active"` make byte 0 1024 func (_ , key, value [] ) int byte bool for range if // remove the key and value from the output return false // write to output if len 0 len -1 append ',' if len 0 append append ':' append return true if nil panic "%s\n" { : , : , :{ : , : }} "id" 12345 "name" "foo" "tags" "color" "red" "priority" "high" As you see in the output, and are removed. "numbers" "active" 4. Wrap int64 in string This is the original motivation behind . The following example finds keys ending with ( , , etc.) and converts their values from numbers to strings, by simply wrapping them in double-quotes. µjson _id" "order_id" "item_id" For valid JSON, values are never empty. We can test the first byte of ( ) to get its type: value value[0] : Null n , : Boolean f t ... : Number 0 9 : String, see " ujson.Unquote() , : Array [ ] , : Object { } In this case, we check within … to see whether it’s a number, then insert double-quotes. value[0] 0 9 main { input := [] ( ) suffix := [] ( ) b := ([] , , ) err := ujson.Walk(input, { shouldWrap := bytes.HasSuffix(key, suffix) && value[ ] > && value[ ] { b = (b, key...) b = (b, ) } shouldWrap { b = (b, ) } b = (b, value...) shouldWrap { b = (b, ) } }) err != { (err) } fmt.Printf( , b) } package import "bytes" import "fmt" import "github.com/olvrng/ujson" func main () byte `{"order_id": 12345678901234, "number": 12, "item_id": 12345678905678, "counting": [1,"2",3]}` byte `_id"` // note the ending quote " make byte 0 256 func (_ , key, value [] ) int byte bool // Test for keys with suffix _id" and value is an int64 number. For valid json, // values will never be empty, so we can safely test only the first byte. 0 '0' 0 '9' // transform the input, wrap values in double quotes if len 0 len -1 append ',' if len 0 append append ':' if append '"' append if append '"' return true if nil panic "%s\n" { : , : , : , :[ , , ]} "order_id" "12345678901234" "number" 12 "item_id" "12345678905678" "counting" 1 "2" 3 After processing, the numbers in and are quoted as strings. And JavaScript should be happy now! 🎉 🎉 "order_id" "item_id" Recap You can start using it by . The is short and easy to read. Feedback is welcome 👋 import " github.com/olvrng/ujson " source code Also published at https://olvrng.github.io/w/ujson