Documentation
¶
Overview ¶
Package jsonx provides helpers for json in/out operations
Index ¶
- Variables
- func AllowAdditionalProperties(schema json.RawMessage) json.RawMessage
- func CloneRawMessage(raw json.RawMessage) json.RawMessage
- func ConformToSchema(schema, doc json.RawMessage) (json.RawMessage, error)
- func Decode[T any](raw json.RawMessage) (T, error)
- func DecodeAnyOrNil(raw json.RawMessage) any
- func DecodeObjectKey[T any](raw json.RawMessage, key string) (T, bool)
- func DeepMerge(base, patch json.RawMessage) (json.RawMessage, bool, error)
- func EditObject(raw json.RawMessage, edit func(doc map[string]json.RawMessage) bool) json.RawMessage
- func InjectDefaults(schema json.RawMessage, defaults map[string]any) (json.RawMessage, error)
- func IsEmptyRawMessage(raw json.RawMessage) bool
- func MergeObjectMap(base json.RawMessage, patch map[string]json.RawMessage) (json.RawMessage, bool, error)
- func RoundTrip(input any, output any) error
- func SchemaFrom[T any]() json.RawMessage
- func SchemaID(schema json.RawMessage) string
- func SchemaRoot(schema json.RawMessage) (*jsonschema.Schema, jsonschema.Definitions, error)
- func SetObjectKey(base json.RawMessage, key string, value any) (json.RawMessage, bool, error)
- func Stringify(value any) string
- func ToMap(value any) (map[string]any, error)
- func ToRawMap(value any) (map[string]json.RawMessage, error)
- func ToRawMessage(value any) (json.RawMessage, error)
- func UnmarshalIfPresent(raw json.RawMessage, output any) error
- func Validate(schema, payload json.RawMessage) error
- func ValidateSchema(schema any, document any) (*gojsonschema.Result, error)
- func ValidationErrorStrings(result *gojsonschema.Result) []string
- type PropertyDescriptor
- type SchemaError
Constants ¶
This section is empty.
Variables ¶
var ( // ErrObjectExpected is returned when a JSON round-trip does not produce an object ErrObjectExpected = errors.New("json value is not an object") // ErrKeyRequired is returned when a JSON object key is empty ErrKeyRequired = errors.New("json key is required") // ErrSchemaRefUnresolved is returned when a schema $ref points outside the schema document ErrSchemaRefUnresolved = errors.New("json schema ref could not be resolved") // ErrSchemaInvalid is returned when a document does not satisfy its JSON schema ErrSchemaInvalid = errors.New("json document does not satisfy schema") )
Functions ¶
func AllowAdditionalProperties ¶
func AllowAdditionalProperties(schema json.RawMessage) json.RawMessage
AllowAdditionalProperties returns the schema with additional properties permitted on the root type, for validating payloads that carry fields deliberately excluded from the authored schema
func CloneRawMessage ¶
func CloneRawMessage(raw json.RawMessage) json.RawMessage
CloneRawMessage copies a raw JSON document to avoid accidental aliasing
func ConformToSchema ¶
func ConformToSchema(schema, doc json.RawMessage) (json.RawMessage, error)
ConformToSchema returns doc with undeclared properties stripped and required defaults filled
func Decode ¶
func Decode[T any](raw json.RawMessage) (T, error)
Decode unmarshals a json.RawMessage into a typed value
func DecodeAnyOrNil ¶
func DecodeAnyOrNil(raw json.RawMessage) any
DecodeAnyOrNil decodes raw JSON to an untyped value or returns nil on failure/empty input
func DecodeObjectKey ¶
func DecodeObjectKey[T any](raw json.RawMessage, key string) (T, bool)
DecodeObjectKey returns one top-level key of raw JSON decoded as T
func DeepMerge ¶
func DeepMerge(base, patch json.RawMessage) (json.RawMessage, bool, error)
DeepMerge returns patch deep-merged into base and whether it changed
func EditObject ¶
func EditObject(raw json.RawMessage, edit func(doc map[string]json.RawMessage) bool) json.RawMessage
EditObject returns raw JSON with edit applied to its top-level keys
func InjectDefaults ¶
func InjectDefaults(schema json.RawMessage, defaults map[string]any) (json.RawMessage, error)
InjectDefaults returns the schema with stored values injected as defaults
func IsEmptyRawMessage ¶
func IsEmptyRawMessage(raw json.RawMessage) bool
IsEmptyRawMessage reports whether a raw JSON message is empty or null
func MergeObjectMap ¶
func MergeObjectMap(base json.RawMessage, patch map[string]json.RawMessage) (json.RawMessage, bool, error)
MergeObjectMap shallow-merges a raw JSON object with the supplied top-level patch map
func SchemaFrom ¶
func SchemaFrom[T any]() json.RawMessage
SchemaFrom reflects a JSON schema from a Go type and returns it as raw JSON
func SchemaID ¶
func SchemaID(schema json.RawMessage) string
SchemaID extracts the definition key from a reflected JSON schema's $ref path
func SchemaRoot ¶
func SchemaRoot(schema json.RawMessage) (*jsonschema.Schema, jsonschema.Definitions, error)
SchemaRoot decodes a raw schema and follows its root $ref into its definitions
func SetObjectKey ¶
func SetObjectKey(base json.RawMessage, key string, value any) (json.RawMessage, bool, error)
SetObjectKey sets or replaces one top-level key in a raw JSON object
func Stringify ¶
Stringify renders an arbitrary decoded JSON value as its JSON string form for downstream text processing. Strings pass through unchanged; nil, empty slices, JSON null, and unmarshalable values render as the empty string
func ToRawMap ¶
func ToRawMap(value any) (map[string]json.RawMessage, error)
ToRawMap converts an arbitrary value into a JSON object map of raw values
func ToRawMessage ¶
func ToRawMessage(value any) (json.RawMessage, error)
ToRawMessage converts an arbitrary value into a raw JSON document
func UnmarshalIfPresent ¶
func UnmarshalIfPresent(raw json.RawMessage, output any) error
UnmarshalIfPresent unmarshals raw JSON when it is non-empty
func Validate ¶
func Validate(schema, payload json.RawMessage) error
Validate checks a payload against a JSON schema, treating an empty schema as unconstrained and an absent payload as an empty object
func ValidateSchema ¶
func ValidateSchema(schema any, document any) (*gojsonschema.Result, error)
ValidateSchema validates a JSON document against a JSON schema and returns the raw gojsonschema result for caller-specific error handling.
func ValidationErrorStrings ¶
func ValidationErrorStrings(result *gojsonschema.Result) []string
ValidationErrorStrings converts schema validation errors into string messages.
Types ¶
type PropertyDescriptor ¶
type PropertyDescriptor struct {
// Name is the JSON property key as it appears in the reflected schema
Name string
// Description is the human-readable description extracted from the jsonschema description tag
Description string
}
PropertyDescriptor is a top-level JSON schema property with its name and description
func PropertyDescriptors ¶
func PropertyDescriptors[T any]() []PropertyDescriptor
PropertyDescriptors returns a Go type's top-level JSON schema properties
type SchemaError ¶
type SchemaError struct {
// Issues lists each validation failure in schema order
Issues []string
}
SchemaError reports the issues a document raised against its JSON schema
func (*SchemaError) Error ¶
func (e *SchemaError) Error() string
Error joins the issues into one message
func (*SchemaError) Unwrap ¶
func (e *SchemaError) Unwrap() error
Unwrap exposes ErrSchemaInvalid so callers can match on the sentinel
Source Files