encoding/json

$ go env GOEXPERIMENT

$ GOEXPERIMENT=nojsonv2 go env GOEXPERIMENT
nojsonv2
$ GOEXPERIMENT=jsonv2 go env GOEXPERIMENT
jsonv2
$ go list -f '{{.GoFiles}}' encoding/json
[v2_decode.go v2_encode.go v2_indent.go v2_inject.go v2_options.go v2_scanner.go v2_stream.go]
$ GOEXPERIMENT=nojsonv2 go list -f '{{.GoFiles}}' encoding/json
[decode.go encode.go fold.go indent.go scanner.go stream.go tables.go tags.go]

package main

import (
	"encoding/json"
	"fmt"
)

type Book struct {
	Title string `json:"title"`
	Pages int    `json:"pages"`
}

func main() {
	fmt.Println("implementation:", implementation)

	inputs := []string{
		`{"title": "A", "pages": }`,
		`{"title":"A","pages":"many"}`,
		`{"title":"A"`,
		`{"title":"A\x"}`,
		`[1,2]`,
	}
	for _, in := range inputs {
		var b Book
		fmt.Printf("%-30s %v\n", in, json.Unmarshal([]byte(in), &b))
	}

	_, err := json.Marshal(map[bool]int{true: 1})
	fmt.Println("marshal:", err)
}

//go:build goexperiment.jsonv2

package main

// implementation reports which engine backs encoding/json in this build.
const implementation = "v2 engine (default in Go 1.27)"

//go:build !goexperiment.jsonv2

package main

const implementation = "original v1 engine (GOEXPERIMENT=nojsonv2)"

implementation: v2 engine (default in Go 1.27)
{"title": "A", "pages": }      invalid character '}' looking for beginning of value
{"title":"A","pages":"many"}   json: cannot unmarshal string into Go struct field Book.pages of type int
{"title":"A"                   unexpected end of JSON input
{"title":"A\x"}                invalid escape sequence `\x` in string
[1,2]                          json: cannot unmarshal array into Go value of type main.Book
marshal: json: unsupported value: jsontext: object member name must be a string after offset 2

$ GOEXPERIMENT=nojsonv2 go run ./e12
implementation: original v1 engine (GOEXPERIMENT=nojsonv2)
{"title": "A", "pages": }      invalid character '}' looking for beginning of value
{"title":"A","pages":"many"}   json: cannot unmarshal string into Go struct field Book.pages of type int
{"title":"A"                   unexpected end of JSON input
{"title":"A\x"}                invalid character 'x' in string escape code
[1,2]                          json: cannot unmarshal array into Go value of type main.Book
marshal: json: unsupported type: map[bool]int

package main

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

func main() {
	b, err := json.Marshal(map[string]int{"a": 1})
	fmt.Println(string(b), err)
}

$ GOEXPERIMENT=nojsonv2 go build ./e13
package example.com/shelf/e13
	imports encoding/json/v2: build constraints exclude all Go files in /Users/albertoirurueta/sdk/go1.27.2/src/encoding/json/v2

package main

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

type Author struct {
	Name string `json:"name"`
}

type Book struct {
	ISBN    string   `json:"isbn"`
	Title   string   `json:"title"`
	Authors []Author `json:"authors"`
	Pages   int      `json:"pages"`
	Free    bool     `json:"free"`
}

func main() {
	b := Book{
		ISBN:    "9780134190440",
		Title:   "The Go Programming Language",
		Authors: []Author{{"Alan A. A. Donovan"}, {"Brian W. Kernighan"}},
		Pages:   380,
	}

	data, err := json.Marshal(b)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(data))

	pretty, err := json.MarshalIndent(b, "", "  ")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(pretty))

	var back Book
	if err := json.Unmarshal(data, &back); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", back)

	// Unmarshal needs a non-nil pointer.
	err = json.Unmarshal(data, (*Book)(nil))
	fmt.Println(err)
}

{"isbn":"9780134190440","title":"The Go Programming Language","authors":[{"name":"Alan A. A. Donovan"},{"name":"Brian W. Kernighan"}],"pages":380,"free":false}
{
  "isbn": "9780134190440",
  "title": "The Go Programming Language",
  "authors": [
    {
      "name": "Alan A. A. Donovan"
    },
    {
      "name": "Brian W. Kernighan"
    }
  ],
  "pages": 380,
  "free": false
}
{ISBN:9780134190440 Title:The Go Programming Language Authors:[{Name:Alan A. A. Donovan} {Name:Brian W. Kernighan}] Pages:380 Free:false}
json: Unmarshal(nil *main.Book)

	var b Book
	data := []byte(`{"id":"1"}`)
	err := json.Unmarshal(data, b) // should be &b

e23/main.go:10:2: struct field Title repeats json tag "id" also at main.go:9
e23/main.go:16:23: call of Unmarshal passes non-pointer as second argument
json: Unmarshal(non-pointer main.Book)

package main

import (
	"encoding/json"
	"fmt"
	"math"
	"time"
)

