json

README

sigs.k8s.io/json

Introduction

This library is a subproject of sig-api-machinery. It provides case-sensitive, integer-preserving JSON unmarshaling functions based on encoding/json Unmarshal().

Compatibility

The UnmarshalCaseSensitivePreserveInts() function behaves like encoding/json#Unmarshal() with the following differences:

• JSON object keys are treated case-sensitively. Object keys must exactly match json tag names (for tagged struct fields) or struct field names (for untagged struct fields).
• JSON integers are unmarshaled into interface{} fields as an int64 instead of a float64 when possible, falling back to float64 on any parse or overflow error.
• Syntax errors do not return an encoding/json *SyntaxError error. Instead, they return an error which can be passed to SyntaxErrorOffset() to obtain an offset.

Additional capabilities

The UnmarshalStrict() function decodes identically to UnmarshalCaseSensitivePreserveInts(), and also returns non-fatal strict errors encountered while decoding:

• Duplicate fields encountered
• Unknown fields encountered

Community, discussion, contribution, and support

You can reach the maintainers of this project via the sig-api-machinery mailing list / channels.

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

Documentation

Index

• func SyntaxErrorOffset(err error) (isSyntaxError bool, offset int64)
• func UnmarshalCaseSensitivePreserveInts(data []byte, v interface{}) error
• func UnmarshalStrict(data []byte, v interface{}, strictOptions ...StrictOption) (strictErrors []error, err error)
• type Decoder
  • func NewDecoderCaseSensitivePreserveInts(r io.Reader) Decoder
• type FieldError
• type StrictOption

Functions

func SyntaxErrorOffset

func SyntaxErrorOffset(err error) (isSyntaxError bool, offset int64)

SyntaxErrorOffset returns if the specified error is a syntax error produced by encoding/json or this package.

func UnmarshalCaseSensitivePreserveInts

func UnmarshalCaseSensitivePreserveInts(data []byte, v interface{}) error

UnmarshalCaseSensitivePreserveInts parses the JSON-encoded data and stores the result in the value pointed to by v.

UnmarshalCaseSensitivePreserveInts matches the behavior of encoding/json#Unmarshal, with the following changes:

• When unmarshaling into a struct, JSON keys must case-sensitively match `json` tag names (for tagged struct fields) or struct field names (for untagged struct fields), or they are treated as unknown fields and discarded.
• When unmarshaling a number into an interface value, it is unmarshaled as an int64 if the JSON data does not contain a "." character and parses as an integer successfully and does not overflow int64. Otherwise, the number is unmarshaled as a float64.
• If a syntax error is returned, it will not be of type encoding/json#SyntaxError, but will be recognizeable by this package's IsSyntaxError() function.

func UnmarshalStrict

func UnmarshalStrict(data []byte, v interface{}, strictOptions ...StrictOption) (strictErrors []error, err error)

UnmarshalStrict parses the JSON-encoded data and stores the result in the value pointed to by v. Unmarshaling is performed identically to UnmarshalCaseSensitivePreserveInts(), returning an error on failure.

If parsing succeeds, additional strict checks as selected by `strictOptions` are performed and a list of the strict failures (if any) are returned. If no `strictOptions` are selected, all supported strict checks are performed.

Strict errors returned will implement the FieldError interface for the specific erroneous fields.

Currently supported strict checks are: - DisallowDuplicateFields: ensure the data contains no duplicate fields - DisallowUnknownFields: ensure the data contains no unknown fields (when decoding into typed structs)

Additional strict checks may be added in the future.

Note that the strict checks do not change what is stored in v. For example, if duplicate fields are present, they will be parsed and stored in v, and errors about the duplicate fields will be returned in the strict error list.

Types

type Decoder

type Decoder interface {
	Decode(v interface{}) error
	Buffered() io.Reader
	Token() (gojson.Token, error)
	More() bool
	InputOffset() int64
}

Decoder describes the decoding API exposed by `encoding/json#Decoder`

func NewDecoderCaseSensitivePreserveInts

func NewDecoderCaseSensitivePreserveInts(r io.Reader) Decoder

NewDecoderCaseSensitivePreserveInts returns a decoder that matches the behavior of encoding/json#NewDecoder, with the following changes:

• When unmarshaling into a struct, JSON keys must case-sensitively match `json` tag names (for tagged struct fields) or struct field names (for untagged struct fields), or they are treated as unknown fields and discarded.
• When unmarshaling a number into an interface value, it is unmarshaled as an int64 if the JSON data does not contain a "." character and parses as an integer successfully and does not overflow int64. Otherwise, the number is unmarshaled as a float64.
• If a syntax error is returned, it will not be of type encoding/json#SyntaxError, but will be recognizeable by this package's IsSyntaxError() function.

type FieldError

type FieldError interface {
	error
	// FieldPath provides the full path of the erroneous field within the json object.
	FieldPath() string
	// SetFieldPath updates the path of the erroneous field output in the error message.
	SetFieldPath(path string)
}

FieldError is an error that provides access to the path of the erroneous field

type StrictOption

type StrictOption int

const (
	// DisallowDuplicateFields returns strict errors if data contains duplicate fields
	DisallowDuplicateFields StrictOption = 1

	// DisallowUnknownFields returns strict errors if data contains unknown fields when decoding into typed structs
	DisallowUnknownFields StrictOption = 2
)