ojg

README

Optimized JSON for Go is a high performance parser with a variety of additional JSON tools.

Features

• Fast JSON parser. Check out the cmd/benchmarks app in this repo.
• Full JSONPath implemenation that operates on simple types as well as structs.
• Generic types. Not the proposed golang generics but type safe JSON elements.
• Fast JSON validator (4 times faster with io.Reader).
• Fast JSON writer with a sort option (1.6 times faster).
• Simple data builders using a push and pop approach.
• Object encoding and decoding using an approach similar to that used with Oj for Ruby.
• Simple Encoding Notation, a lazy way to write JSON omitting commas and quotes.

Using

A basic Parse:

    obj, err := oj.ParseString(`{
        "a":[
            {"x":1,"y":2,"z":3},
            {"x":2,"y":4,"z":6}
        ]
    }`)

Using JSONPath expressions:

    x, err := jp.ParseString("a[?(@.x > 1)].y")
    ys := x.Get(obj)
    // returns [4]

The oj command (cmd/oj) which uses JSON path for filtering and extracting JSON elements. It also includes sorting, reformatting, and colorizing options.

$ oj -m "(@.name == 'Pete')" myfile.json

Installation

go get github.com/ohler55/ojg
go get github.com/ohler55/ojg/cmd/oj

or just import in your .go files.

import (
    "github.com/ohler55/ojg/alt"
    "github.com/ohler55/ojg/gen"
    "github.com/ohler55/ojg/jp"
    "github.com/ohler55/ojg/oj"
    "github.com/ohler55/ojg/sen"
)

To build and install the oj application:

go install ./...

Benchmarks

Higher numbers (longer bars) are better.

Parse string/[]byte
       json.Unmarshal       40464 ns/op   17984 B/op     336 allocs/op
         oj.Parse           22845 ns/op   18783 B/op     431 allocs/op
   oj-reuse.Parse           17546 ns/op    5984 B/op     366 allocs/op

   oj-reuse ███████████████████████  2.31
         oj █████████████████▋ 1.77
       json ▓▓▓▓▓▓▓▓▓▓ 1.00

Parse io.Reader
       json.Decode          51431 ns/op   32657 B/op     346 allocs/op
         oj.ParseReader     26502 ns/op   22881 B/op     432 allocs/op
   oj-reuse.ParseReader     20803 ns/op   10080 B/op     367 allocs/op

   oj-reuse ████████████████████████▋ 2.47
         oj ███████████████████▍ 1.94
       json ▓▓▓▓▓▓▓▓▓▓ 1.00

to JSON with indentation
       json.Marshal         71587 ns/op   27327 B/op     352 allocs/op
         oj.JSON            11950 ns/op    4096 B/op       1 allocs/op
        sen.String          12524 ns/op    4096 B/op       1 allocs/op

         oj ███████████████████████████████████████████████████████████▉ 5.99
        sen █████████████████████████████████████████████████████████▏ 5.72
       json ▓▓▓▓▓▓▓▓▓▓ 1.00

See all benchmarks

Compare Go JSON parsers

Releases

See CHANGELOG.md

Links

• Documentation: https://pkg.go.dev/github.com/ohler55/ojg

• GitHub repo: https://github.com/ohler55/ojg

• JSONPath description: https://goessner.net/articles/JsonPath

Links of Interest

• Oj, a Ruby JSON parser: http://www.ohler.com/oj/doc/index.html also at https://github.com/ohler55/oj

• OjC, a C JSON parser: http://www.ohler.com/ojc/doc/index.html also at https://github.com/ohler55/ojc

• Fast XML parser and marshaller on GitHub: https://github.com/ohler55/ox

• Agoo, a high performance Ruby web server supporting GraphQL on GitHub: https://github.com/ohler55/agoo

• Agoo-C, a high performance C web server supporting GraphQL on GitHub: https://github.com/ohler55/agoo-c

Contributing

• Provide a Pull Request off the develop branch.
• Report a bug
• Suggest an idea

Documentation

Overview

Package ojg is a collection of JSON tools including a validator and parser.

Oj

Package oj contains functions and types for parsing JSON as well as support for building building simple types. Included in the oj package are:

Parser for parsing JSON strings and streams into simple types.

Validator for validating JSON strings and streams.

Builder for building simple types.

Writer for writing data as JSON.

Gen

Package gen provides type safe generic types. They are type safe in that array and objects can only be constructed of other types in the package. The basic types are:

Bool
Int
Float
String
Time

The collection types are Array and Object. All the types implement the Node interface which is relatively simple interface defined primarily to restrict what can be in the collection types. The Node interface should not be used to define new generic types.

Also included in the package are a builder and parser that behave like the parser and builder in the oj package except for gen types.

Jp

Package jp provides JSONPath implementation that operations on simple go types, generic (gen package), and public struct with public members. Get, set, and delete operations can be evaluated on data. When needed reflection is used to follow a path.

Alt

The alt package contains functions and types for altering values. It includes functions for:

Decompose() a value into simple types of bool, int64, float64, string,
            time.Time, []interface{} and map[string]interface{}.

Recompose() takes simple data type and converts it back into a complex type.

Alter() is the same as decompose except it alters the value in place.

Generify() converts a simple value into a gen.Node.

Cmd oj

The oj command is a general purpose tool for processing JSON documents. Features include reformatting JSON, colorizing JSON, extracting parts of a JSON document, and filtering. JSONPath is used for both extracting and filtering.