Documentation
¶
Overview ¶
Package jsonx provides helpers for json in/out operations
Index ¶
- Variables
- func ApplyOverlay[T any](base T, overlay any) (T, error)
- func CloneRawMessage(raw json.RawMessage) json.RawMessage
- 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 PropertyNames[T any]() []string
- func RoundTrip(input any, output any) error
- func SchemaFrom[T any]() json.RawMessage
- func SchemaID(schema json.RawMessage) string
- 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 ValidateSchema(schema any, document any) (*gojsonschema.Result, error)
- func ValidationErrorStrings(result *gojsonschema.Result) []string
- type PropertyDescriptor
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") )
var Reflector = &jsonschema.Reflector{ AllowAdditionalProperties: false, RequiredFromJSONSchemaTags: true, }
Reflector is the shared JSON schema reflector used by SchemaFrom and SchemaID.
Functions ¶
func ApplyOverlay ¶
ApplyOverlay applies a JSON overlay to an existing typed value
func CloneRawMessage ¶
func CloneRawMessage(raw json.RawMessage) json.RawMessage
CloneRawMessage copies a raw JSON document to avoid accidental aliasing
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 decodes one top-level key of a raw JSON object into a typed value, reporting false when the document is not an object, the key is absent, or the value does not decode as T
func DeepMerge ¶
func DeepMerge(base, patch json.RawMessage) (json.RawMessage, bool, error)
DeepMerge deep-merges patch into base and reports whether the document changed. Both arguments must be JSON objects. Returns the merged document and a boolean indicating whether the result differs from base
func EditObject ¶
func EditObject(raw json.RawMessage, edit func(doc map[string]json.RawMessage) bool) json.RawMessage
EditObject decodes a raw JSON object, lets edit mutate its top-level keys, and re-marshals the result. edit reports whether it changed the document; undecodable input, unchanged documents, and re-marshal failures return the original document, making the edit best-effort
func InjectDefaults ¶
func InjectDefaults(schema json.RawMessage, defaults map[string]any) (json.RawMessage, error)
InjectDefaults returns the schema document as raw JSON with stored values injected as "default" at every level of nesting, following $ref pointers into $defs recursively. Using jsonschema.Schema preserves the original property ordering on serialization.
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 PropertyNames ¶
PropertyNames reflects a Go type and returns the top-level JSON property names from the generated JSON schema. Properties from embedded structs are promoted by the reflector and appear as top-level names.
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 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 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 reflects a Go type and returns its top-level JSON properties with names and descriptions from the generated JSON schema. Properties from embedded structs are promoted by the reflector and appear as top-level entries.
Source Files