package json

import "k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"

Package json implements serialization of JSON as specified in RFC 4627, RFC 7159, RFC 7493, RFC 8259, and RFC 8785. JSON is a simple data interchange format that can represent primitive data types such as booleans, strings, and numbers, in addition to structured data types such as objects and arrays.

Terminology

This package uses the terms "encode" and "decode" for syntactic functionality that is concerned with processing JSON based on its grammar, and uses the terms "marshal" and "unmarshal" for semantic functionality that determines the meaning of JSON values as Go values and vice-versa. It aims to provide a clear distinction between functionality that is purely concerned with encoding versus that of marshaling. For example, one can directly encode a stream of JSON tokens without needing to marshal a concrete Go value representing them. Similarly, one can decode a stream of JSON tokens without needing to unmarshal them into a concrete Go value.

This package uses JSON terminology when discussing JSON, which may differ from related concepts in Go or elsewhere in computing literature.

See RFC 8259 for more information.

Specifications

Relevant specifications include RFC 4627, RFC 7159, RFC 7493, RFC 8259, and RFC 8785. Each RFC is generally a stricter subset of another RFC. In increasing order of strictness:

The primary difference between RFC 4627 and RFC 7159 is that the former restricted top-level values to only JSON objects and arrays, while RFC 7159 and subsequent RFCs permit top-level values to additionally be JSON nulls, booleans, strings, or numbers.

By default, this package operates on RFC 7493, but can be configured to operate according to the other RFC specifications. RFC 7493 is a stricter subset of RFC 8259 and fully compliant with it. In particular, it makes specific choices about behavior that RFC 8259 leaves as undefined in order to ensure greater interoperability.

JSON Representation of Go structs

A Go struct is naturally represented as a JSON object, where each Go struct field corresponds with a JSON object member. When marshaling, all Go struct fields are recursively encoded in depth-first order as JSON object members except those that are ignored or omitted. When unmarshaling, JSON object members are recursively decoded into the corresponding Go struct fields. Object members that do not match any struct fields, also known as “unknown members”, are ignored by default or rejected if UnmarshalOptions.RejectUnknownMembers is specified.

The representation of each struct field can be customized in the "json" struct field tag, where the tag is a comma separated list of options. As a special case, if the entire tag is `json:"-"`, then the field is ignored with regard to its JSON representation.

The first option is the JSON object name override for the Go struct field. If the name is not specified, then the Go struct field name is used as the JSON object name. JSON names containing commas or quotes, or names identical to "" or "-", can be specified using a single-quoted string literal, where the syntax is identical to the Go grammar for a double-quoted string literal, but instead uses single quotes as the delimiters. By default, unmarshaling uses case-sensitive matching to identify the Go struct field associated with a JSON object name.

After the name, the following tag options are supported:

The "omitzero" and "omitempty" options are mostly semantically identical. The former is defined in terms of the Go type system, while the latter in terms of the JSON type system. Consequently they behave differently in some circumstances. For example, only a nil slice or map is omitted under "omitzero", while an empty slice or map is omitted under "omitempty" regardless of nilness. The "omitzero" option is useful for types with a well-defined zero value (e.g., netip.Addr) or have an IsZero method (e.g., time.Time).

Every Go struct corresponds to a list of JSON representable fields which is constructed by performing a breadth-first search over all struct fields (excluding unexported or ignored fields), where the search recursively descends into inlined structs. The set of non-inlined fields in a struct must have unique JSON names. If multiple fields all have the same JSON name, then the one at shallowest depth takes precedence and the other fields at deeper depths are excluded from the list of JSON representable fields. If multiple fields at the shallowest depth have the same JSON name, then all of those fields are excluded from the list. This is analogous to Go visibility rules for struct field selection with embedded struct types.

Marshaling or unmarshaling a non-empty struct without any JSON representable fields results in a SemanticError. Unexported fields must not have any `json` tags except for `json:"-"`.

Example (CaseSensitivity)

Unmarshal matches JSON object names with Go struct fields using a case-sensitive match, but can be configured to use a case-insensitive match with the "nocase" option. This permits unmarshaling from inputs that use naming conventions such as camelCase, snake_case, or kebab-case.

Code:play  

package main

import (
	"fmt"
	"log"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// JSON input using various naming conventions.
	const input = `[
		{"firstname": true},
		{"firstName": true},
		{"FirstName": true},
		{"FIRSTNAME": true},
		{"first_name": true},
		{"FIRST_NAME": true},
		{"first-name": true},
		{"FIRST-NAME": true},
		{"unknown": true}
	]`

	// Without "nocase", Unmarshal looks for an exact match.
	var withcase []struct {
		X bool `json:"firstName"`
	}
	if err := json.Unmarshal([]byte(input), &withcase); err != nil {
		log.Fatal(err)
	}
	fmt.Println(withcase) // exactly 1 match found

	// With "nocase", Unmarshal looks first for an exact match,
	// then for a case-insensitive match if none found.
	var nocase []struct {
		X bool `json:"firstName,nocase"`
	}
	if err := json.Unmarshal([]byte(input), &nocase); err != nil {
		log.Fatal(err)
	}
	fmt.Println(nocase) // 8 matches found

}

Output:

[{false} {true} {false} {false} {false} {false} {false} {false} {false}]
[{true} {true} {true} {true} {true} {true} {true} {true} {false}]
Example (FieldNames)

By default, JSON object names for Go struct fields are derived from the Go field name, but may be specified in the `json` tag. Due to JSON's heritage in JavaScript, the most common naming convention used for JSON object names is camelCase.

Code:play  

package main

import (
	"fmt"
	"log"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	var value struct {
		// This field is explicitly ignored with the special "-" name.
		Ignored any `json:"-"`
		// No JSON name is not provided, so the Go field name is used.
		GoName any
		// A JSON name is provided without any special characters.
		JSONName any `json:"jsonName"`
		// No JSON name is not provided, so the Go field name is used.
		Option any `json:",nocase"`
		// An empty JSON name specified using an single-quoted string literal.
		Empty any `json:"''"`
		// A dash JSON name specified using an single-quoted string literal.
		Dash any `json:"'-'"`
		// A comma JSON name specified using an single-quoted string literal.
		Comma any `json:"','"`
		// JSON name with quotes specified using a single-quoted string literal.
		Quote any `json:"'\"\\''"`
		// An unexported field is always ignored.
		unexported any
	}

	b, err := json.Marshal(value)
	if err != nil {
		log.Fatal(err)
	}
	(*json.RawValue)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"GoName": null,
	"jsonName": null,
	"Option": null,
	"": null,
	"-": null,
	",": null,
	"\"'": null
}
Example (FormatFlags)

The "format" tag option can be used to alter the formatting of certain types.

Code:play  

package main

import (
	"fmt"
	"log"
	"math"
	"time"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	value := struct {
		BytesBase64    []byte         `json:",format:base64"`
		BytesHex       [8]byte        `json:",format:hex"`
		BytesArray     []byte         `json:",format:array"`
		FloatNonFinite float64        `json:",format:nonfinite"`
		MapEmitNull    map[string]any `json:",format:emitnull"`
		SliceEmitNull  []any          `json:",format:emitnull"`
		TimeDateOnly   time.Time      `json:",format:'2006-01-02'"`
		DurationNanos  time.Duration  `json:",format:nanos"`
	}{
		BytesBase64:    []byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef},
		BytesHex:       [8]byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef},
		BytesArray:     []byte{0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef},
		FloatNonFinite: math.NaN(),
		MapEmitNull:    nil,
		SliceEmitNull:  nil,
		TimeDateOnly:   time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC),
		DurationNanos:  time.Second + time.Millisecond + time.Microsecond + time.Nanosecond,
	}

	b, err := json.Marshal(&value)
	if err != nil {
		log.Fatal(err)
	}
	(*json.RawValue)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"BytesBase64": "ASNFZ4mrze8=",
	"BytesHex": "0123456789abcdef",
	"BytesArray": [
		1,
		35,
		69,
		103,
		137,
		171,
		205,
		239
	],
	"FloatNonFinite": "NaN",
	"MapEmitNull": null,
	"SliceEmitNull": null,
	"TimeDateOnly": "2000-01-01",
	"DurationNanos": 1001001001
}
Example (InlinedFields)

JSON objects can be inlined within a parent object similar to how Go structs can be embedded within a parent struct. The inlining rules are similar to those of Go embedding, but operates upon the JSON namespace.

Code:play  

package main

