README.md
1# [](https://github.com/ohler55/ojg)
2
3[](https://github.com/ohler55/ojg/actions)
4[](https://coveralls.io/github/ohler55/ojg?branch=master)
5[](https://goreportcard.com/report/github.com/ohler55/ojg)
6
7Optimized JSON for Go is a high performance parser with a variety of
8additional JSON tools. OjG is optimized to processing huge data sets
9where data does not necessarily conform to a fixed structure.
10
11## Features
12
13 - Fast JSON parser. Check out the cmd/benchmarks app in this repo.
14 - Full JSONPath implemenation that operates on simple types as well as structs.
15 - Generic types. Not the proposed golang generics but type safe JSON elements.
16 - Fast JSON validator (7 times faster with io.Reader).
17 - Fast JSON writer with a sort option (4 times faster).
18 - JSON builder from JSON sources using a simple assembly plan.
19 - Simple data builders using a push and pop approach.
20 - Object encoding and decoding using an approach similar to that used with Oj for Ruby.
21 - [Simple Encoding Notation](sen.md), a lazy way to write JSON omitting commas and quotes.
22
23## Using
24
25A basic Parse:
26
27```golang
28 obj, err := oj.ParseString(`{
29 "a":[
30 {"x":1,"y":2,"z":3},
31 {"x":2,"y":4,"z":6}
32 ]
33 }`)
34```
35
36Using JSONPath expressions:
37
38```golang
39 x, err := jp.ParseString("a[?(@.x > 1)].y")
40 ys := x.Get(obj)
41 // returns [4]
42```
43
44The **oj** command (cmd/oj) uses JSON path for filtering and
45extracting JSON elements. It also includes sorting, reformatting, and
46colorizing options.
47
48```
49$ oj -m "(@.name == 'Pete')" myfile.json
50
51```
52
53More complete examples are available in the go docs for most
54functions. The example for [Unmarshalling
55interfaces](oj/example_interface_test.go) demonstrates a feature that
56allows interfaces to be marshalled and unmarshalled.
57
58## Installation
59```
60go get github.com/ohler55/ojg
61go get github.com/ohler55/ojg/cmd/oj
62
63```
64
65or just import in your `.go` files.
66
67```
68import (
69 "github.com/ohler55/ojg/alt"
70 "github.com/ohler55/ojg/asm"
71 "github.com/ohler55/ojg/gen"
72 "github.com/ohler55/ojg/jp"
73 "github.com/ohler55/ojg/oj"
74 "github.com/ohler55/ojg/sen"
75)
76```
77
78To build and install the `oj` application:
79
80```
81go install ./...
82```
83
84## Benchmarks
85
86Higher numbers (longer bars) are better.
87
88```
89Parse string/[]byte
90 json.Unmarshal 55916 ns/op 17776 B/op 334 allocs/op
91 oj.Parse 39570 ns/op 18488 B/op 429 allocs/op
92 oj-reuse.Parse 17881 ns/op 5691 B/op 364 allocs/op
93
94 oj-reuse.Parse █████████████████████▉ 3.13
95 oj.Parse █████████▉ 1.41
96 json.Unmarshal ▓▓▓▓▓▓▓ 1.00
97
98Parse io.Reader
99 json.Decode 63029 ns/op 32449 B/op 344 allocs/op
100 oj.ParseReader 34289 ns/op 22583 B/op 430 allocs/op
101 oj-reuse.ParseReader 25094 ns/op 9788 B/op 365 allocs/op
102 oj.TokenizeLoad 13610 ns/op 6072 B/op 157 allocs/op
103
104 oj.TokenizeLoad ████████████████████████████████▍ 4.63
105 oj-reuse.ParseReader █████████████████▌ 2.51
106 oj.ParseReader ████████████▊ 1.84
107 json.Decode ▓▓▓▓▓▓▓ 1.00
108
109to JSON with indentation
110 json.Marshal 78762 ns/op 26978 B/op 352 allocs/op
111 oj.JSON 7662 ns/op 0 B/op 0 allocs/op
112 sen.Bytes 9053 ns/op 0 B/op 0 allocs/op
113
114 oj.JSON ███████████████████████████████████████████████████████████████████████▉ 10.28
115 sen.Bytes ████████████████████████████████████████████████████████████▉ 8.70
116 json.Marshal ▓▓▓▓▓▓▓ 1.00
117```
118
119See [all benchmarks](benchmarks.md)
120
121[Compare Go JSON parsers](https://github.com/ohler55/compare-go-json)
122
123## Releases
124
125See [CHANGELOG.md](CHANGELOG.md)
126
127## Links
128
129- *Documentation*: [https://pkg.go.dev/github.com/ohler55/ojg](https://pkg.go.dev/github.com/ohler55/ojg)
130
131- *GitHub* *repo*: https://github.com/ohler55/ojg
132
133- *JSONPath* description: https://goessner.net/articles/JsonPath
134
135- *JSONPath Comparisons*: https://cburgmer.github.io/json-path-comparison
136
137- *Go Report Card*: https://goreportcard.com/report/github.com/ohler55/ojg
138
139#### Links of Interest
140
141 - *Oj, a Ruby JSON parser*: http://www.ohler.com/oj/doc/index.html also at https://github.com/ohler55/oj
142
143 - *OjC, a C JSON parser*: http://www.ohler.com/ojc/doc/index.html also at https://github.com/ohler55/ojc
144
145 - *Fast XML parser and marshaller on GitHub*: https://github.com/ohler55/ox
146
147 - *Agoo, a high performance Ruby web server supporting GraphQL on GitHub*: https://github.com/ohler55/agoo
148
149 - *Agoo-C, a high performance C web server supporting GraphQL on GitHub*: https://github.com/ohler55/agoo-c
150
151#### Contributing
152
153+ Provide a Pull Request off the `develop` branch.
154+ Report a bug
155+ Suggest an idea
156
){kind=link}
){kind=link}