1# encoding/json [![GoDoc](https://godoc.org/github.com/segmentio/encoding/json?status.svg)](https://godoc.org/github.com/segmentio/encoding/json) 2 3Go package offering a replacement implementation of the standard library's 4[`encoding/json`](https://golang.org/pkg/encoding/json/) package, with much 5better performance. 6 7## Usage 8 9The exported API of this package mirrors the standard library's 10[`encoding/json`](https://golang.org/pkg/encoding/json/) package, the only 11change needed to take advantage of the performance improvements is the import 12path of the `json` package, from: 13```go 14import ( 15 "encoding/json" 16) 17``` 18to 19```go 20import ( 21 "github.com/segmentio/encoding/json" 22) 23``` 24 25One way to gain higher encoding throughput is to disable HTML escaping. 26It allows the string encoding to use a much more efficient code path which 27does not require parsing UTF-8 runes most of the time. 28 29## Performance Improvements 30 31The internal implementation uses a fair amount of unsafe operations (untyped 32code, pointer arithmetic, etc...) to avoid using reflection as much as possible, 33which is often the reason why serialization code has a large CPU and memory 34footprint. 35 36The package aims for zero unnecessary dynamic memory allocations and hot code 37paths that are mostly free from calls into the reflect package. 38 39## Compatibility with encoding/json 40 41This package aims to be a drop-in replacement, therefore it is tested to behave 42exactly like the standard library's package. However, there are still a few 43missing features that have not been ported yet: 44 45- Streaming decoder, currently the `Decoder` implementation offered by the 46package does not support progressively reading values from a JSON array (unlike 47the standard library). In our experience this is a very rare use-case, if you 48need it you're better off sticking to the standard library, or spend a bit of 49time implementing it in here ;) 50 51Note that none of those features should result in performance degradations if 52they were implemented in the package, and we welcome contributions! 53 54## Trade-offs 55 56As one would expect, we had to make a couple of trade-offs to achieve greater 57performance than the standard library, but there were also features that we 58did not want to give away. 59 60Other open-source packages offering a reduced CPU and memory footprint usually 61do so by designing a different API, or require code generation (therefore adding 62complexity to the build process). These were not acceptable conditions for us, 63as we were not willing to trade off developer productivity for better runtime 64performance. To achieve this, we chose to exactly replicate the standard 65library interfaces and behavior, which meant the package implementation was the 66only area that we were able to work with. The internals of this package make 67heavy use of unsafe pointer arithmetics and other performance optimizations, 68and therefore are not as approachable as typical Go programs. Basically, we put 69a bigger burden on maintainers to achieve better runtime cost without 70sacrificing developer productivity. 71 72For these reasons, we also don't believe that this code should be ported upstream 73to the standard `encoding/json` package. The standard library has to remain 74readable and approachable to maximize stability and maintainability, and make 75projects like this one possible because a high quality reference implementation 76already exists. 77