import (
	"fmt"
	"log"
	"time"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Base is embedded within Container.
	type Base struct {
		// ID is promoted into the JSON object for Container.
		ID string
		// Type is ignored due to presence of Container.Type.
		Type string
		// Time cancels out with Container.Inlined.Time.
		Time time.Time
	}
	// Other is embedded within Container.
	type Other struct{ Cost float64 }
	// Container embeds Base and Other.
	type Container struct {
		// Base is an embedded struct and is implicitly JSON inlined.
		Base
		// Type takes precedence over Base.Type.
		Type int
		// Inlined is a named Go field, but is explicitly JSON inlined.
		Inlined struct {
			// User is promoted into the JSON object for Container.
			User string
			// Time cancels out with Base.Time.
			Time string
		} `json:",inline"`
		// ID does not conflict with Base.ID since the JSON name is different.
		ID string `json:"uuid"`
		// Other is not JSON inlined since it has an explicit JSON name.
		Other `json:"other"`
	}

	// Format an empty Container to show what fields are JSON serializable.
	var input Container
	b, err := json.Marshal(&input)
	if err != nil {
		log.Fatal(err)
	}
	(*json.RawValue)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"ID": "",
	"Type": 0,
	"User": "",
	"uuid": "",
	"other": {
		"Cost": 0
	}
}
Example (OmitFields)

Go struct fields can be omitted from the output depending on either the input Go value or the output JSON encoding of the value. The "omitzero" option omits a field if it is the zero Go value or implements a "IsZero() bool" method that reports true. The "omitempty" option omits a field if it encodes as an empty JSON value, which we define as a JSON null or empty JSON string, object, or array. In many cases, the behavior of "omitzero" and "omitempty" are equivalent. If both provide the desired effect, then using "omitzero" is preferred.

Code:play  

package main

import (
	"fmt"
	"log"
	"net/netip"
	"time"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	type MyStruct struct {
		Foo string `json:",omitzero"`
		Bar []int  `json:",omitempty"`
		// Both "omitzero" and "omitempty" can be specified together,
		// in which case the field is omitted if either would take effect.
		// This omits the Baz field either if it is a nil pointer or
		// if it would have encoded as an empty JSON object.
		Baz *MyStruct `json:",omitzero,omitempty"`
	}

	// Demonstrate behavior of "omitzero".
	b, err := json.Marshal(struct {
		Bool         bool        `json:",omitzero"`
		Int          int         `json:",omitzero"`
		String       string      `json:",omitzero"`
		Time         time.Time   `json:",omitzero"`
		Addr         netip.Addr  `json:",omitzero"`
		Struct       MyStruct    `json:",omitzero"`
		SliceNil     []int       `json:",omitzero"`
		Slice        []int       `json:",omitzero"`
		MapNil       map[int]int `json:",omitzero"`
		Map          map[int]int `json:",omitzero"`
		PointerNil   *string     `json:",omitzero"`
		Pointer      *string     `json:",omitzero"`
		InterfaceNil any         `json:",omitzero"`
		Interface    any         `json:",omitzero"`
	}{
		// Bool is omitted since false is the zero value for a Go bool.
		Bool: false,
		// Int is omitted since 0 is the zero value for a Go int.
		Int: 0,
		// String is omitted since "" is the zero value for a Go string.
		String: "",
		// Time is omitted since time.Time.IsZero reports true.
		Time: time.Date(1, 1, 1, 0, 0, 0, 0, time.UTC),
		// Addr is omitted since netip.Addr{} is the zero value for a Go struct.
		Addr: netip.Addr{},
		// Struct is NOT omitted since it is not the zero value for a Go struct.
		Struct: MyStruct{Bar: []int{}, Baz: new(MyStruct)},
		// SliceNil is omitted since nil is the zero value for a Go slice.
		SliceNil: nil,
		// Slice is NOT omitted since []int{} is not the zero value for a Go slice.
		Slice: []int{},
		// MapNil is omitted since nil is the zero value for a Go map.
		MapNil: nil,
		// Map is NOT omitted since map[int]int{} is not the zero value for a Go map.
		Map: map[int]int{},
		// PointerNil is omitted since nil is the zero value for a Go pointer.
		PointerNil: nil,
		// Pointer is NOT omitted since new(string) is not the zero value for a Go pointer.
		Pointer: new(string),
		// InterfaceNil is omitted since nil is the zero value for a Go interface.
		InterfaceNil: nil,
		// Interface is NOT omitted since (*string)(nil) is not the zero value for a Go interface.
		Interface: (*string)(nil),
	})
	if err != nil {
		log.Fatal(err)
	}
	(*json.RawValue)(&b).Indent("", "\t") // indent for readability
	fmt.Println("OmitZero:", string(b))   // outputs "Struct", "Slice", "Map", "Pointer", and "Interface"

	// Demonstrate behavior of "omitempty".
	b, err = json.Marshal(struct {
		Bool         bool        `json:",omitempty"`
		Int          int         `json:",omitempty"`
		String       string      `json:",omitempty"`
		Time         time.Time   `json:",omitempty"`
		Addr         netip.Addr  `json:",omitempty"`
		Struct       MyStruct    `json:",omitempty"`
		Slice        []int       `json:",omitempty"`
		Map          map[int]int `json:",omitempty"`
		PointerNil   *string     `json:",omitempty"`
		Pointer      *string     `json:",omitempty"`
		InterfaceNil any         `json:",omitempty"`
		Interface    any         `json:",omitempty"`
	}{
		// Bool is NOT omitted since false is not an empty JSON value.
		Bool: false,
		// Int is NOT omitted since 0 is not a empty JSON value.
		Int: 0,
		// String is omitted since "" is an empty JSON string.
		String: "",
		// Time is NOT omitted since this encodes as a non-empty JSON string.
		Time: time.Date(1, 1, 1, 0, 0, 0, 0, time.UTC),
		// Addr is omitted since this encodes as an empty JSON string.
		Addr: netip.Addr{},
		// Struct is omitted since {} is an empty JSON object.
		Struct: MyStruct{Bar: []int{}, Baz: new(MyStruct)},
		// Slice is omitted since [] is an empty JSON array.
		Slice: []int{},
		// Map is omitted since {} is an empty JSON object.
		Map: map[int]int{},
		// PointerNil is ommited since null is an empty JSON value.
		PointerNil: nil,
		// Pointer is omitted since "" is an empty JSON string.
		Pointer: new(string),
		// InterfaceNil is omitted since null is an empty JSON value.
		InterfaceNil: nil,
		// Interface is omitted since null is an empty JSON value.
		Interface: (*string)(nil),
	})
	if err != nil {
		log.Fatal(err)
	}
	(*json.RawValue)(&b).Indent("", "\t") // indent for readability
	fmt.Println("OmitEmpty:", string(b))  // outputs "Bool", "Int", and "Time"

}

Output:

OmitZero: {
	"Struct": {},
	"Slice": [],
	"Map": {},
	"Pointer": "",
	"Interface": null
}
OmitEmpty: {
	"Bool": false,
	"Int": 0,
	"Time": "0001-01-01T00:00:00Z"
}
Example (OrderedObject)

The exact order of JSON object can be preserved through the use of a specialized type that implements MarshalerV2 and UnmarshalerV2.

Code:play  

package main