type Sample struct {
	Raw   []byte           `json:"raw"`
	When  time.Time        `json:"when"`
	Ptr   *string          `json:"ptr"`
	Any   any              `json:"any"`
	Ints  map[int]string   `json:"ints"`
	Arr   [2]bool          `json:"arr"`
	Nest  map[string][]int `json:"nest"`
	Float float64          `json:"float"`
}

func main() {
	s := Sample{
		Raw:   []byte("go"),
		When:  time.Date(2026, 10, 18, 9, 30, 0, 0, time.UTC),
		Any:   []any{1, "two", nil},
		Ints:  map[int]string{2: "b", 10: "a", 1: "c"},
		Nest:  map[string][]int{"z": {1}, "a": nil},
		Float: 1e21,
	}
	data, err := json.Marshal(s)
	fmt.Println(string(data), err)

	for _, v := range []any{math.NaN(), make(chan int), func() {}, map[bool]int{true: 1}} {
		_, err := json.Marshal(v)
		fmt.Printf("%T: %v\n", v, err)
	}

	html, _ := json.Marshal("<b>Tom & Jerry</b>
")
	fmt.Println(string(html))
}

{"raw":"Z28=","when":"2026-10-18T09:30:00Z","ptr":null,"any":[1,"two",null],"ints":{"1":"c","10":"a","2":"b"},"arr":[false,false],"nest":{"a":null,"z":[1]},"float":1e+21} <nil>
float64: json: unsupported value: NaN
chan int: json: unsupported type: chan int
func(): json: unsupported type: func()
map[bool]int: json: unsupported value: jsontext: object member name must be a string after offset 2
"\u003cb\u003eTom \u0026 Jerry\u003c/b\u003e\u2028"

package main

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

type Audit struct {
	CreatedBy string `json:"created_by"`
}

type Loan struct {
	Audit              // embedded: fields are promoted into the object
	Book     string    `json:"book"`
	Member   string    `json:"member"`
	Renewals int       `json:"renewals,omitempty"`
	Returned time.Time `json:"returned,omitzero"`
	Fine     int64     `json:"fine,string"`
	Notes    []string  `json:"notes,omitempty"`
	Internal string    `json:"-"`
	Dash     string    `json:"-,"`
	private  string
	NoTag    bool
	Ptr      *int      `json:"ptr"`
	OmitPtr  *int      `json:"omit_ptr,omitempty"`
	ZeroTime time.Time `json:"zero_time_omitempty,omitempty"`
}

func main() {
	l := Loan{
		Audit:    Audit{CreatedBy: "desk-1"},
		Book:     "9780134190440",
		Member:   "m-42",
		Fine:     250,
		Internal: "never written",
		Dash:     "literal dash name",
		private:  "unexported",
		Notes:    []string{},
	}
	data, err := json.MarshalIndent(l, "", "  ")
	fmt.Println(string(data), err)
}

{
  "created_by": "desk-1",
  "book": "9780134190440",
  "member": "m-42",
  "fine": "250",
  "-": "literal dash name",
  "NoTag": false,
  "ptr": null,
  "zero_time_omitempty": "0001-01-01T00:00:00Z"
} <nil>

package main

import (
	"encoding/json"
	jsonv2 "encoding/json/v2"
	"fmt"
)

type Book struct {
	ISBN  string `json:"id"`
	Title string `json:"id"`
}

func main() {
	b := Book{"1", "Go"}
	data, err := json.Marshal(b)
	fmt.Println(string(data), err)
	data, err = jsonv2.Marshal(b)
	fmt.Println(string(data), err)
	type Bad struct {
		N int             `json:"n,omitEmpty"`
		S struct{ X int } `json:"s,string"`
	}
	data, err = json.Marshal(Bad{})
	fmt.Println(string(data), err)
	data, err = jsonv2.Marshal(Bad{})
	fmt.Println(string(data), err)
}

e24/main.go:11:2: struct field Title repeats json tag "id" also at main.go:10

{} <nil>
 json: cannot marshal from Go main.Book: Go struct fields ISBN and Title conflict over JSON object name "id"
{"n":0,"s":{"X":0}} <nil>
 json: cannot marshal from Go main.Bad: Go struct field N has invalid appearance of `omitEmpty` tag option; specify `omitempty` instead

package main

import (
	"encoding/json"
	"fmt"
)

type Member struct {
	Name string `json:"name"`
	Age  *int   `json:"age,omitempty"` // nil means "not known"
}

func main() {
	// new(expr) is Go 1.26: it allocates a variable initialised to the value.
	known, _ := json.Marshal(Member{Name: "Ada", Age: new(36)})
	unknown, _ := json.Marshal(Member{Name: "Alan"})
	fmt.Println(string(known), string(unknown))

	var m Member
	_ = json.Unmarshal([]byte(`{"name":"Grace","age":0}`), &m)
	fmt.Println(*m.Age)
}

{"name":"Ada","age":36} {"name":"Alan"}
0

package main

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

func main() {
	const doc = `{"isbn":"9780134190440","copies":3,"id":9007199254740993,"tags":["go","json"],"meta":{"ok":true},"gone":null}`

	var v any
	if err := json.Unmarshal([]byte(doc), &v); err != nil {
		fmt.Println(err)
		return
	}
	m := v.(map[string]any)
	for _, k := range []string{"isbn", "copies", "id", "tags", "meta", "gone"} {
		fmt.Printf("%-6s %-16T %v\n", k, m[k], m[k])
	}

	// UseNumber keeps the digits as a json.Number string.
	dec := json.NewDecoder(strings.NewReader(doc))
	dec.UseNumber()
	var w map[string]any
	if err := dec.Decode(&w); err != nil {
		fmt.Println(err)
		return
	}
	id := w["id"].(json.Number)
	n, err := id.Int64()
	fmt.Println("json.Number:", id, n, err)
	_, err = w["copies"].(json.Number).Float64()
	fmt.Println("as float:", err)

	// A concrete int64 field keeps all digits without UseNumber.
	var s struct {
		ID int64 `json:"id"`
	}
	_ = json.Unmarshal([]byte(doc), &s)
	fmt.Println("int64 field:", s.ID)
}

isbn   string           9780134190440
copies float64          3
id     float64          9.007199254740992e+15
tags   []interface {}   [go json]
meta   map[string]interface {} map[ok:true]
gone   <nil>            <nil>
json.Number: 9007199254740993 9007199254740993 <nil>
as float: <nil>
int64 field: 9007199254740993

type Marshaler interface {
	MarshalJSON() ([]byte, error)
}

type Unmarshaler interface {
	UnmarshalJSON([]byte) error
}

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"strings"
)

