json.Unmarshal() accepts a pointer to a pointer

I noticed, quite by accident, that I can successfully pass both a pointer to a struct, and a pointer to a pointer to a struct to json.Unmarshal(), and both work just fine:

package main

import (
	"testing"
	"encoding/json"
)
    
type Person struct {
	Name string
	Age  int
}

func TestMarshaling(t *testing.T) {
	foo := &Person{Name: "bob", Age: 23}

	// marshal it to bytes
	b, err := json.Marshal(foo)
	if err != nil {
		t.Error(err)
	}

	bar := &Person{}             // pointer to new, empty struct
   	err = json.Unmarshal(b, bar) // unmarshal to bar, which is a *Person
	if err != nil {
		t.Error(err)
	}
	testBob(t, bar)  // ok

   	bar = &Person{}               // pointer to new, empty struct
	err = json.Unmarshal(b, &bar) // wait a minute, passing in a **Person, yet it still works?
	if err != nil {
		t.Error(err)
	}
	testBob(t, bar) // ok
}

func testBob(t *testing.T, person *Person) {
	if person.Name != "bob" || person.Age != 23 {
		t.Error("not equal")
	}
}

I was really surprised that the second one (unmarshal to **Person) worked.

What's going on in json.Unmarshal()? Is it dereferencing the pointers until it finds a struct?

The documentation offers:

> To unmarshal JSON into a pointer, Unmarshal first handles the case of
> the JSON being the JSON literal null. In that case, Unmarshal sets
> the pointer to nil. Otherwise, Unmarshal unmarshals the JSON into the
> value pointed at by the pointer

It seems to be doing a bit more than that. What's really going on?

Fleshing out my question more: how does it know to automatically dereference my pointer to a pointer? The documentation says it will unmarshal "into the value pointed at by the pointer". Since the value of my pointer is in fact another pointer, and has no Name/Age fields, I expected it to stop there.

To be clear: I'm not saying there's a bug or misfeature in Unmarshal(); I'm trying to satisfy my astonishment that it works at all when given a ptr-to-ptr, and avoid any potential pitfalls in my use of it.

The json package has no reason to "stop at a pointer", since a pointer means nothing in json. It has to keep walking the tree in order to find a value to write. Since the json package is going to allow unmarshaling the same value into Type or *Type, it stands to reason that it should be able to unmarshal that into **Type, which is also a valid type in Go.

For a example, if Person were defined using pointers to differentiate between nil and zero values, and you were unmarshaling into a slice of []*Person, the json package needs to follow those pointers, and allocate values if necessary. The same applies if a field in Person were defined as a **string.

type Person struct {
    Name **string
    Age  *int
}

type People []*Person

http://play.golang.org/p/vLq0nJPG5M

The json.Unmarshal implementation takes multiple indirection into account. Check the source here, in particular the decodeState.indirect method:

// indirect walks down v allocating pointers as needed,
// until it gets to a non-pointer.
// if it encounters an Unmarshaler, indirect stops and returns that.
// if decodingNull is true, indirect stops at the last pointer so it can be set to nil.
func (d *decodeState) indirect(v reflect.Value, decodingNull bool) (Unmarshaler, encoding.TextUnmarshaler, reflect.Value) {
    // If v is a named type and is addressable,
    // start with its address, so that if the type has pointer methods,
    // we find them.
    if v.Kind() != reflect.Ptr && v.Type().Name() != "" && v.CanAddr() {
        v = v.Addr()
    }
    for {
        if v.Kind() == reflect.Interface && !v.IsNil() {
            e := v.Elem()
            if e.Kind() == reflect.Ptr && !e.IsNil() && (!decodingNull || e.Elem().Kind() == reflect.Ptr) {
                v = e
                continue
            }
        }

        if v.Kind() != reflect.Ptr {
            break
        }
        //and so on
    }
return nil, nil, v

The same method is called when unmarshaling arrays:

func (d *decodeState) array(v reflect.Value) {
    u, ut, pv := d.indirect(v, false)
    //...

That would have me believe that go can handle double indirection just fine. If nothing else, the json package source is a great example of what the reflect package is all about.

In short, values are checked, if the decoder is dealing with pointers, it will use reflection to work out how many levels of indirection there are, and determine what type the target has/is. The place to start from in the decode source is this: func (d *decodeState) unmarshal(v interface{}) (err error) {, from that point on, it's pretty self-explanatory.

As other answers have said, pointers are followed.

A little weird that this errors (nil pointer), but makes sense when you think about it.

package main

import (
    "encoding/json"
    "fmt"
    "log"
)

type MyStruct struct {
    A string `json:"a"`
}

func main() {
    data := []byte(`{"a":"foo"}`)
    var a *MyStruct
    err := json.Unmarshal(data, a)  // nil ptr
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(a)
}

But this doesn't error (pointer to nil pointer).

package main

import (
    "encoding/json"
    "fmt"
    "log"
)

type MyStruct struct {
    A string `json:"a"`
}

func main() {
    data := []byte(`{"a":"foo"}`)
    var a *MyStruct
    err := json.Unmarshal(data, &a) // **MyStruct, ptr to nil ptr
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(a)
}

https://play.golang.org/p/eI8jqWZOmGW