import (
	"fmt"
	"log"
	"reflect"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

// OrderedObject is an ordered sequence of name/value members in a JSON object.
//
// RFC 8259 defines an object as an "unordered collection".
// JSON implementations need not make "ordering of object members visible"
// to applications nor will they agree on the semantic meaning of an object if
// "the names within an object are not unique". For maximum compatibility,
// applications should avoid relying on ordering or duplicity of object names.
type OrderedObject[V any] []ObjectMember[V]

// ObjectMember is a JSON object member.
type ObjectMember[V any] struct {
	Name  string
	Value V
}

// MarshalNextJSON encodes obj as a JSON object into enc.
func (obj *OrderedObject[V]) MarshalNextJSON(opts json.MarshalOptions, enc *json.Encoder) error {
	if err := enc.WriteToken(json.ObjectStart); err != nil {
		return err
	}
	for i := range *obj {
		member := &(*obj)[i]
		if err := opts.MarshalNext(enc, &member.Name); err != nil {
			return err
		}
		if err := opts.MarshalNext(enc, &member.Value); err != nil {
			return err
		}
	}
	if err := enc.WriteToken(json.ObjectEnd); err != nil {
		return err
	}
	return nil
}

// UnmarshalNextJSON decodes a JSON object from dec into obj.
func (obj *OrderedObject[V]) UnmarshalNextJSON(opts json.UnmarshalOptions, dec *json.Decoder) error {
	if k := dec.PeekKind(); k != '{' {
		return fmt.Errorf("expected object start, but encountered %v", k)
	}
	if _, err := dec.ReadToken(); err != nil {
		return err
	}
	for dec.PeekKind() != '}' {
		*obj = append(*obj, ObjectMember[V]{})
		member := &(*obj)[len(*obj)-1]
		if err := opts.UnmarshalNext(dec, &member.Name); err != nil {
			return err
		}
		if err := opts.UnmarshalNext(dec, &member.Value); err != nil {
			return err
		}
	}
	if _, err := dec.ReadToken(); err != nil {
		return err
	}
	return nil
}

// The exact order of JSON object can be preserved through the use of a
// specialized type that implements MarshalerV2 and UnmarshalerV2.
func main() {
	// Round-trip marshal and unmarshal an ordered object.
	// We expect the order and duplicity of JSON object members to be preserved.
	want := OrderedObject[string]{
		{"fizz", "buzz"},
		{"hello", "world"},
		{"fizz", "wuzz"},
	}
	b, err := json.MarshalOptions{}.Marshal(json.EncodeOptions{
		AllowDuplicateNames: true, // since the object contains "fizz" twice
	}, &want)
	if err != nil {
		log.Fatal(err)
	}
	var got OrderedObject[string]
	err = json.UnmarshalOptions{}.Unmarshal(json.DecodeOptions{
		AllowDuplicateNames: true, // since the object contains "fizz" twice
	}, b, &got)
	if err != nil {
		log.Fatal(err)
	}

	// Sanity check.
	if !reflect.DeepEqual(got, want) {
		log.Fatalf("roundtrip mismatch: got %v, want %v", got, want)
	}

	// Print the serialized JSON object.
	(*json.RawValue)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"fizz": "buzz",
	"hello": "world",
	"fizz": "wuzz"
}
Example (ProtoJSON)

Some Go types have a custom JSON represention where the implementation is delegated to some external package. Consequentely, the "json" package will not know how to use that external implementation. For example, the "google.golang.org/protobuf/encoding/protojson" package implements JSON for all "google.golang.org/protobuf/proto".Message types. MarshalOptions.Marshalers and UnmarshalOptions.Unmarshalers can be used to configure "json" and "protojson" to cooperate together.

Code:play  

package main

import (
	"log"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Let protoMessage be "google.golang.org/protobuf/proto".Message.
	type protoMessage interface{ ProtoReflect() }
	// Let foopbMyMessage be a concrete implementation of proto.Message.
	type foopbMyMessage struct{ protoMessage }
	// Let protojson be an import of "google.golang.org/protobuf/encoding/protojson".
	var protojson struct {
		Marshal   func(protoMessage) ([]byte, error)
		Unmarshal func([]byte, protoMessage) error
	}

	// This value mixes both non-proto.Message types and proto.Message types.
	// It should use the "json" package to handle non-proto.Message types and
	// should use the "protojson" package to handle proto.Message types.
	var value struct {
		// GoStruct does not implement proto.Message and
		// should use the default behavior of the "json" package.
		GoStruct struct {
			Name string
			Age  int
		}

		// ProtoMessage implements proto.Message and
		// should be handled using protojson.Marshal.
		ProtoMessage *foopbMyMessage
	}

	// Marshal using protojson.Marshal for proto.Message types.
	b, err := json.MarshalOptions{
		// Use protojson.Marshal as a type-specific marshaler.
		Marshalers: json.MarshalFuncV1(protojson.Marshal),
	}.Marshal(json.EncodeOptions{}, &value)
	if err != nil {
		log.Fatal(err)
	}

	// Unmarshal using protojson.Unmarshal for proto.Message types.
	err = json.UnmarshalOptions{
		// Use protojson.Unmarshal as a type-specific unmarshaler.
		Unmarshalers: json.UnmarshalFuncV1(protojson.Unmarshal),
	}.Unmarshal(json.DecodeOptions{}, b, &value)
	if err != nil {
		log.Fatal(err)
	}
}
Example (ServeHTTP)

When implementing HTTP endpoints, it is common to be operating with an io.Reader and an io.Writer. The UnmarshalFull and MarshalFull functions assist in operating on such input/output types. UnmarshalFull reads the entirety of the io.Reader to ensure that io.EOF is encountered without any unexpected bytes after the top-level JSON value.

Code:play  

package main

import (
	"net/http"
	"sync/atomic"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Some global state maintained by the server.
	var n int64

	// The "add" endpoint accepts a POST request with a JSON object
	// containing a number to atomically add to the server's global counter.
	// It returns the updated value of the counter.
	http.HandleFunc("/api/add", func(w http.ResponseWriter, r *http.Request) {
		// Unmarshal the request from the client.
		var val struct{ N int64 }
		if err := json.UnmarshalFull(r.Body, &val); err != nil {
			// Inability to unmarshal the input suggests a client-side problem.
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}

		// Marshal a response from the server.
		val.N = atomic.AddInt64(&n, val.N)
		if err := json.MarshalFull(w, &val); err != nil {
			// Inability to marshal the output suggests a server-side problem.
			// This error is not always observable by the client since
			// json.MarshalFull may have already written to the output.
			http.Error(w, err.Error(), http.StatusInternalServerError)
			return
		}
	})
}
Example (StringReplace)

This example demonstrates the use of the Encoder and Decoder to parse and modify JSON without unmarshaling it into a concrete Go type.

Code:play  

package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"strings"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Example input with non-idiomatic use of "Golang" instead of "Go".
	const input = `{
		"title": "Golang version 1 is released",
		"author": "Andrew Gerrand",
		"date": "2012-03-28",
		"text": "Today marks a major milestone in the development of the Golang programming language.",
		"otherArticles": [
			"Twelve Years of Golang",
			"The Laws of Reflection",
			"Learn Golang from your browser"
		]
	}`

	// Using a Decoder and Encoder, we can parse through every token,
	// check and modify the token if necessary, and
	// write the token to the output.
	var replacements []string
	in := strings.NewReader(input)
	dec := json.NewDecoder(in)
	out := new(bytes.Buffer)
	enc := json.EncodeOptions{Indent: "\t"}.NewEncoder(out) // indent for readability
	for {
		// Read a token from the input.
		tok, err := dec.ReadToken()
		if err != nil {
			if err == io.EOF {
				break
			}
			log.Fatal(err)
		}

		// Check whether the token contains the string "Golang" and
		// replace each occurence with "Go" instead.
		if tok.Kind() == '"' && strings.Contains(tok.String(), "Golang") {
			replacements = append(replacements, dec.StackPointer())
			tok = json.String(strings.ReplaceAll(tok.String(), "Golang", "Go"))
		}

		// Write the (possibly modified) token to the output.
		if err := enc.WriteToken(tok); err != nil {
			log.Fatal(err)
		}
	}

	// Print the list of replacements and the adjusted JSON output.
	if len(replacements) > 0 {
		fmt.Println(`Replaced "Golang" with "Go" in:`)
		for _, where := range replacements {
			fmt.Println("\t" + where)
		}
		fmt.Println()
	}
	fmt.Println("Result:", out.String())

}

Output:

Replaced "Golang" with "Go" in:
	/title
	/text
	/otherArticles/0
	/otherArticles/2

Result: {
	"title": "Go version 1 is released",
	"author": "Andrew Gerrand",
	"date": "2012-03-28",
	"text": "Today marks a major milestone in the development of the Go programming language.",
	"otherArticles": [
		"Twelve Years of Go",
		"The Laws of Reflection",
		"Learn Go from your browser"
	]
}
Example (TextMarshal)

If a type implements encoding.TextMarshaler and/or encoding.TextUnmarshaler, then the MarshalText and UnmarshalText methods are used to encode/decode the value to/from a JSON string.

Code:play  

package main