// ISBN validates its input while decoding.
type ISBN string

var ErrInvalidISBN = errors.New("invalid ISBN")

func (i *ISBN) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	d := strings.ReplaceAll(s, "-", "")
	if len(d) != 13 {
		return fmt.Errorf("%w: %q", ErrInvalidISBN, s)
	}
	*i = ISBN(d)
	return nil
}

func (i ISBN) MarshalJSON() ([]byte, error) {
	s := string(i)
	if len(s) == 13 {
		s = s[:3] + "-" + s[3:]
	}
	return json.Marshal(s)
}

// LoanState is written as text, so it also works as a map key.
type LoanState int

const (
	Available LoanState = iota
	OnLoan
	Overdue
)

var stateNames = [...]string{"available", "on_loan", "overdue"}

func (s LoanState) MarshalText() ([]byte, error) {
	if int(s) < 0 || int(s) >= len(stateNames) {
		return nil, fmt.Errorf("unknown loan state %d", int(s))
	}
	return []byte(stateNames[s]), nil
}

func (s *LoanState) UnmarshalText(b []byte) error {
	for i, n := range stateNames {
		if n == string(b) {
			*s = LoanState(i)
			return nil
		}
	}
	return fmt.Errorf("unknown loan state %q", b)
}

type Loan struct {
	Book  ISBN      `json:"book"`
	State LoanState `json:"state"`
}

func main() {
	l := Loan{Book: "9780134190440", State: OnLoan}
	data, err := json.Marshal(l)
	fmt.Println(string(data), err)

	var back Loan
	err = json.Unmarshal([]byte(`{"book":"978-0-13-419044-0","state":"overdue"}`), &back)
	fmt.Println(back, err)

	err = json.Unmarshal([]byte(`{"book":"12","state":"overdue"}`), &back)
	fmt.Println(err, errors.Is(err, ErrInvalidISBN))

	err = json.Unmarshal([]byte(`{"book":"9780134190440","state":"lost"}`), &back)
	fmt.Println(err)

	counts := map[LoanState]int{OnLoan: 2, Overdue: 1}
	data, err = json.Marshal(counts)
	fmt.Println(string(data), err)
}

{"book":"978-0134190440","state":"on_loan"} <nil>
{9780134190440 2} <nil>
invalid ISBN: "12" true
unknown loan state "lost"
{"on_loan":2,"overdue":1} <nil>

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"time"
)

// Member fills in defaults while decoding, by decoding into an alias
// type that has no UnmarshalJSON method of its own.
type Member struct {
	Name  string `json:"name"`
	Limit int    `json:"limit"`
}

func (m *Member) UnmarshalJSON(b []byte) error {
	type plain Member // same fields, none of the methods
	p := plain{Limit: 5}
	if err := json.Unmarshal(b, &p); err != nil {
		return err
	}
	*m = Member(p)
	return nil
}

// Date is a calendar date written as 2006-01-02. The embedded time.Time
// promotes IsZero, which is the method omitzero asks.
type Date struct{ time.Time }

func (d Date) MarshalJSON() ([]byte, error) {
	return json.Marshal(d.Format(time.DateOnly))
}

func (d *Date) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	t, err := time.Parse(time.DateOnly, s)
	d.Time = t
	return err
}

type Loan struct {
	Book string `json:"book"`
	Due  Date   `json:"due,omitzero"`
}

