Documentation
¶
Overview ¶
Package jsonformat provides custom JSON representation for common Go types.
For custom representations of time.Time, see:
For custom representations of time.Duration, see:
For custom representations of slices and maps, see:
History and future ¶
The github.com/go-json-experiment/json package was the prototype implementation for what became encoding/json/v2. That prototype originally provided a `format` tag option that allowed certain types to customize their exact JSON representation. See github.com/go-json-experiment/json.ExperimentalSupportFormatTag.
While there was widespread support for the concept of custom per-type formatting in encoding/json/v2, there was also concern about its use of a bespoke DSL to express formatting directives. Consequently, support for the `format` tag was removed from the initial release of encoding/json/v2 in Go 1.27.
The hope is that "typed struct tags" (see https://go.dev/issues/74472) will land in a future release of Go, in which case encoding/json/v2 will make use of typed struct tags to express formatting directives in a more natural way without resorting to inventing its own DSL.
This package exists as an intermediate step to support custom formats while encoding/json/v2 currently does not directly support it. Once the Go standard library supports such a feature, existing usages of this package are expected to migrate to using typed struct tags to express formatting.
In the future, this package may be deleted.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DurationISO8601 ¶
DurationISO8601 is a time.Duration that represents a duration as a JSON string using a subset of the ISO 8601 format. In particular, it uses the exact grammar of ISO 8601 that JavaScript uses for its Temporal.Duration type.
While this format is relatively novel in the Go ecosystem, the fact that JSON finds its heritage in JavaScript and that JavaScript has adopted ISO 8601 as the JSON representation for durations suggests that JavaScript's particular flavor of ISO 8601 may well become the de facto standard for representing durations across the industry.
func (DurationISO8601) MarshalJSON ¶
func (d DurationISO8601) MarshalJSON() ([]byte, error)
func (DurationISO8601) MarshalJSONTo ¶
func (d DurationISO8601) MarshalJSONTo(enc *jsontext.Encoder) error
func (*DurationISO8601) UnmarshalJSON ¶
func (d *DurationISO8601) UnmarshalJSON(b []byte) error
func (*DurationISO8601) UnmarshalJSONFrom ¶
func (d *DurationISO8601) UnmarshalJSONFrom(dec *jsontext.Decoder) error
type DurationNano ¶
DurationNano is a time.Duration that represents a duration as a JSON number of nanoseconds. If json.StringifyNumbers is specified, then it represents the duration as a JSON number within a JSON string.
This format is what v1 encoding/json historically used for durations. It is not recommended that newly defined types represent durations using this format, as a standalone JSON number lacks context as to the units of the duration.
func (DurationNano) MarshalJSON ¶
func (d DurationNano) MarshalJSON() ([]byte, error)
func (DurationNano) MarshalJSONTo ¶
func (d DurationNano) MarshalJSONTo(enc *jsontext.Encoder) error
func (*DurationNano) UnmarshalJSON ¶
func (d *DurationNano) UnmarshalJSON(b []byte) error
func (*DurationNano) UnmarshalJSONFrom ¶
func (d *DurationNano) UnmarshalJSONFrom(dec *jsontext.Decoder) error
type DurationUnits ¶
DurationUnits is a time.Duration that represents a duration as a JSON string using the format of time.Duration.String.
While this format is human-readable (e.g., "43m17.152s"), it is also highly specific to the Go ecosystem (and not used elsewhere in the industry).
func (DurationUnits) MarshalJSON ¶
func (d DurationUnits) MarshalJSON() ([]byte, error)
func (DurationUnits) MarshalJSONTo ¶
func (d DurationUnits) MarshalJSONTo(enc *jsontext.Encoder) error
func (*DurationUnits) UnmarshalJSON ¶
func (d *DurationUnits) UnmarshalJSON(b []byte) error
func (*DurationUnits) UnmarshalJSONFrom ¶
func (d *DurationUnits) UnmarshalJSONFrom(dec *jsontext.Decoder) error
type MapEmitEmpty ¶
type MapEmitEmpty[K comparable, V any] map[K]V
MapEmitEmpty is a generic map where nil marshals as an empty JSON object.
func (MapEmitEmpty[K, V]) MarshalJSON ¶
func (m MapEmitEmpty[K, V]) MarshalJSON() ([]byte, error)
func (MapEmitEmpty[K, V]) MarshalJSONTo ¶
func (m MapEmitEmpty[K, V]) MarshalJSONTo(enc *jsontext.Encoder) error
type SliceEmitEmpty ¶
type SliceEmitEmpty[E any] []E
SliceEmitEmpty is a generic slice where nil marshals as an empty JSON array.
func (SliceEmitEmpty[E]) MarshalJSON ¶
func (s SliceEmitEmpty[E]) MarshalJSON() ([]byte, error)
func (SliceEmitEmpty[E]) MarshalJSONTo ¶
func (s SliceEmitEmpty[E]) MarshalJSONTo(enc *jsontext.Encoder) error
type TimeRFC1123 ¶
TimeRFC1123 is a time.Time that represents time as a JSON string formatted using time.RFC1123.
func (TimeRFC1123) MarshalJSON ¶
func (t TimeRFC1123) MarshalJSON() ([]byte, error)
func (TimeRFC1123) MarshalJSONTo ¶
func (t TimeRFC1123) MarshalJSONTo(enc *jsontext.Encoder) error
func (*TimeRFC1123) UnmarshalJSON ¶
func (t *TimeRFC1123) UnmarshalJSON(b []byte) error
func (*TimeRFC1123) UnmarshalJSONFrom ¶
func (t *TimeRFC1123) UnmarshalJSONFrom(dec *jsontext.Decoder) error
type TimeUnix ¶
TimeUnix is a time.Time that represents time as a JSON number of seconds since the Unix epoch. If json.StringifyNumbers is specified, then it represents the time as a JSON number within a JSON string.
Note that this format preserves the fractional number of seconds. To encode just the seconds as an integer, call time.Time.Round prior to JSON marshaling.
func (TimeUnix) MarshalJSON ¶
func (*TimeUnix) UnmarshalJSON ¶
type TimeUnixNano ¶
TimeUnixNano is a time.Time that represents time as a JSON number of nanoseconds since the Unix epoch. If json.StringifyNumbers is specified, then it represents the time as a JSON number within a JSON string.
func (TimeUnixNano) MarshalJSON ¶
func (t TimeUnixNano) MarshalJSON() ([]byte, error)
func (TimeUnixNano) MarshalJSONTo ¶
func (t TimeUnixNano) MarshalJSONTo(enc *jsontext.Encoder) error
func (*TimeUnixNano) UnmarshalJSON ¶
func (t *TimeUnixNano) UnmarshalJSON(b []byte) error
func (*TimeUnixNano) UnmarshalJSONFrom ¶
func (t *TimeUnixNano) UnmarshalJSONFrom(dec *jsontext.Decoder) error
Source Files