import (
	"fmt"
	"log"
	"net/netip"
	"reflect"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Round-trip marshal and unmarshal a hostname map where the netip.Addr type
	// implements both encoding.TextMarshaler and encoding.TextUnmarshaler.
	want := map[netip.Addr]string{
		netip.MustParseAddr("192.168.0.100"): "carbonite",
		netip.MustParseAddr("192.168.0.101"): "obsidian",
		netip.MustParseAddr("192.168.0.102"): "diamond",
	}
	b, err := json.Marshal(&want)
	if err != nil {
		log.Fatal(err)
	}
	var got map[netip.Addr]string
	err = json.Unmarshal(b, &got)
	if err != nil {
		log.Fatal(err)
	}

	// Sanity check.
	if !reflect.DeepEqual(got, want) {
		log.Fatalf("roundtrip mismatch: got %v, want %v", got, want)
	}

	// Print the serialized JSON object. Canonicalize the JSON first since
	// Go map entries are not serialized in a deterministic order.
	(*json.RawValue)(&b).Canonicalize()
	(*json.RawValue)(&b).Indent("", "\t") // indent for readability
	fmt.Println(string(b))

}

Output:

{
	"192.168.0.100": "carbonite",
	"192.168.0.101": "obsidian",
	"192.168.0.102": "diamond"
}
Example (UnknownMembers)

Due to version skew, the set of JSON object members known at compile-time may differ from the set of members encountered at execution-time. As such, it may be useful to have finer grain handling of unknown members. This package supports preserving, rejecting, or discarding such members.

Code:play  

package main

import (
	"errors"
	"fmt"
	"log"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	const input = `{
		"Name": "Teal",
		"Value": "#008080",
		"WebSafe": false
	}`
	type Color struct {
		Name  string
		Value string

		// Unknown is a Go struct field that holds unknown JSON object members.
		// It is marked as having this behavior with the "unknown" tag option.
		//
		// The type may be a RawValue or map[string]T.
		Unknown json.RawValue `json:",unknown"`
	}

	// By default, unknown members are stored in a Go field marked as "unknown"
	// or ignored if no such field exists.
	var color Color
	err := json.Unmarshal([]byte(input), &color)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Unknown members:", string(color.Unknown))

	// Specifying UnmarshalOptions.RejectUnknownMembers causes
	// Unmarshal to reject the presence of any unknown members.
	err = json.UnmarshalOptions{
		RejectUnknownMembers: true,
	}.Unmarshal(json.DecodeOptions{}, []byte(input), new(Color))
	if err != nil {
		fmt.Println("Unmarshal error:", errors.Unwrap(err))
	}

	// By default, Marshal preserves unknown members stored in
	// a Go struct field marked as "unknown".
	b, err := json.Marshal(color)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Output with unknown members:   ", string(b))

	// Specifying MarshalOptions.DiscardUnknownMembers causes
	// Marshal to discard any unknown members.
	b, err = json.MarshalOptions{
		DiscardUnknownMembers: true,
	}.Marshal(json.EncodeOptions{}, color)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Output without unknown members:", string(b))

}

Output:

Unknown members: {"WebSafe":false}
Unmarshal error: unknown name "WebSafe"
Output with unknown members:    {"Name":"Teal","Value":"#008080","WebSafe":false}
Output without unknown members: {"Name":"Teal","Value":"#008080"}

Index

Examples

Constants 

const Error = jsonError("json error")

Error matches errors returned by this package according to errors.Is. 

const SkipFunc = jsonError("skip function")

SkipFunc may be returned by MarshalFuncV2 and UnmarshalFuncV2 functions.

Any function that returns SkipFunc must not cause observable side effects on the provided Encoder or Decoder. For example, it is permissible to call Decoder.PeekKind, but not permissible to call Decoder.ReadToken or Encoder.WriteToken since such methods mutate the state.

Functions

func Marshal 

func Marshal(in any) (out []byte, err error)

Marshal serializes a Go value as a []byte with default options. It is a thin wrapper over MarshalOptions.Marshal.

func MarshalFull 

func MarshalFull(out io.Writer, in any) error

MarshalFull serializes a Go value into an io.Writer with default options. It is a thin wrapper over MarshalOptions.MarshalFull.

func Unmarshal 

func Unmarshal(in []byte, out any) error

Unmarshal deserializes a Go value from a []byte with default options. It is a thin wrapper over UnmarshalOptions.Unmarshal.

func UnmarshalFull 

func UnmarshalFull(in io.Reader, out any) error

UnmarshalFull deserializes a Go value from an io.Reader with default options. It is a thin wrapper over UnmarshalOptions.UnmarshalFull.

Types

type DecodeOptions 

type DecodeOptions struct {

	// AllowDuplicateNames specifies that JSON objects may contain
	// duplicate member names. Disabling the duplicate name check may provide
	// computational and performance benefits, but breaks compliance with
	// RFC 7493, section 2.3. The input will still be compliant with RFC 8259,
	// which leaves the handling of duplicate names as unspecified behavior.
	AllowDuplicateNames bool

	// AllowInvalidUTF8 specifies that JSON strings may contain invalid UTF-8,
	// which will be mangled as the Unicode replacement character, U+FFFD.
	// This causes the decoder to break compliance with
	// RFC 7493, section 2.1, and RFC 8259, section 8.1.
	AllowInvalidUTF8 bool
	// contains filtered or unexported fields
}

DecodeOptions configures how JSON decoding operates. The zero value is equivalent to the default settings, which is compliant with both RFC 7493 and RFC 8259.

func (DecodeOptions) NewDecoder 

func (o DecodeOptions) NewDecoder(r io.Reader) *Decoder

NewDecoder constructs a new streaming decoder reading from r configured with the provided options.

func (DecodeOptions) ResetDecoder 

func (o DecodeOptions) ResetDecoder(d *Decoder, r io.Reader)

ResetDecoder resets a decoder such that it is reading afresh from r and configured with the provided options.

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder is a streaming decoder for raw JSON tokens and values. It is used to read a stream of top-level JSON values, each separated by optional whitespace characters.

ReadToken and ReadValue calls may be interleaved. For example, the following JSON value: 

{"name":"value","array":[null,false,true,3.14159],"object":{"k":"v"}}

can be parsed with the following calls (ignoring errors for brevity): 

d.ReadToken() // {
d.ReadToken() // "name"
d.ReadToken() // "value"
d.ReadValue() // "array"
d.ReadToken() // [
d.ReadToken() // null
d.ReadToken() // false
d.ReadValue() // true
d.ReadToken() // 3.14159
d.ReadToken() // ]
d.ReadValue() // "object"
d.ReadValue() // {"k":"v"}
d.ReadToken() // }

The above is one of many possible sequence of calls and may not represent the most sensible method to call for any given token/value. For example, it is probably more common to call ReadToken to obtain a string token for object names.

func NewDecoder 

func NewDecoder(r io.Reader) *Decoder

NewDecoder constructs a new streaming decoder reading from r.

If r is a bytes.Buffer, then the decoder parses directly from the buffer without first copying the contents to an intermediate buffer. Additional writes to the buffer must not occur while the decoder is in use.

func (*Decoder) InputOffset 

func (d *Decoder) InputOffset() int64

InputOffset returns the current input byte offset. It gives the location of the next byte immediately after the most recently returned token or value. The number of bytes actually read from the underlying io.Reader may be more than this offset due to internal buffering effects.

func (*Decoder) PeekKind 

func (d *Decoder) PeekKind() Kind

PeekKind retrieves the next token kind, but does not advance the read offset. It returns 0 if there are no more tokens.

func (*Decoder) ReadToken 

func (d *Decoder) ReadToken() (Token, error)

ReadToken reads the next Token, advancing the read offset. The returned token is only valid until the next Peek, Read, or Skip call. It returns io.EOF if there are no more tokens.

func (*Decoder) ReadValue 

func (d *Decoder) ReadValue() (RawValue, error)

ReadValue returns the next raw JSON value, advancing the read offset. The value is stripped of any leading or trailing whitespace. The returned value is only valid until the next Peek, Read, or Skip call and may not be mutated while the Decoder remains in use. If the decoder is currently at the end token for an object or array, then it reports a SyntacticError and the internal state remains unchanged. It returns io.EOF if there are no more values.

func (*Decoder) Reset 

func (d *Decoder) Reset(r io.Reader)

Reset resets a decoder such that it is reading afresh from r but keep any pre-existing decoder options.

func (*Decoder) SkipValue 

func (d *Decoder) SkipValue() error

SkipValue is semantically equivalent to calling ReadValue and discarding the result except that memory is not wasted trying to hold the entire result.

func (*Decoder) StackDepth 

func (d *Decoder) StackDepth() int

StackDepth returns the depth of the state machine for read JSON data. Each level on the stack represents a nested JSON object or array. It is incremented whenever an ObjectStart or ArrayStart token is encountered and decremented whenever an ObjectEnd or ArrayEnd token is encountered. The depth is zero-indexed, where zero represents the top-level JSON value.

