Documentation
¶
Overview ¶
Package strictjson decodes JSON so that what a reader sees in the text is exactly what the decoded value holds. encoding/json accepts a duplicate key and keeps the last value, matches keys case-insensitively, ignores unknown fields, and rewrites invalid UTF-8 and escaped lone surrogates to U+FFFD; each lets one text mean a value other than the one it shows. The checks here reject all of them, token by token against the target type, before encoding/json decodes.
The audit package reads proof artifacts with it (audit.UnmarshalStrict) and the agent package reads tool arguments and typed answers with it, which also requires every field schema.For lists as required.
Index ¶
- Variables
- func Check(data []byte, t reflect.Type, opts *Options) error
- func CheckValue(raw []byte, t reflect.Type, path string, opts *Options) error
- func ExactFields(t reflect.Type) map[string]Field
- func SchemaFields(t reflect.Type) map[string]Field
- func Unmarshal(data []byte, v any, opts *Options) error
- type Field
- type Options
Constants ¶
This section is empty.
Variables ¶
var ErrTrailingData = errors.New("trailing data after the value")
ErrTrailingData reports data after the one JSON value.
Functions ¶
func Check ¶
Check consumes the one JSON value in data, checking it against t, and returns ErrTrailingData if anything but whitespace follows. An object decoded into a struct may use only that struct's exact JSON field names, each at most once, and must include each required one, with a value other than null unless the field takes null (Field.NullOK); every other object (a map, raw JSON, a type with its own UnmarshalJSON, an interface) is checked for duplicate names only, at any depth. Strings decoded into Go must have one spelling: no escaped lone surrogate, and in a []byte, base64 that is the standard encoding of its bytes. JSON kept verbatim (json.RawMessage) is checked for duplicate names only.
func CheckValue ¶
CheckValue checks the first JSON value in raw against t, as Check does, naming path in its errors. It does not look past that value.
func ExactFields ¶
ExactFields returns the exact JSON names encoding/json decodes into struct type t, with each field's type, by encoding/json's own rules: exported fields by tag name or Go name (a "-" tag is skipped), and the fields of an untagged embedded struct promoted into t. When several fields claim one name, the shallowest wins, and at equal depth a tagged field wins over an untagged one. A name still claimed by several fields is one encoding/json ignores; it is kept here, and the decode that follows (DisallowUnknownFields) rejects it. No field is required, and every field takes null.
func SchemaFields ¶
SchemaFields returns the names struct type t accepts as schema.For describes them: the fields encoding/json reads (jsonfields.Of), each required exactly when the schema lists it as required. A required field takes null only when its schema admits any value (For leaves an interface, json.RawMessage, or a json.Unmarshaler other than time.Time unconstrained); otherwise encoding/json would read null as the zero value, one the document never gave. An optional field takes null (OpenAI strict mode sends it). A type jsonfields cannot resolve accepts no names.
Types ¶
type Field ¶
Field is one name a struct accepts: the type its value decodes into, whether a document must include it, and whether it may be null.
type Options ¶
type Options struct {
// Fields returns the names struct type t accepts, each exactly as spelled. Nil means
// ExactFields.
Fields func(t reflect.Type) map[string]Field
// Shapes maps a type to the type its JSON is checked against instead: for a type whose own
// UnmarshalJSON matches names loosely, its wire shape.
Shapes map[reflect.Type]reflect.Type
// Hooks maps a type to a check of its own: the value is consumed (checked for duplicate
// names only) and its raw text, with the path to it, is handed to the hook.
Hooks map[reflect.Type]func(raw []byte, path string) error
// AllowUnknown lets an object decoded into a struct carry names the struct does not have, as a
// document written by a later version does. Such a name must not be a case variant of a name
// the struct has ("Kind" beside a "kind" field), which encoding/json would read into that
// field; its value is checked like any value decoded into Go: no duplicate names at any depth
// and no escaped lone surrogate.
AllowUnknown bool
}
Options configure a check.
Source Files