func main() {
	var m Member
	err := json.Unmarshal([]byte(`{"name":"Ada"}`), &m)
	fmt.Printf("%+v %v\n", m, err)

	data, err := json.Marshal(Loan{Book: "1", Due: Date{time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)}})
	fmt.Println(string(data), err)
	data, err = json.Marshal(Loan{Book: "1"})
	fmt.Println(string(data), err)

	var l Loan
	err = json.Unmarshal([]byte(`{"book":"2","due":"2026-13-45"}`), &l)
	fmt.Println(err)

	// Helpers that work on bytes.
	src := []byte(`{ "title" : "R&D <v2>" , "tags":[ "a" , "b" ] }`)
	fmt.Println(json.Valid(src), json.Valid([]byte(`{"a":}`)))

	var buf bytes.Buffer
	_ = json.Compact(&buf, src)
	fmt.Println(buf.String())

	buf.Reset()
	_ = json.Indent(&buf, src, ">", "  ")
	fmt.Println(buf.String())

	buf.Reset()
	json.HTMLEscape(&buf, []byte(`{"t":"<b>&</b>"}`))
	fmt.Println(buf.String())
}

{Name:Ada Limit:5} <nil>
{"book":"1","due":"2026-11-01"} <nil>
{"book":"1"} <nil>
parsing time "2026-13-45": month out of range
true false
{"title":"R&D <v2>","tags":["a","b"]}
{
>  "title": "R&D <v2>",
>  "tags": [
>    "a",
>    "b"
>  ]
>}
{"t":"\u003cb\u003e\u0026\u003c/b\u003e"}

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

type Book struct {
	ISBN  string `json:"isbn"`
	Title string `json:"title"`
}

func main() {
	// 1. Newline-delimited values: Decode returns io.EOF at the end.
	const lines = `{"isbn":"1","title":"A"}
{"isbn":"2","title":"B"}
{"isbn":"3","title":"C"}
`
	dec := json.NewDecoder(strings.NewReader(lines))
	for {
		var b Book
		err := dec.Decode(&b)
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			fmt.Println("error:", err)
			return
		}
		fmt.Printf("%+v (offset %d)\n", b, dec.InputOffset())
	}

	// 2. Reject unknown fields.
	strict := json.NewDecoder(strings.NewReader(`{"isbn":"1","title":"A","pages":9}`))
	strict.DisallowUnknownFields()
	var b Book
	fmt.Println("unknown:", strict.Decode(&b))

	// 3. Stream a big array one element at a time.
	arr := json.NewDecoder(strings.NewReader(`[{"isbn":"1","title":"A"},{"isbn":"2","title":"B"}]`))
	tok, err := arr.Token()
	fmt.Printf("%T %v %v\n", tok, tok, err)
	for arr.More() {
		var b Book
		if err := arr.Decode(&b); err != nil {
			fmt.Println(err)
			return
		}
		fmt.Println("element:", b.Title)
	}
	tok, err = arr.Token()
	fmt.Printf("%T %v %v\n", tok, tok, err)

	// 4. Encoder: one value per call, newline added, indentation and HTML escaping configurable.
	enc := json.NewEncoder(os.Stdout)
	enc.SetEscapeHTML(false)
	enc.SetIndent("", "\t")
	if err := enc.Encode(Book{"3", "R&D <draft>"}); err != nil {
		fmt.Println(err)
	}
}

{ISBN:1 Title:A} (offset 24)
{ISBN:2 Title:B} (offset 49)
{ISBN:3 Title:C} (offset 74)
unknown: json: unknown field "pages"
json.Delim [ <nil>
element: A
element: B
json.Delim ] <nil>
{
	"isbn": "3",
	"title": "R&D <draft>"
}

package main

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

type Book struct {
	Title string `json:"title"`
	Pages int    `json:"pages"`
}

func main() {
	var b Book

	err := json.Unmarshal([]byte(`{"title": "A", "pages": }`), &b)
	var se *json.SyntaxError
	if errors.As(err, &se) {
		fmt.Printf("syntax error at offset %d: %v\n", se.Offset, se)
	}

	err = json.Unmarshal([]byte(`{"title":"A","pages":"many"}`), &b)
	var te *json.UnmarshalTypeError
	if errors.As(err, &te) {
		fmt.Printf("type error: value=%s type=%v field=%q offset=%d\n", te.Value, te.Type, te.Field, te.Offset)
		fmt.Println(err)
	}
	fmt.Printf("partial result still filled: %+v\n", b)

	var missing *Book
	err = json.Unmarshal([]byte(`{}`), missing)
	var ie *json.InvalidUnmarshalError
	fmt.Println(errors.As(err, &ie), err)

	fmt.Println(json.Valid([]byte(`{"a":1}`)), json.Valid([]byte(`{a:1}`)))
}

syntax error at offset 25: invalid character '}' looking for beginning of value
type error: value=string type=int field="pages" offset=27
json: cannot unmarshal string into Go struct field Book.pages of type int
partial result still filled: {Title:A Pages:0}
true json: Unmarshal(nil *main.Book)
true false

package main

import (
	"encoding/json"
	"fmt"
)

type Event struct {
	Type string          `json:"type"`
	Data json.RawMessage `json:"data"`
}

type Borrowed struct {
	Member string `json:"member"`
	Book   string `json:"book"`
}

type Returned struct {
	Book string `json:"book"`
	Late bool   `json:"late"`
}