func (*Decoder) StackIndex 

func (d *Decoder) StackIndex(i int) (Kind, int)

StackIndex returns information about the specified stack level. It must be a number between 0 and StackDepth, inclusive. For each level, it reports the kind:

It also reports the length of that JSON object or array. Each name and value in a JSON object is counted separately, so the effective number of members would be half the length. A complete JSON object must have an even length.

func (*Decoder) StackPointer 

func (d *Decoder) StackPointer() string

StackPointer returns a JSON Pointer (RFC 6901) to the most recently read value. Object names are only present if AllowDuplicateNames is false, otherwise object members are represented using their index within the object.

func (*Decoder) UnreadBuffer 

func (d *Decoder) UnreadBuffer() []byte

UnreadBuffer returns the data remaining in the unread buffer, which may contain zero or more bytes. The returned buffer must not be mutated while Decoder continues to be used. The buffer contents are valid until the next Peek, Read, or Skip call.

type EncodeOptions 

type EncodeOptions struct {

	// AllowDuplicateNames specifies that JSON objects may contain
	// duplicate member names. Disabling the duplicate name check may provide
	// performance benefits, but breaks compliance with RFC 7493, section 2.3.
	// The output will still be compliant with RFC 8259,
	// which leaves the handling of duplicate names as unspecified behavior.
	AllowDuplicateNames bool

	// AllowInvalidUTF8 specifies that JSON strings may contain invalid UTF-8,
	// which will be mangled as the Unicode replacement character, U+FFFD.
	// This causes the encoder to break compliance with
	// RFC 7493, section 2.1, and RFC 8259, section 8.1.
	AllowInvalidUTF8 bool

	// EscapeRune reports whether the provided character should be escaped
	// as a hexadecimal Unicode codepoint (e.g., \ufffd).
	// If nil, the shortest and simplest encoding will be used,
	// which is also the formatting specified by RFC 8785, section 3.2.2.2.
	EscapeRune func(rune) bool

	// Indent (if non-empty) specifies that the encoder should emit multiline
	// output where each element in a JSON object or array begins on a new,
	// indented line beginning with the indent prefix followed by one or more
	// copies of indent according to the indentation nesting.
	// It may only be composed of space or tab characters.
	Indent string

	// IndentPrefix is prepended to each line within a JSON object or array.
	// The purpose of the indent prefix is to encode data that can more easily
	// be embedded inside other formatted JSON data.
	// It may only be composed of space or tab characters.
	// It is ignored if Indent is empty.
	IndentPrefix string
	// contains filtered or unexported fields
}

EncodeOptions configures how JSON encoding operates. The zero value is equivalent to the default settings, which is compliant with both RFC 7493 and RFC 8259.

Example (EscapeHTML)

Directly embedding JSON within HTML requires special handling for safety. Escape certain runes to prevent JSON directly treated as HTML from being able to perform <script> injection.

This example shows how to obtain equivalent behavior provided by the "encoding/json" package that is no longer directly supported by this package. Newly written code that intermix JSON and HTML should instead be using the "github.com/google/safehtml" module for safety purposes.

Code:play  

package main

import (
	"fmt"
	"log"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	page := struct {
		Title string
		Body  string
	}{
		Title: "Example Embedded Javascript",
		Body:  `<script> console.log("Hello, world!"); </script>`,
	}

	b, err := json.MarshalOptions{}.Marshal(json.EncodeOptions{
		// Escape certain runes within a JSON string so that
		// JSON will be safe to directly embed inside HTML.
		EscapeRune: func(r rune) bool {
			switch r {
			case '&', '<', '>', '\u2028', '\u2029':
				return true
			default:
				return false
			}
		},
		// Indent the output for readability.
		Indent: "\t",
	}, &page)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(b))

}

Output:

{
	"Title": "Example Embedded Javascript",
	"Body": "\u003cscript\u003e console.log(\"Hello, world!\"); \u003c/script\u003e"
}

func (EncodeOptions) NewEncoder 

func (o EncodeOptions) NewEncoder(w io.Writer) *Encoder

NewEncoder constructs a new streaming encoder writing to w configured with the provided options. It flushes the internal buffer when the buffer is sufficiently full or when a top-level value has been written.

If w is a bytes.Buffer, then the encoder appends directly into the buffer without copying the contents from an intermediate buffer.

func (EncodeOptions) ResetEncoder 

func (o EncodeOptions) ResetEncoder(e *Encoder, w io.Writer)

ResetEncoder resets an encoder such that it is writing afresh to w and configured with the provided options.

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder is a streaming encoder from raw JSON tokens and values. It is used to write a stream of top-level JSON values, each terminated with a newline character.

WriteToken and WriteValue calls may be interleaved. For example, the following JSON value: 

{"name":"value","array":[null,false,true,3.14159],"object":{"k":"v"}}

can be composed with the following calls (ignoring errors for brevity): 

e.WriteToken(ObjectStart)           // {
e.WriteToken(String("name"))        // "name"
e.WriteToken(String("value"))       // "value"
e.WriteValue(RawValue(`"array"`))   // "array"
e.WriteToken(ArrayStart)            // [
e.WriteToken(Null)                  // null
e.WriteToken(False)                 // false
e.WriteValue(RawValue("true"))      // true
e.WriteToken(Float(3.14159))        // 3.14159
e.WriteToken(ArrayEnd)              // ]
e.WriteValue(RawValue(`"object"`))  // "object"
e.WriteValue(RawValue(`{"k":"v"}`)) // {"k":"v"}
e.WriteToken(ObjectEnd)             // }

The above is one of many possible sequence of calls and may not represent the most sensible method to call for any given token/value. For example, it is probably more common to call WriteToken with a string for object names.

func NewEncoder 

func NewEncoder(w io.Writer) *Encoder

NewEncoder constructs a new streaming encoder writing to w.

func (*Encoder) OutputOffset 

func (e *Encoder) OutputOffset() int64

OutputOffset returns the current output byte offset. It gives the location of the next byte immediately after the most recently written token or value. The number of bytes actually written to the underlying io.Writer may be less than this offset due to internal buffering effects.

func (*Encoder) Reset 

func (e *Encoder) Reset(w io.Writer)

Reset resets an encoder such that it is writing afresh to w but keeps any pre-existing encoder options.

func (*Encoder) StackDepth 

func (e *Encoder) StackDepth() int

StackDepth returns the depth of the state machine for written JSON data. Each level on the stack represents a nested JSON object or array. It is incremented whenever an ObjectStart or ArrayStart token is encountered and decremented whenever an ObjectEnd or ArrayEnd token is encountered. The depth is zero-indexed, where zero represents the top-level JSON value.

func (*Encoder) StackIndex 

func (e *Encoder) StackIndex(i int) (Kind, int)

StackIndex returns information about the specified stack level. It must be a number between 0 and StackDepth, inclusive. For each level, it reports the kind:

It also reports the length of that JSON object or array. Each name and value in a JSON object is counted separately, so the effective number of members would be half the length. A complete JSON object must have an even length.

func (*Encoder) StackPointer 

func (e *Encoder) StackPointer() string

StackPointer returns a JSON Pointer (RFC 6901) to the most recently written value. Object names are only present if AllowDuplicateNames is false, otherwise object members are represented using their index within the object.

func (*Encoder) UnusedBuffer 

func (e *Encoder) UnusedBuffer() []byte

UnusedBuffer returns a zero-length buffer with a possible non-zero capacity. This buffer is intended to be used to populate a RawValue being passed to an immediately succeeding WriteValue call.

Example usage: 

b := d.UnusedBuffer()
b = append(b, '"')
b = appendString(b, v) // append the string formatting of v
b = append(b, '"')
... := d.WriteValue(b)

It is the user's responsibility to ensure that the value is valid JSON.

func (*Encoder) WriteToken 

func (e *Encoder) WriteToken(t Token) error

WriteToken writes the next token and advances the internal write offset.

The provided token kind must be consistent with the JSON grammar. For example, it is an error to provide a number when the encoder is expecting an object name (which is always a string), or to provide an end object delimiter when the encoder is finishing an array. If the provided token is invalid, then it reports a SyntacticError and the internal state remains unchanged.

func (*Encoder) WriteValue 

func (e *Encoder) WriteValue(v RawValue) error

WriteValue writes the next raw value and advances the internal write offset. The Encoder does not simply copy the provided value verbatim, but parses it to ensure that it is syntactically valid and reformats it according to how the Encoder is configured to format whitespace and strings.

