Skip to content
Decode JSON with Functional Decoders
Go Makefile
Branch: master
Clone or download
Aaron Schlesinger
Aaron Schlesinger bool decoder (#4)
Latest commit cd91725 Mar 13, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Initial commit Mar 3, 2019
LICENSE Initial commit Mar 3, 2019
Makefile adding a makefile Mar 6, 2019 fixing badge links (#6) Mar 13, 2019 splitting usage out Mar 6, 2019
azure-pipelines.yml turning on module builds (#5) Mar 13, 2019
bool.go bool decoder (#4) Mar 13, 2019
builder.go code samples Mar 11, 2019
builder_test.go making the builder a thing Mar 6, 2019
decode.go fix build error Mar 13, 2019
decode_test.go adding a makefile Mar 6, 2019
decoder.go adding godocs Mar 11, 2019
decoder_test.go more stuff Mar 6, 2019
exists.go adding godocs Mar 11, 2019
field.go code sample formatting Mar 11, 2019
field_test.go adding a makefile Mar 6, 2019
float64.go adding godocs Mar 11, 2019
go.mod first things Mar 3, 2019
go.sum first things Mar 3, 2019
int.go adding godocs Mar 11, 2019
string.go adding godocs Mar 11, 2019
the_suite_of_test.go adding a makefile Mar 6, 2019
types.go stuff! Mar 6, 2019

Welcome to dcode 🎉

Build Status Go Report Card GoDoc

Note: this library is a work in progress. I'd love for you to try it! If you do find issues, please file an issue. Happy hacking!

Welcome Gophers! dcode (pronounced "decode") is a library that gives you a quick and easy way to quickly traverse JSON objects, target a single field, and pull it out into a variable you specify. All using a familiar API.

dcode tries to help you with these two cases in your everyday programming life:

  1. When you don't know the "shape" of the JSON coming into your program
  2. When you know there's a huge JSON object coming in, but you only need to get a few values out of it

To accomplish the first case without dcode, you'd usually decode the JSON into a map[string]interface{}, and then deal with the untyped interface{} values as you traverse your way down into the map to get the value you want.

To accomplish the second case without dcode, you'd usually write a bunch of structs so you can decode the values you want (one per "level" in the JSON).

Ok, Tell Me More!

We're going to focus on the "let's decode big JSON objects" use case in this section.

Let's say you're a weather buff, and you want to write some Go to get the forecast from Dark Sky using their API. Awesome!

Here's part of a JSON response from Dark Sky's API (adapted from their docs page):

    "latitude": 42.3601,
    "longitude": -71.0589,
    "timezone": "America/New_York",
    "minutely": {
        "summary": "Light rain stopping in 13 min., starting again 30 min. later.",
        "icon": "rain",
        "data": {
            "time": 1509993240,
            "precipIntensity": 0.007,
            "precipIntensityError": 0.004,
            "precipProbability": 0.84,
            "precipType": "rain"

Let's try to get the precipitation probability and type so we can print out "84% chance of rain."

Let's Decode This With encoding/json

The most common way you decode JSON using encoding/json is to decode a []byte into a struct. Here's what the struct for this JSON response would look like:

type minutelyResp struct {
    precipType string `json:"precipType"`
    precipProbability float64 `json:"precipProbability"`

type forecast struct {
    minutely minutelyResp `json:"minutely"`

Then, here's how we'd decode the struct:

fcast := new(forecast)
// TODO: deal with the error!
json.Unmarshal(jsonBytes, fcast)

Not terrible, but it's a little boilerplate-ey just to get a string and a float64 out of this response. If there were values nested even deeper, we'd have to write more structs to get them.

Note: If you have to start grabbing a ton more data from the API response JSON, it might make sense to fill out the struct more and grab the data you need.

Let's Decode The Same JSON With dcode

We can decode the same JSON with a little bit less boilerplate, and be clearer about the JSON we're trying to get!

To start, here's how we'd use dcode to do the same decoding:

typeDecoder := First("minutely").Then("precipType").Into(String())
probDecoder := First("minutely").Then("precipProbability").Into(Float64())
var precipType string
var prob float64
// TODO: deal with the errors here!
Decode(typeDecoder, jsonBytes, &precipType) 
Decode(probDecoder, jsonBytes, &prob)

It looks a fair bit different than the previous example with encoding/json. How is this different? Why is it better? Here are some answers for you:

  • No boilerplate structs to write. Hooray!
  • You target just the fields you want. No more mistakes with struct tags 🔥
  • You write how to traverse the returned JSON rather than the complete structure you expect. Don't fail because some other field came in slightly differently than you expeced
  • Your parsing code tends to be more self-documenting. It almost looks like JSONPath!
  • You can reuse those *Decoder values as many times as you want, against any []byte, without creating any new structs or allocating any new memory

Interesting, Right?

Check out for more details, and enjoy!


This library follows patterns from the Elm language JSON decoding library.

I love that language, and I think their JSON decoder is really well designed. The described the benefits to their decoder pattern in their documenation, and I slighly adapted what they wrote here 😉:

Fun Fact: I have heard a bunch of stories of folks finding bugs in their server code as they switched from JS encoding/json to Elm dcode. The decoders people write end up working as a validation phase, catching weird stuff in JSON values. So when NoRedInk you switched from React encoding/json to Elm dcode, it revealed a couple bugs in their Ruby server code!

You can’t perform that action at this time.