func decode(raw string) {
	var e Event
	if err := json.Unmarshal([]byte(raw), &e); err != nil {
		fmt.Println("envelope:", err)
		return
	}
	switch e.Type {
	case "borrowed":
		var b Borrowed
		err := json.Unmarshal(e.Data, &b)
		fmt.Printf("%s: %+v %v\n", e.Type, b, err)
	case "returned":
		var r Returned
		err := json.Unmarshal(e.Data, &r)
		fmt.Printf("%s: %+v %v\n", e.Type, r, err)
	default:
		fmt.Printf("unknown event %q, payload kept as %s\n", e.Type, e.Data)
	}
}

func main() {
	decode(`{"type":"borrowed","data":{"member":"m-42","book":"9780134190440"}}`)
	decode(`{"type":"returned","data":{"book":"9780134190440","late":true}}`)
	decode(`{"type":"reserved","data":  [1, 2,   3]}`)

	// RawMessage marshals as-is, but must be valid JSON.
	out, err := json.Marshal(Event{Type: "x", Data: json.RawMessage(`{"a":1}`)})
	fmt.Println(string(out), err)
	_, err = json.Marshal(Event{Type: "x", Data: json.RawMessage(`{a:1}`)})
	fmt.Println(err)
}

borrowed: {Member:m-42 Book:9780134190440} <nil>
returned: {Book:9780134190440 Late:true} <nil>
unknown event "reserved", payload kept as [1, 2,   3]
{"type":"x","data":{"a":1}} <nil>
json: error calling MarshalJSON for type *jsontext.Value: invalid character 'a' looking for beginning of object key string

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"strings"
)

type Book struct {
	ISBN  string `json:"isbn"`
	Title string `json:"title"`
}

func decodeBody(w http.ResponseWriter, r *http.Request, dst any) error {
	r.Body = http.MaxBytesReader(w, r.Body, 1<<10)
	dec := json.NewDecoder(r.Body)
	dec.DisallowUnknownFields()
	if err := dec.Decode(dst); err != nil {
		return err
	}
	// A second Decode must hit EOF, otherwise there is trailing data.
	if err := dec.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
		return errors.New("body must contain a single JSON value")
	}
	return nil
}