The provided value kind must be consistent with the JSON grammar (see examples on Encoder.WriteToken). If the provided value is invalid, then it reports a SyntacticError and the internal state remains unchanged.

type Kind 

type Kind byte

Kind represents each possible JSON token kind with a single byte, which is conveniently the first byte of that kind's grammar with the restriction that numbers always be represented with '0':

An invalid kind is usually represented using 0, but may be non-zero due to invalid JSON data.

func (Kind) String 

func (k Kind) String() string

String prints the kind in a humanly readable fashion.

type MarshalOptions 

type MarshalOptions struct {

	// Marshalers is a list of type-specific marshalers to use.
	Marshalers *Marshalers

	// StringifyNumbers specifies that numeric Go types should be serialized
	// as a JSON string containing the equivalent JSON number value.
	//
	// According to RFC 8259, section 6, a JSON implementation may choose to
	// limit the representation of a JSON number to an IEEE 754 binary64 value.
	// This may cause decoders to lose precision for int64 and uint64 types.
	// Escaping JSON numbers as a JSON string preserves the exact precision.
	StringifyNumbers bool

	// DiscardUnknownMembers specifies that marshaling should ignore any
	// JSON object members stored in Go struct fields dedicated to storing
	// unknown JSON object members.
	DiscardUnknownMembers bool

	// Deterministic specifies that the same input value will be serialized
	// as the exact same output bytes. Different processes of
	// the same program will serialize equal values to the same bytes,
	// but different versions of the same program are not guaranteed
	// to produce the exact same sequence of bytes.
	Deterministic bool
	// contains filtered or unexported fields
}

MarshalOptions configures how Go data is serialized as JSON data. The zero value is equivalent to the default marshal settings.

Example (Errors)

Many error types are not serializable since they tend to be Go structs without any exported fields (e.g., errors constructed with errors.New). Some applications, may desire to marshal an error as a JSON string even if these errors cannot be unmarshaled.

Code:play  

package main

import (
	"fmt"
	"log"
	"os"
	"strconv"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Response to serialize with some Go errors encountered.
	response := []struct {
		Result string `json:",omitzero"`
		Error  error  `json:",omitzero"`
	}{
		{Result: "Oranges are a good source of Vitamin C."},
		{Error: &strconv.NumError{Func: "ParseUint", Num: "-1234", Err: strconv.ErrSyntax}},
		{Error: &os.PathError{Op: "ReadFile", Path: "/path/to/secret/file", Err: os.ErrPermission}},
	}

	b, err := json.MarshalOptions{
		// Intercept every attempt to marshal an error type.
		Marshalers: json.NewMarshalers(
			// Suppose we consider strconv.NumError to be a safe to serialize:
			// this type-specific marshal function intercepts this type
			// and encodes the error message as a JSON string.
			json.MarshalFuncV2(func(opts json.MarshalOptions, enc *json.Encoder, err *strconv.NumError) error {
				return enc.WriteToken(json.String(err.Error()))
			}),
			// Error messages may contain sensitive information that may not
			// be appropriate to serialize. For all errors not handled above,
			// report some generic error message.
			json.MarshalFuncV1(func(error) ([]byte, error) {
				return []byte(`"internal server error"`), nil
			}),
		),
	}.Marshal(json.EncodeOptions{
		Indent: "\t", // indent for readability
	}, &response)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(b))

}

Output:

[
	{
		"Result": "Oranges are a good source of Vitamin C."
	},
	{
		"Error": "strconv.ParseUint: parsing \"-1234\": invalid syntax"
	},
	{
		"Error": "internal server error"
	}
]

func (MarshalOptions) Marshal 

func (mo MarshalOptions) Marshal(eo EncodeOptions, in any) (out []byte, err error)

Marshal serializes a Go value as a []byte according to the provided marshal and encode options. It does not terminate the output with a newline. See MarshalNext for details about the conversion of a Go value into JSON.

func (MarshalOptions) MarshalFull 

func (mo MarshalOptions) MarshalFull(eo EncodeOptions, out io.Writer, in any) error

MarshalFull serializes a Go value into an io.Writer according to the provided marshal and encode options. It does not terminate the output with a newline. See MarshalNext for details about the conversion of a Go value into JSON.

func (MarshalOptions) MarshalNext 

func (mo MarshalOptions) MarshalNext(out *Encoder, in any) error

MarshalNext encodes a Go value as the next JSON value according to the provided marshal options.

Type-specific marshal functions and methods take precedence over the default representation of a value. Functions or methods that operate on *T are only called when encoding a value of type T (by taking its address) or a non-nil value of *T. MarshalNext ensures that a value is always addressable (by boxing it on the heap if necessary) so that these functions and methods can be consistently called. For performance, it is recommended that MarshalNext be passed a non-nil pointer to the value.

The input value is encoded as JSON according the following rules:

Most Go types have a default JSON representation. Certain types support specialized formatting according to a format flag optionally specified in the Go struct tag for the struct field that contains the current value (see the “JSON Representation of Go structs” section for more details).

The representation of each type is as follows:

JSON cannot represent cyclic data structures and MarshalNext does not handle them. Passing cyclic structures will result in an error.

type MarshalerV1 

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

MarshalerV1 is implemented by types that can marshal themselves. It is recommended that types implement MarshalerV2 unless the implementation is trying to avoid a hard dependency on the "jsontext" package.

It is recommended that implementations return a buffer that is safe for the caller to retain and potentially mutate.

type MarshalerV2 

type MarshalerV2 interface {
	MarshalNextJSON(MarshalOptions, *Encoder) error
}

MarshalerV2 is implemented by types that can marshal themselves. It is recommended that types implement MarshalerV2 instead of MarshalerV1 since this is both more performant and flexible. If a type implements both MarshalerV1 and MarshalerV2, then MarshalerV2 takes precedence. In such a case, both implementations should aim to have equivalent behavior for the default marshal options.

The implementation must write only one JSON value to the Encoder and must not retain the pointer to Encoder.

type Marshalers 

type Marshalers = typedMarshalers

Marshalers is a list of functions that may override the marshal behavior of specific types. Populate MarshalOptions.Marshalers to use it. A nil *Marshalers is equivalent to an empty list.

func MarshalFuncV1 

func MarshalFuncV1[T any](fn func(T) ([]byte, error)) *Marshalers

MarshalFuncV1 constructs a type-specific marshaler that specifies how to marshal values of type T. T can be any type except a named pointer. The function is always provided with a non-nil pointer value if T is an interface or pointer type.

The function must marshal exactly one JSON value. The value of T must not be retained outside the function call. It may not return SkipFunc.

func MarshalFuncV2 

func MarshalFuncV2[T any](fn func(MarshalOptions, *Encoder, T) error) *Marshalers

MarshalFuncV2 constructs a type-specific marshaler that specifies how to marshal values of type T. T can be any type except a named pointer. The function is always provided with a non-nil pointer value if T is an interface or pointer type.

The function must marshal exactly one JSON value by calling write methods on the provided encoder. It may return SkipFunc such that marshaling can move on to the next marshal function. However, no mutable method calls may be called on the encoder if SkipFunc is returned. The pointer to Encoder and the value of T must not be retained outside the function call.

func NewMarshalers 

func NewMarshalers(ms ...*Marshalers) *Marshalers

NewMarshalers constructs a flattened list of marshal functions. If multiple functions in the list are applicable for a value of a given type, then those earlier in the list take precedence over those that come later. If a function returns SkipFunc, then the next applicable function is called, otherwise the default marshaling behavior is used.

For example: 

m1 := NewMarshalers(f1, f2)
m2 := NewMarshalers(f0, m1, f3)     // equivalent to m3
m3 := NewMarshalers(f0, f1, f2, f3) // equivalent to m2

type RawValue 

type RawValue []byte

RawValue represents a single raw JSON value, which may be one of the following:

RawValue can represent entire array or object values, while Token cannot. RawValue may contain leading and/or trailing whitespace.

func (*RawValue) Canonicalize 

func (v *RawValue) Canonicalize() error

Canonicalize canonicalizes the raw JSON value according to the JSON Canonicalization Scheme (JCS) as defined by RFC 8785 where it produces a stable representation of a JSON value.

The output stability is dependent on the stability of the application data (see RFC 8785, Appendix E). It cannot produce stable output from fundamentally unstable input. For example, if the JSON value contains ephemeral data (e.g., a frequently changing timestamp), then the value is still unstable regardless of whether this is called.

