In Go, why is JSON null sometimes not passed to UnmarshalJSON for decoding?

Go provides the encoding/json.Unmarshaler interface so types can control the way they are decoded from JSON. In almost all cases, the encoded JSON value is passed directly to the UnmarshalJSON method, but not if the Unmarshaler is a pointer and the JSON value is null. In that case, the pointer is set to nil without calling UnmarshalJSON at all. Here's an example:

package main

import (
	"encoding/json"
	"fmt"
)

type T string

func (v *T) UnmarshalJSON(b []byte) error {
	if b[0] == 'n' {
		*v = "null"
	} else {
		*v = "not null"
	}
	return nil
}

func main() {
	var a struct {
		T   T
		PT1 *T
		PT2 *T
	}
	a.PT1 = nil // just to be explicit
	a.PT2 = new(T)
	err := json.Unmarshal([]byte(`{"T":null,"PT1":"foo","PT2":null}`), &a)
	if err != nil {
		panic(err)
	}
	fmt.Printf("a.T is %#v\n", a.T)
	if a.PT1 == nil {
		fmt.Println("a.PT1 is nil")
	} else {
		fmt.Printf("a.PT1 points to %#v\n", *a.PT1)
	}
	if a.PT2 == nil {
		fmt.Println("a.PT2 is nil")
	} else {
		fmt.Printf("a.PT2 points to %#v\n", *a.PT2)
	}
}

I expected this to print

<!-- language: lang-none -->

a.T is "null"
a.PT1 points to "not null"
a.PT2 points to "null"

Instead, it prints

<!-- language: lang-none -->

a.T is "null"
a.PT1 points to "not null"
a.PT2 is nil

So json.Unmarshal allocates a new T for a.PT1, which is initially nil. But it sets a.PT2 to nil without calling UnmarshalJSON, even though a.PT2 was not nil. Why?

This is because setting the pointer to nil is the most common way to handle a JSON null, and there is no way for an UnmarshalJSON method of *T to do that on its own. If UnmarshalJSON were called in this case, you would have to define (**T).UnmarshalJSON to set the *T to nil. This would make the most common case very awkward.

If you don't want JSON null to become Go nil, don't use a pointer.