doc_format.go

     1  // Copyright 2026 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:build goexperiment.jsonv2 && goexperiment.jsonformat
     6  
     7  // # Format Tag Option
     8  //
     9  // The `format` tag option is experimental,
    10  // and not subject to the Go 1 compatibility promise.
    11  // It only exists when building with the GOEXPERIMENT=jsonformat environment variable set.
    12  //
    13  // Some Go types support alternative JSON representations as specified below.
    14  // The `format` tag option is a key-value pair specified as "format:value"
    15  // where the value must be either a literal consisting of letters and numbers
    16  // (e.g., "format:RFC3339") or a single-quoted string literal
    17  // (e.g., "format:'2006-01-02'"). The interpretation of the format option
    18  // is determined by the struct field type.
    19  //
    20  // Go types with alternative representations are as follows:
    21  //
    22  //   - A Go []byte or [N]byte is usually represented as a JSON string
    23  //     containing the binary value encoded using RFC 4648.
    24  //     If the format is "base64" or unspecified, then this uses RFC 4648, section 4.
    25  //     If the format is "base64url", then this uses RFC 4648, section 5.
    26  //     If the format is "base32", then this uses RFC 4648, section 6.
    27  //     If the format is "base32hex", then this uses RFC 4648, section 7.
    28  //     If the format is "base16" or "hex", then this uses RFC 4648, section 8.
    29  //     If the format is "array", then the bytes value is represented as a JSON array
    30  //     where each element recursively uses the JSON representation of each byte.
    31  //
    32  //   - A Go float is usually represented as a JSON number.
    33  //     If the format is "nonfinite", then NaN, +Inf, and -Inf are represented as
    34  //     the JSON strings "NaN", "Infinity", and "-Infinity", respectively.
    35  //     Without the use of this format, such string values result in a [SemanticError].
    36  //
    37  //   - A nil Go map is usually encoded using an empty JSON object.
    38  //     If the format is "emitnull", then a nil map is encoded as a JSON null.
    39  //     If the format is "emitempty", then a nil map is encoded as an empty JSON object,
    40  //     regardless of whether [FormatNilMapAsNull] is specified.
    41  //
    42  //   - A nil Go slice is usually encoded using an empty JSON array.
    43  //     If the format is "emitnull", then a nil slice is encoded as a JSON null.
    44  //     If the format is "emitempty", then a nil slice is encoded as an empty JSON array,
    45  //     regardless of whether [FormatNilSliceAsNull] is specified.
    46  //
    47  //   - A Go pointer usually uses the JSON representation of the underlying value.
    48  //     The format is forwarded to the marshaling and unmarshaling of the underlying type.
    49  //
    50  //   - A Go [time.Time] is usually represented as a JSON string containing
    51  //     the timestamp formatted in RFC 3339 with nanosecond precision.
    52  //     If the format matches one of the format constants declared
    53  //     in the time package (e.g., RFC1123), then that format is used.
    54  //     If the format is "unix", "unixmilli", "unixmicro", or "unixnano",
    55  //     then the timestamp is represented as a possibly fractional JSON number
    56  //     of the number of seconds (or milliseconds, microseconds, or nanoseconds)
    57  //     since the Unix epoch, which is January 1st, 1970 at 00:00:00 UTC.
    58  //     To avoid a fractional component when encoding,
    59  //     round the timestamp to the relevant unit.
    60  //     Otherwise if non-empty, the format is used as-is and
    61  //     encoded using [time.Time.Format] and
    62  //     decoded using [time.Time.Parse].
    63  //
    64  //   - A Go [time.Duration] usually has no default representation.
    65  //     If the format is "sec", "milli", "micro", or "nano",
    66  //     then the duration is represented as a possibly fractional JSON number
    67  //     of the number of seconds (or milliseconds, microseconds, or nanoseconds).
    68  //     To avoid a fractional component when encoding,
    69  //     round the duration to the relevant unit.
    70  //     If the format is "units", it is represented as a JSON string
    71  //     encoded using [time.Duration.String] and decoded using [time.ParseDuration]
    72  //     (e.g., "1h30m" for 1 hour 30 minutes).
    73  //     If the format is "iso8601", it is represented as a JSON string using the
    74  //     ISO 8601 standard for durations (e.g., "PT1H30M" for 1 hour 30 minutes)
    75  //     using only accurate units of hours, minutes, and seconds.
    76  package json
    77
View as plain text