Note that JCS treats all JSON numbers as IEEE 754 double precision numbers. Any numbers with precision beyond what is representable by that form will lose their precision when canonicalized. For example, integer values beyond ±2⁵³ will lose their precision. It is recommended that int64 and uint64 data types be represented as a JSON string.

It is guaranteed to succeed if the input is valid. If the value is already canonicalized, then the buffer is not mutated.

func (RawValue) Clone 

func (v RawValue) Clone() RawValue

Clone returns a copy of v.

func (*RawValue) Compact 

func (v *RawValue) Compact() error

Compact removes all whitespace from the raw JSON value.

It does not reformat JSON strings to use any other representation. It is guaranteed to succeed if the input is valid. If the value is already compacted, then the buffer is not mutated.

func (*RawValue) Indent 

func (v *RawValue) Indent(prefix, indent string) error

Indent reformats the whitespace in the raw JSON value so that each element in a JSON object or array begins on a new, indented line beginning with prefix followed by one or more copies of indent according to the nesting. The value does not begin with the prefix nor any indention, to make it easier to embed inside other formatted JSON data.

It does not reformat JSON strings to use any other representation. It is guaranteed to succeed if the input is valid. If the value is already indented properly, then the buffer is not mutated.

func (RawValue) IsValid 

func (v RawValue) IsValid() bool

IsValid reports whether the raw JSON value is syntactically valid according to RFC 7493.

It verifies whether the input is properly encoded as UTF-8, that escape sequences within strings decode to valid Unicode codepoints, and that all names in each object are unique. It does not verify whether numbers are representable within the limits of any common numeric type (e.g., float64, int64, or uint64).

func (RawValue) Kind 

func (v RawValue) Kind() Kind

Kind returns the starting token kind. For a valid value, this will never include '}' or ']'.

func (RawValue) MarshalJSON 

func (v RawValue) MarshalJSON() ([]byte, error)

MarshalJSON returns v as the JSON encoding of v. It returns the stored value as the raw JSON output without any validation. If v is nil, then this returns a JSON null.

func (RawValue) String 

func (v RawValue) String() string

String returns the string formatting of v.

func (*RawValue) UnmarshalJSON 

func (v *RawValue) UnmarshalJSON(b []byte) error

UnmarshalJSON sets v as the JSON encoding of b. It stores a copy of the provided raw JSON input without any validation.

type SemanticError 

type SemanticError struct {

	// ByteOffset indicates that an error occurred after this byte offset.
	ByteOffset int64
	// JSONPointer indicates that an error occurred within this JSON value
	// as indicated using the JSON Pointer notation (see RFC 6901).
	JSONPointer string

	// JSONKind is the JSON kind that could not be handled.
	JSONKind Kind // may be zero if unknown
	// GoType is the Go type that could not be handled.
	GoType reflect.Type // may be nil if unknown

	// Err is the underlying error.
	Err error // may be nil
	// contains filtered or unexported fields
}

SemanticError describes an error determining the meaning of JSON data as Go data or vice-versa.

The contents of this error as produced by this package may change over time.

func (*SemanticError) Error 

func (e *SemanticError) Error() string

func (*SemanticError) Is 

func (e *SemanticError) Is(target error) bool

func (*SemanticError) Unwrap 

func (e *SemanticError) Unwrap() error

type SyntacticError 

type SyntacticError struct {

	// ByteOffset indicates that an error occurred after this byte offset.
	ByteOffset int64
	// contains filtered or unexported fields
}

SyntacticError is a description of a syntactic error that occurred when encoding or decoding JSON according to the grammar.

The contents of this error as produced by this package may change over time.

func (*SyntacticError) Error 

func (e *SyntacticError) Error() string

func (*SyntacticError) Is 

func (e *SyntacticError) Is(target error) bool

type Token 

type Token struct {
	// contains filtered or unexported fields
}

Token represents a lexical JSON token, which may be one of the following:

A Token cannot represent entire array or object values, while a RawValue can. There is no Token to represent commas and colons since these structural tokens can be inferred from the surrounding context. 

var (
	Null  Token = rawToken("null")
	False Token = rawToken("false")
	True  Token = rawToken("true")

	ObjectStart Token = rawToken("{")
	ObjectEnd   Token = rawToken("}")
	ArrayStart  Token = rawToken("[")
	ArrayEnd    Token = rawToken("]")
)

func Bool 

func Bool(b bool) Token

Bool constructs a Token representing a JSON boolean.

func Float 

func Float(n float64) Token

Float constructs a Token representing a JSON number. The values NaN, +Inf, and -Inf will be represented as a JSON string with the values "NaN", "Infinity", and "-Infinity".

func Int 

func Int(n int64) Token

Int constructs a Token representing a JSON number from an int64.

func String 

func String(s string) Token

String constructs a Token representing a JSON string. The provided string should contain valid UTF-8, otherwise invalid characters may be mangled as the Unicode replacement character.

func Uint 

func Uint(n uint64) Token

Uint constructs a Token representing a JSON number from a uint64.

func (Token) Bool 

func (t Token) Bool() bool

Bool returns the value for a JSON boolean. It panics if the token kind is not a JSON boolean.

func (Token) Clone 

func (t Token) Clone() Token

Clone makes a copy of the Token such that its value remains valid even after a subsequent Decoder.Read call.

func (Token) Float 

func (t Token) Float() float64

Float returns the floating-point value for a JSON number. It returns a NaN, +Inf, or -Inf value for any JSON string with the values "NaN", "Infinity", or "-Infinity". It panics for all other cases.

func (Token) Int 

func (t Token) Int() int64

Int returns the signed integer value for a JSON number. The fractional component of any number is ignored (truncation toward zero). Any number beyond the representation of an int64 will be saturated to the closest representable value. It panics if the token kind is not a JSON number.

func (Token) Kind 

func (t Token) Kind() Kind

Kind returns the token kind.

func (Token) String 

func (t Token) String() string

String returns the unescaped string value for a JSON string. For other JSON kinds, this returns the raw JSON representation.

func (Token) Uint 

func (t Token) Uint() uint64

Uint returns the unsigned integer value for a JSON number. The fractional component of any number is ignored (truncation toward zero). Any number beyond the representation of an uint64 will be saturated to the closest representable value. It panics if the token kind is not a JSON number.

type UnmarshalOptions 

type UnmarshalOptions struct {

	// Unmarshalers is a list of type-specific unmarshalers to use.
	Unmarshalers *Unmarshalers

	// StringifyNumbers specifies that numeric Go types can be deserialized
	// from either a JSON number or a JSON string containing a JSON number
	// without any surrounding whitespace.
	StringifyNumbers bool

	// RejectUnknownMembers specifies that unknown members should be rejected
	// when unmarshaling a JSON object, regardless of whether there is a field
	// to store unknown members.
	RejectUnknownMembers bool
	// contains filtered or unexported fields
}

UnmarshalOptions configures how JSON data is deserialized as Go data. The zero value is equivalent to the default unmarshal settings.

Example (RawNumber)

In some applications, the exact precision of JSON numbers needs to be preserved when unmarshaling. This can be accomplished using a type-specific unmarshal function that intercepts all any types and pre-populates the interface value with a RawValue, which can represent a JSON number exactly.

Code:play  

package main

import (
	"fmt"
	"log"
	"reflect"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Input with JSON numbers beyond the representation of a float64.
	const input = `[false, 1e-1000, 3.141592653589793238462643383279, 1e+1000, true]`

	var value any
	err := json.UnmarshalOptions{
		// Intercept every attempt to unmarshal into the any type.
		Unmarshalers: json.UnmarshalFuncV2(func(opts json.UnmarshalOptions, dec *json.Decoder, val *any) error {
			// If the next value to be decoded is a JSON number,
			// then provide a concrete Go type to unmarshal into.
			if dec.PeekKind() == '0' {
				*val = json.RawValue(nil)
			}
			// Return SkipFunc to fallback on default unmarshal behavior.
			return json.SkipFunc
		}),
	}.Unmarshal(json.DecodeOptions{}, []byte(input), &value)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(value)

	// Sanity check.
	want := []any{false, json.RawValue("1e-1000"), json.RawValue("3.141592653589793238462643383279"), json.RawValue("1e+1000"), true}
	if !reflect.DeepEqual(value, want) {
		log.Fatalf("value mismatch:\ngot  %v\nwant %v", value, want)
	}

}

Output:

[false 1e-1000 3.141592653589793238462643383279 1e+1000 true]
Example (RecordOffsets)

