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