func addBook(w http.ResponseWriter, r *http.Request) {
	var b Book
	if err := decodeBody(w, r, &b); err != nil {
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	if err := json.NewEncoder(w).Encode(b); err != nil {
		// Headers are sent; all we can do is log.
		fmt.Println("write:", err)
	}
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /books", addBook)

	for _, body := range []string{
		`{"isbn":"1","title":"A"}`,
		`{"isbn":"1","title":"A","extra":true}`,
		`{"isbn":"1","title":"A"} {"x":1}`,
		`{"isbn":`,
		`{"isbn":"` + strings.Repeat("x", 2000) + `"}`,
	} {
		rec := httptest.NewRecorder()
		req := httptest.NewRequest("POST", "/books", strings.NewReader(body))
		mux.ServeHTTP(rec, req)
		out := strings.TrimSpace(rec.Body.String())
		if len(out) > 70 {
			out = out[:70] + "..."
		}
		fmt.Printf("%d %s\n", rec.Code, out)
	}
}

201 {"isbn":"1","title":"A"}
400 json: unknown field "extra"
400 body must contain a single JSON value
400 unexpected EOF
400 http: request body too large

package main

import (
	"bytes"
	"encoding/json/jsontext"
	"encoding/json/v2"
	"errors"
	"fmt"
	"strings"
)

type Book struct {
	ISBN  string   `json:"isbn"`
	Title string   `json:"title"`
	Tags  []string `json:"tags"`
	Pages int      `json:"pages,omitzero"`
}

func main() {
	b := Book{ISBN: "9780134190440", Title: "The Go Programming Language"}

	data, err := json.Marshal(b)
	fmt.Println(string(data), err)

	// Options are variadic and can be joined.
	data, err = json.Marshal(b,
		json.FormatNilSliceAsNull(true),
		jsontext.Multiline(true),
		jsontext.WithIndent("  "))
	fmt.Println(string(data), err)

	// Streaming: MarshalWrite and UnmarshalRead.
	var buf bytes.Buffer
	if err := json.MarshalWrite(&buf, b, json.Deterministic(true)); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(buf.String())

	var back Book
	err = json.UnmarshalRead(&buf, &back)
	fmt.Printf("%+v %v\n", back, err)

	// Strictness: reject unknown members.
	err = json.Unmarshal([]byte(`{"isbn":"1","colour":"red"}`), &back, json.RejectUnknownMembers(true))
	fmt.Println(err, errors.Is(err, json.ErrUnknownName))

	// The error carries the JSON Pointer of the offending value.
	err = json.Unmarshal([]byte(`{"isbn":"1","tags":["a",7]}`), &back)
	var se *json.SemanticError
	if errors.As(err, &se) {
		fmt.Println(se.JSONPointer, se.JSONKind, se.GoType, "|", err)
	}

	// Compare with the first byte on a reader that holds two values.
	err = json.UnmarshalRead(strings.NewReader(`{"isbn":"1"} {"isbn":"2"}`), &back)
	fmt.Println(err)
}

{"isbn":"9780134190440","title":"The Go Programming Language","tags":[]} <nil>
{
  "isbn": "9780134190440",
  "title": "The Go Programming Language",
  "tags": null
} <nil>
{"isbn":"9780134190440","title":"The Go Programming Language","tags":[]}
{ISBN:9780134190440 Title:The Go Programming Language Tags:[] Pages:0} <nil>
json: cannot unmarshal JSON string into Go main.Book: unknown object member name "colour" true
/tags/1 number string | json: cannot unmarshal JSON number into Go string within "/tags/1"
jsontext: invalid character '{' after top-level value after offset 13

package main

import (
	"encoding/json/jsontext"
	"encoding/json/v2"
	"fmt"
	"time"
)

type Audit struct {
	CreatedBy string `json:"created_by"`
}

type Loan struct {
	Audit
	Book     string    `json:"book"`
	Member   string    `json:"member"`
	Renewals int       `json:"renewals,omitempty"`
	Returned time.Time `json:"returned,omitzero"`
	Fine     int64     `json:"fine,string"`
	Notes    []string  `json:"notes,omitempty"`
	Tags     []string  `json:"tags,omitzero"`
	Internal string    `json:"-"`
	Fixed    string    `json:"fixed,case:strict"`
	Loose    string    `json:"loose_name,case:ignore"`
}

func main() {
	l := Loan{
		Audit:  Audit{CreatedBy: "desk-1"},
		Book:   "9780134190440",
		Member: "m-42",
		Fine:   250,
		Notes:  []string{},
		Tags:   []string{},
	}
	data, err := json.Marshal(l, jsontext.Multiline(true), jsontext.WithIndent("  "))
	fmt.Println(string(data), err)

	// case:ignore ignores case, dashes and underscores; case:strict is the default.
	var back Loan
	err = json.Unmarshal([]byte(`{"FIXED":"x","Loose-Name":"y","BOOK":"z"}`), &back)
	fmt.Printf("%+v %v\n", back, err)

	// The "format" tag option of the 1.25 experiment is gone: it is a marshal error now.
	type Stamp struct {
		At time.Time `json:"at,format:unixmilli"`
	}
	_, err = json.Marshal(Stamp{time.UnixMilli(5000).UTC()})
	fmt.Println(err)
}

{
  "created_by": "desk-1",
  "book": "9780134190440",
  "member": "m-42",
  "renewals": 0,
  "fine": "250",
  "tags": [],
  "fixed": "",
  "loose_name": ""
} <nil>
{Audit:{CreatedBy:} Book: Member: Renewals:0 Returned:0001-01-01 00:00:00 +0000 UTC Fine:0 Notes:[] Tags:[] Internal: Fixed: Loose:y} <nil>
json: cannot marshal from Go main.Stamp: Go struct field At has unsupported `format` tag option

package main

import (
	"encoding/json/jsontext"
	"encoding/json/v2"
	"errors"
	"fmt"
	"strings"
	"time"
)

// Settings keeps members it does not know about instead of dropping them.
type Settings struct {
	Name string         `json:"name"`
	Rest map[string]any `json:",embed"`
}

// Raw keeps the unknown members as raw JSON text.
type Raw struct {
	Name string         `json:"name"`
	Rest jsontext.Value `json:",embed"`
}

// Policy holds a time.Duration, which has no default JSON form in v2.
type Policy struct {
	Name   string        `json:"name"`
	Period time.Duration `json:"period"`
}

// ISBN implements MarshalerTo and UnmarshalerFrom to avoid intermediate allocations.
type ISBN string

func (i ISBN) MarshalJSONTo(enc *jsontext.Encoder) error {
	return enc.WriteToken(jsontext.String(string(i)))
}

func (i *ISBN) UnmarshalJSONFrom(dec *jsontext.Decoder) error {
	tok, err := dec.ReadToken()
	if err != nil {
		return err
	}
	if tok.Kind() != '"' {
		return fmt.Errorf("ISBN must be a JSON string, got %v", tok.Kind())
	}
	s := strings.ReplaceAll(tok.String(), "-", "")
	if len(s) != 13 {
		return fmt.Errorf("invalid ISBN %q", tok.String())
	}
	*i = ISBN(s)
	return nil
}

func main() {
	var s Settings
	err := json.Unmarshal([]byte(`{"name":"desk","theme":"dark","limit":3}`), &s)
	fmt.Printf("%+v %v\n", s, err)
	out, _ := json.Marshal(s, json.Deterministic(true))
	fmt.Println(string(out))

	var r Raw
	err = json.Unmarshal([]byte(`{"name":"desk","theme":"dark","limit":3}`), &r)
	fmt.Printf("%s | %s %v\n", r.Name, r.Rest, err)

	// Per-call marshalers: a function for a type you do not own.
	opts := json.JoinOptions(
		json.WithMarshalers(json.MarshalToFunc(func(enc *jsontext.Encoder, d time.Duration) error {
			return enc.WriteToken(jsontext.String(d.String()))
		})),
		json.WithUnmarshalers(json.UnmarshalFromFunc(func(dec *jsontext.Decoder, d *time.Duration) error {
			tok, err := dec.ReadToken()
			if err != nil {
				return err
			}
			v, err := time.ParseDuration(tok.String())
			*d = v
			return err
		})),
	)
	p := Policy{Name: "loan", Period: 36 * time.Hour}
	out, err = json.Marshal(p, opts)
	fmt.Println(string(out), err)
	var p2 Policy
	err = json.Unmarshal(out, &p2, opts)
	fmt.Printf("%+v %v\n", p2, err)

	// Without the option, Duration has no default representation.
	_, err = json.Marshal(p)
	fmt.Println(err)

	// Methods on the type.
	var ids []ISBN
	err = json.Unmarshal([]byte(`["978-0-13-419044-0","9780134190440"]`), &ids)
	fmt.Println(ids, err)
	out, err = json.Marshal(ids)
	fmt.Println(string(out), err)
	err = json.Unmarshal([]byte(`[1]`), &ids)
	var se *json.SemanticError
	fmt.Println(errors.As(err, &se), err)
}

{Name:desk Rest:map[limit:3 theme:dark]} <nil>
{"name":"desk","limit":3,"theme":"dark"}
desk | {"theme":"dark","limit":3} <nil>
{"name":"loan","period":"36h0m0s"} <nil>
{Name:loan Period:36h0m0s} <nil>
json: cannot marshal from Go time.Duration within "/period": no default representation
[9780134190440 9780134190440] <nil>
["9780134190440","9780134190440"] <nil>
true json: cannot unmarshal into Go main.ISBN within "/0": ISBN must be a JSON string, got number

package main

import (
	"encoding/json"
	jsonv2 "encoding/json/v2"
	"fmt"
	"strings"
	"time"
)

type Book struct {
	Title string   `json:"title"`
	Tags  []string `json:"tags"`
	Meta  map[string]string
	Pages int  `json:"pages,omitempty"`
	Free  bool `json:"free,omitempty"`
}

// Level has a pointer-receiver MarshalJSON.
type Level int

func (l *Level) MarshalJSON() ([]byte, error) { return []byte(`"L` + fmt.Sprint(int(*l)) + `"`), nil }

type Holder struct{ Lv Level }

type Flag struct {
	On bool `json:"on,string"`
}

func show(name string, v1, v2 string) {
	fmt.Printf("%-22s v1: %-48s v2: %s\n", name, v1, v2)
}

func res(b []byte, err error) string {
	if err != nil {
		return "ERROR " + shorten(err.Error())
	}
	return string(b)
}

func shorten(s string) string {
	if len(s) > 70 {
		return s[:70] + "..."
	}
	return s
}

func main() {
	b := Book{Title: "Go"}
	show("nil slice and map", res(json.Marshal(b)), res(jsonv2.Marshal(b)))

	var u1, u2 Book
	e1 := json.Unmarshal([]byte(`{"TITLE":"loud"}`), &u1)
	e2 := jsonv2.Unmarshal([]byte(`{"TITLE":"loud"}`), &u2)
	show("name case", fmt.Sprintf("%q %v", u1.Title, e1), fmt.Sprintf("%q %v", u2.Title, e2))

	u1, u2 = Book{}, Book{}
	e1 = json.Unmarshal([]byte(`{"title":"a","title":"b"}`), &u1)
	e2 = jsonv2.Unmarshal([]byte(`{"title":"a","title":"b"}`), &u2)
	show("duplicate name", fmt.Sprintf("%q %v", u1.Title, e1), fmt.Sprintf("%q %s", u2.Title, shorten(fmt.Sprint(e2))))

	u1, u2 = Book{}, Book{}
	bad := "{\"title\":\"a\xffb\"}"
	e1 = json.Unmarshal([]byte(bad), &u1)
	e2 = jsonv2.Unmarshal([]byte(bad), &u2)
	show("invalid UTF-8", fmt.Sprintf("%+q %v", u1.Title, e1), fmt.Sprintf("%+q %s", u2.Title, shorten(fmt.Sprint(e2))))

	show("duration", res(json.Marshal(time.Second)), res(jsonv2.Marshal(time.Second)))
	show("[2]byte", res(json.Marshal([2]byte{1, 2})), res(jsonv2.Marshal([2]byte{1, 2})))
	show("HTML characters", res(json.Marshal("<a&b>")), res(jsonv2.Marshal("<a&b>")))
	show("pointer receiver", res(json.Marshal(Holder{3})), res(jsonv2.Marshal(Holder{3})))
	show("string tag on bool", res(json.Marshal(Flag{true})), res(jsonv2.Marshal(Flag{true})))
	show("no exported fields", res(json.Marshal(struct{ x int }{1})), res(jsonv2.Marshal(struct{ x int }{1})))

	m := map[string]int{"b": 2, "a": 1, "c": 3}
	show("map key order", res(json.Marshal(m)), res(jsonv2.Marshal(m, jsonv2.Deterministic(true))))

	x1, x2 := Book{Pages: 7}, Book{Pages: 7}
	e1 = json.Unmarshal([]byte(`{"pages":null}`), &x1)
	e2 = jsonv2.Unmarshal([]byte(`{"pages":null}`), &x2)
	show("null into int", fmt.Sprint(x1.Pages, e1), fmt.Sprint(x2.Pages, e2))

	var a1, a2 any
	_ = json.NewDecoder(strings.NewReader(`{"n":1}`)).Decode(&a1)
	_ = jsonv2.Unmarshal([]byte(`{"n":1}`), &a2)
	show("number into any", fmt.Sprintf("%T", a1.(map[string]any)["n"]), fmt.Sprintf("%T", a2.(map[string]any)["n"]))
}

nil slice and map      v1: {"title":"Go","tags":null,"Meta":null}           v2: {"title":"Go","tags":[],"Meta":{},"pages":0,"free":false}
name case              v1: "loud" <nil>                                     v2: "" <nil>
duplicate name         v1: "b" <nil>                                        v2: "a" jsontext: duplicate object member name "title"
invalid UTF-8          v1: "a\ufffdb" <nil>                                 v2: "" jsontext: invalid UTF-8 within "/title" after offset 11
duration               v1: 1000000000                                       v2: ERROR json: cannot marshal from Go time.Duration: no default representation
[2]byte                v1: [1,2]                                            v2: "AQI="
HTML characters        v1: "\u003ca\u0026b\u003e"                           v2: "<a&b>"
pointer receiver       v1: {"Lv":3}                                         v2: {"Lv":"L3"}
string tag on bool     v1: {"on":"true"}                                    v2: ERROR json: cannot marshal from Go bool within "/on": invalid use of `string...
no exported fields     v1: {}                                               v2: ERROR json: cannot marshal from Go struct { x int }: Go struct has no export...
map key order          v1: {"a":1,"b":2,"c":3}                              v2: {"a":1,"b":2,"c":3}
null into int          v1: 7 <nil>                                          v2: 0 <nil>
number into any        v1: float64                                          v2: float64

package main

import (
	"encoding/json/jsontext"
	"encoding/json/v2"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"os"
	"strings"
)

type Book struct {
	ISBN  string `json:"isbn"`
	Title string `json:"title"`
	Pages int    `json:"pages,omitzero"`
}

// readJSON decodes one JSON value from the request body, strictly.
func readJSON(w http.ResponseWriter, r *http.Request, dst any) error {
	r.Body = http.MaxBytesReader(w, r.Body, 1<<10)
	return json.UnmarshalRead(r.Body, dst, json.RejectUnknownMembers(true))
}

func addBook(w http.ResponseWriter, r *http.Request) {
	var b Book
	if err := readJSON(w, r, &b); err != nil {
		var tooBig *http.MaxBytesError
		var syn *jsontext.SyntacticError
		var sem *json.SemanticError
		switch {
		case errors.As(err, &tooBig):
			http.Error(w, "body too large", http.StatusRequestEntityTooLarge)
		case errors.As(err, &syn):
			http.Error(w, "malformed JSON", http.StatusBadRequest)
		case errors.As(err, &sem):
			http.Error(w, fmt.Sprintf("invalid value at %s", sem.JSONPointer), http.StatusUnprocessableEntity)
		default:
			http.Error(w, "unreadable body", http.StatusBadRequest)
		}
		return
	}
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusCreated)
	if err := json.MarshalWrite(w, b); err != nil {
		fmt.Println("write:", err)
	}
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("POST /books", addBook)
	for _, body := range []string{
		`{"isbn":"1","title":"A"}`,
		`{"isbn":"1","title":"A","extra":true}`,
		`{"isbn":"1","title":7}`,
		`{"isbn":"1","title":"A"} {"x":1}`,
		`{"isbn":`,
		`{"isbn":"1","isbn":"2"}`,
		`{"isbn":"` + strings.Repeat("x", 2000) + `"}`,
	} {
		rec := httptest.NewRecorder()
		mux.ServeHTTP(rec, httptest.NewRequest("POST", "/books", strings.NewReader(body)))
		out := strings.TrimSpace(rec.Body.String())
		fmt.Printf("%d %s\n", rec.Code, out)
	}

	// Streaming a large array: one element in memory at a time.
	dec := jsontext.NewDecoder(strings.NewReader(`[{"isbn":"1","title":"a"},{"isbn":"2","title":"b","pages":9}]`))
	if _, err := dec.ReadToken(); err != nil { // [
		fmt.Println(err)
		return
	}
	enc := jsontext.NewEncoder(os.Stdout, jsontext.Multiline(false))
	for dec.PeekKind() != ']' {
		var b Book
		if err := json.UnmarshalDecode(dec, &b); err != nil {
			fmt.Println(err)
			return
		}
		b.Title = strings.ToUpper(b.Title)
		if err := json.MarshalEncode(enc, b); err != nil { // writes one value, then a newline
			fmt.Println(err)
			return
		}
	}
	_, err := dec.ReadToken() // ]
	_, err2 := dec.ReadToken()
	fmt.Println(err, err2 == io.EOF)
}

201 {"isbn":"1","title":"A"}
422 invalid value at /extra
422 invalid value at /title
400 malformed JSON
400 malformed JSON
400 malformed JSON
413 body too large
{"isbn":"1","title":"A"}
{"isbn":"2","title":"B","pages":9}
<nil> true