When using JSON for parsing configuration files, the parsing logic often needs to report an error with a line and column indicating where in the input an error occurred.

Code:play  

package main

import (
	"bytes"
	"fmt"
	"log"
	"net/netip"
	"strings"

	"k8s.io/kube-openapi/pkg/internal/third_party/go-json-experiment/json"
)

func main() {
	// Hypothetical configuration file.
	const input = `[
		{"Source": "192.168.0.100:1234", "Destination": "192.168.0.1:80"},
		{"Source": "192.168.0.251:4004"},
		{"Source": "192.168.0.165:8080", "Destination": "0.0.0.0:80"}
	]`
	type Tunnel struct {
		Source      netip.AddrPort
		Destination netip.AddrPort

		// ByteOffset is populated during unmarshal with the byte offset
		// within the JSON input of the JSON object for this Go struct.
		ByteOffset int64 `json:"-"` // metadata to be ignored for JSON serialization
	}

	var tunnels []Tunnel
	err := json.UnmarshalOptions{
		// Intercept every attempt to unmarshal into the Tunnel type.
		Unmarshalers: json.UnmarshalFuncV2(func(opts json.UnmarshalOptions, dec *json.Decoder, tunnel *Tunnel) error {
			// Decoder.InputOffset reports the offset after the last token,
			// but we want to record the offset before the next token.
			//
			// Call Decoder.PeekKind to buffer enough to reach the next token.
			// Add the number of leading whitespace, commas, and colons
			// to locate the start of the next token.
			dec.PeekKind()
			unread := dec.UnreadBuffer()
			n := len(unread) - len(bytes.TrimLeft(unread, " \n\r\t,:"))
			tunnel.ByteOffset = dec.InputOffset() + int64(n)

			// Return SkipFunc to fallback on default unmarshal behavior.
			return json.SkipFunc
		}),
	}.Unmarshal(json.DecodeOptions{}, []byte(input), &tunnels)
	if err != nil {
		log.Fatal(err)
	}

	// lineColumn converts a byte offset into a one-indexed line and column.
	// The offset must be within the bounds of the input.
	lineColumn := func(input string, offset int) (line, column int) {
		line = 1 + strings.Count(input[:offset], "\n")
		column = 1 + offset - (strings.LastIndex(input[:offset], "\n") + len("\n"))
		return line, column
	}

	// Verify that the configuration file is valid.
	for _, tunnel := range tunnels {
		if !tunnel.Source.IsValid() || !tunnel.Destination.IsValid() {
			line, column := lineColumn(input, int(tunnel.ByteOffset))
			fmt.Printf("%d:%d: source and destination must both be specified", line, column)
		}
	}

}

Output:

3:3: source and destination must both be specified

func (UnmarshalOptions) Unmarshal 

func (uo UnmarshalOptions) Unmarshal(do DecodeOptions, in []byte, out any) error

Unmarshal deserializes a Go value from a []byte according to the provided unmarshal and decode options. The output must be a non-nil pointer. The input must be a single JSON value with optional whitespace interspersed. See UnmarshalNext for details about the conversion of JSON into a Go value.

func (UnmarshalOptions) UnmarshalFull 

func (uo UnmarshalOptions) UnmarshalFull(do DecodeOptions, in io.Reader, out any) error

UnmarshalFull deserializes a Go value from an io.Reader according to the provided unmarshal and decode options. The output must be a non-nil pointer. The input must be a single JSON value with optional whitespace interspersed. It consumes the entirety of io.Reader until io.EOF is encountered. See UnmarshalNext for details about the conversion of JSON into a Go value.

func (UnmarshalOptions) UnmarshalNext 

func (uo UnmarshalOptions) UnmarshalNext(in *Decoder, out any) error

UnmarshalNext decodes the next JSON value into a Go value according to the provided unmarshal options. The output must be a non-nil pointer.

Type-specific unmarshal functions and methods take precedence over the default representation of a value. Functions or methods that operate on *T are only called when decoding a value of type T (by taking its address) or a non-nil value of *T. UnmarshalNext ensures that a value is always addressable (by boxing it on the heap if necessary) so that these functions and methods can be consistently called.

The input is decoded into the output according the following rules:

Most Go types have a default JSON representation. Certain types support specialized formatting according to a format flag optionally specified in the Go struct tag for the struct field that contains the current value (see the “JSON Representation of Go structs” section for more details). A JSON null may be decoded into every supported Go value where it is equivalent to storing the zero value of the Go value. If the input JSON kind is not handled by the current Go value type, then this fails with a SemanticError. Unless otherwise specified, the decoded value replaces any pre-existing value.

The representation of each type is as follows:

In general, unmarshaling follows merge semantics (similar to RFC 7396) where the decoded Go value replaces the destination value for any JSON kind other than an object. For JSON objects, the input object is merged into the destination value where matching object members recursively apply merge semantics.

type UnmarshalerV1 

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

UnmarshalerV1 is implemented by types that can unmarshal themselves. It is recommended that types implement UnmarshalerV2 unless the implementation is trying to avoid a hard dependency on this package.

The input can be assumed to be a valid encoding of a JSON value if called from unmarshal functionality in this package. UnmarshalJSON must copy the JSON data if it is retained after returning. It is recommended that UnmarshalJSON implement merge semantics when unmarshaling into a pre-populated value.

Implementations must not retain or mutate the input []byte.

type UnmarshalerV2 

type UnmarshalerV2 interface {
	UnmarshalNextJSON(UnmarshalOptions, *Decoder) error
}

UnmarshalerV2 is implemented by types that can unmarshal themselves. It is recommended that types implement UnmarshalerV2 instead of UnmarshalerV1 since this is both more performant and flexible. If a type implements both UnmarshalerV1 and UnmarshalerV2, then UnmarshalerV2 takes precedence. In such a case, both implementations should aim to have equivalent behavior for the default unmarshal options.

The implementation must read only one JSON value from the Decoder. It is recommended that UnmarshalNextJSON implement merge semantics when unmarshaling into a pre-populated value.

Implementations must not retain the pointer to Decoder.

type Unmarshalers 

type Unmarshalers = typedUnmarshalers

Unmarshalers is a list of functions that may override the unmarshal behavior of specific types. Populate UnmarshalOptions.Unmarshalers to use it. A nil *Unmarshalers is equivalent to an empty list.

func NewUnmarshalers 

func NewUnmarshalers(us ...*Unmarshalers) *Unmarshalers

NewUnmarshalers constructs a flattened list of unmarshal functions. If multiple functions in the list are applicable for a value of a given type, then those earlier in the list take precedence over those that come later. If a function returns SkipFunc, then the next applicable function is called, otherwise the default unmarshaling behavior is used.

For example: 

u1 := NewUnmarshalers(f1, f2)
u2 := NewUnmarshalers(f0, u1, f3)     // equivalent to u3
u3 := NewUnmarshalers(f0, f1, f2, f3) // equivalent to u2

func UnmarshalFuncV1 

func UnmarshalFuncV1[T any](fn func([]byte, T) error) *Unmarshalers

UnmarshalFuncV1 constructs a type-specific unmarshaler that specifies how to unmarshal values of type T. T must be an unnamed pointer or an interface type. The function is always provided with a non-nil pointer value.

The function must unmarshal exactly one JSON value. The input []byte must not be mutated. The input []byte and value T must not be retained outside the function call. It may not return SkipFunc.

func UnmarshalFuncV2 

func UnmarshalFuncV2[T any](fn func(UnmarshalOptions, *Decoder, T) error) *Unmarshalers

UnmarshalFuncV2 constructs a type-specific unmarshaler that specifies how to unmarshal values of type T. T must be an unnamed pointer or an interface type. The function is always provided with a non-nil pointer value.

The function must unmarshal exactly one JSON value by calling read methods on the provided decoder. It may return SkipFunc such that unmarshaling can move on to the next unmarshal function. However, no mutable method calls may be called on the decoder if SkipFunc is returned. The pointer to Decoder and the value of T must not be retained outside the function call.

Source Files

arshal.go arshal_any.go arshal_default.go arshal_funcs.go arshal_inlined.go arshal_methods.go arshal_time.go decode.go doc.go encode.go errors.go fields.go fold.go intern.go pools.go state.go token.go value.go

Version
v0.0.0-20250318190949-c8a335a9a2ff (latest)
Published
Mar 18, 2025
Platform
linux/amd64
Imports
20 packages
Last checked
1 month ago –

Tools for package owners.