@ttsc/win32-arm64 0.33.1 → 0.34.0

package/bin/go/src/encoding/json/v2/doc.go

@@ -9,10 +9,7 @@
 // primitive data types such as booleans, strings, and numbers,
 // in addition to structured data types such as objects and arrays.
 //
-// This package (encoding/json/v2) is experimental,
-// and not subject to the Go 1 compatibility promise.
-// It only exists when building with the GOEXPERIMENT=jsonv2 environment variable set.
-// Most users should use [encoding/json].
+// See the [Working with JSON] tutorial for an introduction to this package.
 //
 // [Marshal] and [Unmarshal] encode and decode Go values
 // to/from JSON text contained within a []byte.
@@ -58,7 +55,7 @@
 // if [RejectUnknownMembers] is specified.
 //
 // The representation of each struct field can be customized in the
-// "json" struct field tag, where the tag is a comma separated list of options.
+// "json" struct field tag, where the tag is a comma-separated list of options.
 // As a special case, if the entire tag is `json:"-"`,
 // then the field is ignored with regard to its JSON representation.
 // Some options also have equivalent behavior controlled by a caller-specified [Options].
@@ -66,11 +63,7 @@
 //
 // The first option is the JSON object name override for the Go struct field.
 // If the name is not specified, then the Go struct field name
-// is used as the JSON object name. JSON names containing commas or quotes,
-// or names identical to "" or "-", can be specified using
-// a single-quoted string literal, where the syntax is identical to
-// the Go grammar for a double-quoted string literal,
-// but instead uses single quotes as the delimiters.
+// is used as the JSON object name.
 // By default, unmarshaling uses case-sensitive matching to identify
 // the Go struct field associated with a JSON object name.
 //
@@ -87,60 +80,49 @@
 //     encoded as a JSON null, empty string, empty object, or empty array.
 //     This option has no effect when unmarshaling.
 //
-//   - string: The "string" option specifies that [StringifyNumbers]
-//     be set when marshaling or unmarshaling a struct field value.
-//     This causes numeric types to be encoded as a JSON number
-//     within a JSON string, and to be decoded from a JSON string
-//     containing the JSON number without any surrounding whitespace.
-//     This extra level of encoding is often necessary since
-//     many JSON parsers cannot precisely represent 64-bit integers.
+//   - string: The "string" option specifies that [StringifyNumbers] be set
+//     when marshaling or unmarshaling a struct field value.
+//     This causes types that would normally be encoded as a JSON number
+//     to instead be encoded as a JSON number quoted within a JSON string,
+//     and to be decoded from a JSON string containing the JSON number
+//     without any surrounding whitespace.
+//     The "string" option only applies to the top-level of the Go struct field
+//     value. It is an error to apply this option to any type that does not
+//     encode as a JSON number.
+//     Note that composite types such as arrays, slices, structs, and maps do
+//     not encode as a JSON number, so applying this option will cause an error
+//     rather than affecting JSON numbers within such types.
+//     This extra level of encoding is often necessary since many JSON parsers
+//     cannot precisely represent 64-bit integers.
 //
 //   - case: When unmarshaling, the "case" option specifies how
 //     JSON object names are matched with the JSON name for Go struct fields.
 //     The option is a key-value pair specified as "case:value" where
 //     the value must either be 'ignore' or 'strict'.
-//     The 'ignore' value specifies that matching is case-insensitive
-//     where dashes and underscores are also ignored. If multiple fields match,
-//     the first declared field in breadth-first order takes precedence.
+//     The 'ignore' value specifies that matching is case-insensitive,
+//     and also ignores dashes and underscores. If multiple fields match,
+//     then the field with an exact name match is selected, otherwise an error
+//     is reported because the choice of field to unmarshal into is ambiguous.
 //     The 'strict' value specifies that matching is case-sensitive.
 //     This takes precedence over the [MatchCaseInsensitiveNames] option.
 //
-//   - inline: The "inline" option specifies that
+//   - embed: The "embed" option specifies that
 //     the JSON representable content of this field type is to be promoted
-//     as if they were specified in the parent struct.
+//     as if it were specified in the parent struct.
 //     It is the JSON equivalent of Go struct embedding.
-//     A Go embedded field is implicitly inlined unless an explicit JSON name
-//     is specified. The inlined field must be a Go struct
+//     A Go embedded field is implicitly JSON embedded unless
+//     an explicit JSON name is specified. The embedded field must be a Go struct
 //     (that does not implement any JSON methods), [jsontext.Value],
 //     map[~string]T, or an unnamed pointer to such types. When marshaling,
-//     inlined fields from a pointer type are omitted if it is nil.
-//     Inlined fields of type [jsontext.Value] and map[~string]T are called
-//     “inlined fallbacks” as they can represent all possible
+//     embedded fields from a pointer type are omitted if it is nil.
+//     Embedded fields of type [jsontext.Value] and map[~string]T are called
+//     “embedded fallbacks” as they can represent all possible
 //     JSON object members not directly handled by the parent struct.
-//     Only one inlined fallback field may be specified in a struct,
+//     Only one embedded fallback field may be specified in a struct,
 //     while many non-fallback fields may be specified. This option
 //     must not be specified with any other option (including the JSON name).
 //
-//   - unknown: The "unknown" option is a specialized variant
-//     of the inlined fallback to indicate that this Go struct field
-//     contains any number of unknown JSON object members. The field type must
-//     be a [jsontext.Value], map[~string]T, or an unnamed pointer to such types.
-//     If [DiscardUnknownMembers] is specified when marshaling,
-//     the contents of this field are ignored.
-//     If [RejectUnknownMembers] is specified when unmarshaling,
-//     any unknown object members are rejected regardless of whether
-//     an inlined fallback with the "unknown" option exists. This option
-//     must not be specified with any other option (including the JSON name).
-//
-//   - format: The "format" option specifies a format flag
-//     used to specialize the formatting of the field value.
-//     The option is a key-value pair specified as "format:value" where
-//     the value must be either a literal consisting of letters and numbers
-//     (e.g., "format:RFC3339") or a single-quoted string literal
-//     (e.g., "format:'2006-01-02'"). The interpretation of the format flag
-//     is determined by the struct field type.
-//
-// The "omitzero" and "omitempty" options are mostly semantically identical.
+// The "omitzero" and "omitempty" options behave similarly.
 // The former is defined in terms of the Go type system,
 // while the latter in terms of the JSON type system.
 // Consequently they behave differently in some circumstances.
@@ -149,14 +131,14 @@
 // The "omitzero" option is useful for types with a well-defined zero value
 // (e.g., [net/netip.Addr]) or have an IsZero method (e.g., [time.Time.IsZero]).
 //
-// Every Go struct corresponds to a list of JSON representable fields
+// Every Go struct corresponds to a list of JSON-representable fields
 // which is constructed by performing a breadth-first search over
 // all struct fields (excluding unexported or ignored fields),
-// where the search recursively descends into inlined structs.
-// The set of non-inlined fields in a struct must have unique JSON names.
+// where the search recursively descends into embedded structs.
+// The set of non-embedded fields in a struct must have unique JSON names.
 // If multiple fields all have the same JSON name, then the one
 // at shallowest depth takes precedence and the other fields at deeper depths
-// are excluded from the list of JSON representable fields.
+// are excluded from the list of JSON-representable fields.
 // If multiple fields at the shallowest depth have the same JSON name,
 // but exactly one is explicitly tagged with a JSON name,
 // then that field takes precedence and all others are excluded from the list.
@@ -164,7 +146,9 @@
 // with embedded struct types.
 //
 // Marshaling or unmarshaling a non-empty struct
-// without any JSON representable fields results in a [SemanticError].
+// without any JSON-representable fields results in a [SemanticError],
+// unless the Go struct has a field with an explicit `json` tag,
+// which signals that the type has a valid JSON representation (even if empty).
 // Unexported fields must not have any `json` tags except for `json:"-"`.
 //
 // # Security Considerations
@@ -176,8 +160,8 @@
 //
 // [For example, suppose we have two micro-services.]
 // The first service is responsible for authenticating a JSON request,
-// while the second service is responsible for executing the request
-// (having assumed that the prior service authenticated the request).
+// while the second service is responsible for executing the request,
+// assuming that it was authenticated.
 // If an attacker were able to maliciously craft a JSON request such that
 // both services believe that the same request is from different users,
 // it could bypass the authenticator with valid credentials for one user,
@@ -259,6 +243,7 @@
 // The v2 API generally chooses more secure defaults than v1,
 // but care should still be taken with large integers or unknown members.
 //
+// [Working with JSON]: https://go.dev/doc/tutorial/json
 // [For example, suppose we have two micro-services.]: https://www.youtube.com/watch?v=avilmOcHKHE&t=1057s
 package json
 

package/bin/go/src/encoding/json/v2/errors.go

@@ -39,6 +39,10 @@ import (
 // This error is only returned if [RejectUnknownMembers] is true.
 var ErrUnknownName = errors.New("unknown object member name")
 
+// errAmbiguousName indicates a JSON object member could be unmarshal
+// into multiple candidate Go struct fields.
+var errAmbiguousName = errors.New("ambiguous object member name")
+
 const errorPrefix = "json: "
 
 func isSemanticError(err error) bool {
@@ -51,7 +55,7 @@ func isSyntacticError(err error) bool {
 	return ok
 }
 
-// isFatalError reports whether this error must terminate asharling.
+// isFatalError reports whether this error must terminate arshaling.
 // All errors are considered fatal unless operating under
 // [jsonflags.ReportErrorsWithLegacySemantics] in which case only
 // syntactic errors and I/O errors are considered fatal.
@@ -61,7 +65,7 @@ func isFatalError(err error, flags jsonflags.Flags) bool {
 }
 
 // SemanticError describes an error determining the meaning
-// of JSON data as Go data or vice-versa.
+// of JSON data as Go data, or vice versa.
 //
 // If a [Marshaler], [MarshalerTo], [Unmarshaler], or [UnmarshalerFrom] method
 // returns a SemanticError when called by the [json] package,
@@ -75,7 +79,7 @@ type SemanticError struct {
 
 	action string // either "marshal" or "unmarshal"
 
-	// ByteOffset indicates that an error occurred after this byte offset.
+	// ByteOffset indicates that an error occurred at or after this byte offset.
 	ByteOffset int64
 	// JSONPointer indicates that an error occurred within this JSON value
 	// as indicated using the JSON Pointer notation (see RFC 6901).
@@ -99,9 +103,9 @@ type coder interface {
 	Options() Options
 }
 
-// newInvalidFormatError wraps err in a SemanticError because
+// newInvalidFormatError constructs a SemanticError because
 // the current type t cannot handle the provided options format.
-// This error must be called before producing or consuming the next value.
+// This function must be called before producing or consuming the next value.
 //
 // If [jsonflags.ReportErrorsWithLegacySemantics] is specified,
 // then this automatically skips the next value when unmarshaling
@@ -159,13 +163,22 @@ func newUnmarshalErrorBeforeWithSkipping(d *jsontext.Decoder, t reflect.Type, er
 // is positioned right after the previous token or value, which caused an error.
 func newUnmarshalErrorAfter(d *jsontext.Decoder, t reflect.Type, err error) error {
 	tokOrVal := export.Decoder(d).PreviousTokenOrValue()
+	byteOffset := d.InputOffset() - int64(len(tokOrVal))
+	if export.Decoder(d).Flags.Get(jsonflags.ReportErrorsWithLegacySemantics) {
+		// NOTE: In v1, the offset pointed to the end of the bad token or value.
+		if k := jsontext.Value(tokOrVal).Kind(); k == '[' || k == '{' {
+			byteOffset++ // add just the '[' or '{'
+		} else {
+			byteOffset += int64(len(tokOrVal))
+		}
+	}
 	return &SemanticError{action: "unmarshal", GoType: t, Err: toUnexpectedEOF(err),
-		ByteOffset:  d.InputOffset() - int64(len(tokOrVal)),
+		ByteOffset:  byteOffset,
 		JSONPointer: jsontext.Pointer(export.Decoder(d).AppendStackPointer(nil, -1)),
 		JSONKind:    jsontext.Value(tokOrVal).Kind()}
 }
 
-// newUnmarshalErrorAfter wraps err in a SemanticError assuming that d
+// newUnmarshalErrorAfterWithValue wraps err in a SemanticError assuming that d
 // is positioned right after the previous token or value, which caused an error.
 // It also stores a copy of the last JSON value if it is a string or number.
 func newUnmarshalErrorAfterWithValue(d *jsontext.Decoder, t reflect.Type, err error) error {
@@ -299,6 +312,13 @@ func collapseSemanticErrors(err error) error {
 	return err
 }
 
+func wrapErrUnsupported(err error, what string) error {
+	if errors.Is(err, errors.ErrUnsupported) {
+		return errors.New(what + " may not return errors.ErrUnsupported")
+	}
+	return err
+}
+
 // errorModalVerb is a modal verb like "cannot" or "unable to".
 //
 // Once per process, Hyrum-proof the error message by deliberately
@@ -380,9 +400,9 @@ func (e *SemanticError) Error() string {
 	}
 
 	// Special handling for unknown names.
-	if e.Err == ErrUnknownName {
+	if e.Err == ErrUnknownName || e.Err == errAmbiguousName {
 		sb.WriteString(": ")
-		sb.WriteString(ErrUnknownName.Error())
+		sb.WriteString(e.Err.Error())
 		sb.WriteString(" ")
 		sb.WriteString(strconv.Quote(e.JSONPointer.LastToken()))
 		if parent := e.JSONPointer.Parent(); parent != "" {

package/bin/go/src/encoding/json/v2/fields.go

@@ -29,10 +29,12 @@ type isZeroer interface {
 var isZeroerType = reflect.TypeFor[isZeroer]()
 
 type structFields struct {
-	flattened       []structField // listed in depth-first ordering
-	byActualName    map[string]*structField
-	byFoldedName    map[string][]*structField
-	inlinedFallback *structField
+	flattened        []structField // listed in depth-first ordering
+	byActualName     map[string]*structField
+	byFoldedName     map[string][]*structField
+	embeddedFallback *structField
+
+	errUnsupportedFormat *SemanticError
 }
 
 // reindex recomputes index to avoid bounds check during runtime.
@@ -51,8 +53,8 @@ func (sf *structFields) reindex() {
 	for i := range sf.flattened {
 		reindex(&sf.flattened[i])
 	}
-	if sf.inlinedFallback != nil {
-		reindex(sf.inlinedFallback)
+	if sf.embeddedFallback != nil {
+		reindex(sf.embeddedFallback)
 	}
 }
 
@@ -80,25 +82,25 @@ func makeStructFields(root reflect.Type) (fs structFields, serr *SemanticError)
 		return cmp.Or(serr, &SemanticError{GoType: t, Err: fmt.Errorf(f, a...)})
 	}
 
-	// Setup a queue for a breath-first search.
+	// Setup a queue for a breadth-first search.
 	var queueIndex int
 	type queueEntry struct {
 		typ           reflect.Type
 		index         []int
-		visitChildren bool // whether to recursively visit inlined field in this struct
+		visitChildren bool // whether to recursively visit embedded field in this struct
 	}
 	queue := []queueEntry{{root, nil, true}}
 	seen := map[reflect.Type]bool{root: true}
 
 	// Perform a breadth-first search over all reachable fields.
 	// This ensures that len(f.index) will be monotonically increasing.
-	var allFields, inlinedFallbacks []structField
+	var allFields, embeddedFallbacks []structField
 	for queueIndex < len(queue) {
 		qe := queue[queueIndex]
 		queueIndex++
 
 		t := qe.typ
-		inlinedFallbackIndex := -1         // index of last inlined fallback field in current struct
+		embeddedFallbackIndex := -1        // index of last embedded fallback field in current struct
 		namesIndex := make(map[string]int) // index of each field with a given JSON object name in current struct
 		var hasAnyJSONTag bool             // whether any Go struct field has a `json` tag
 		var hasAnyJSONField bool           // whether any JSON serializable fields exist in current struct
@@ -126,80 +128,73 @@ func makeStructFields(root reflect.Type) (fs structFields, serr *SemanticError)
 				if indirectType(f.typ).Kind() != reflect.Struct {
 					serr = orErrorf(serr, t, "embedded Go struct field %s of non-struct type must be explicitly given a JSON name", sf.Name)
 				} else {
-					f.inline = true // implied by use of Go embedding without an explicit name
+					f.embed = true // implied by use of Go embedding without an explicit name
 				}
 			}
-			if f.inline || f.unknown {
-				// Handle an inlined field that serializes to/from
+
+			var handleEmbed, handleField func()
+			handleEmbed = func() {
+				// Handle an embedded field that serializes to/from
 				// zero or more JSON object members.
 
-				switch f.fieldOptions {
-				case fieldOptions{name: f.name, quotedName: f.quotedName, inline: true}:
-				case fieldOptions{name: f.name, quotedName: f.quotedName, unknown: true}:
-				case fieldOptions{name: f.name, quotedName: f.quotedName, inline: true, unknown: true}:
-					serr = orErrorf(serr, t, "Go struct field %s cannot have both `inline` and `unknown` specified", sf.Name)
-					f.inline = false // let `unknown` take precedence
-				default:
-					serr = orErrorf(serr, t, "Go struct field %s cannot have any options other than `inline` or `unknown` specified", sf.Name)
+				if f.fieldOptions != (fieldOptions{name: f.name, quotedName: f.quotedName, embed: true}) {
+					serr = orErrorf(serr, t, "Go struct field %s cannot have any options other than `embed` specified", sf.Name)
 					if f.hasName {
-						continue // invalid inlined field; treat as ignored
-					}
-					f.fieldOptions = fieldOptions{name: f.name, quotedName: f.quotedName, inline: f.inline, unknown: f.unknown}
-					if f.inline && f.unknown {
-						f.inline = false // let `unknown` take precedence
+						handleField()
+						return // invalid embedded field; treat as regular field
 					}
+					f.fieldOptions = fieldOptions{name: f.name, quotedName: f.quotedName, embed: f.embed}
 				}
 
 				// Reject any types with custom serialization otherwise
-				// it becomes impossible to know what sub-fields to inline.
+				// it becomes impossible to know what sub-fields to embed.
 				tf := indirectType(f.typ)
 				if implementsAny(tf, allMethodTypes...) && tf != jsontextValueType {
-					serr = orErrorf(serr, t, "inlined Go struct field %s of type %s must not implement marshal or unmarshal methods", sf.Name, tf)
+					serr = orErrorf(serr, t, "embedded Go struct field %s of type %s must not implement marshal or unmarshal methods", sf.Name, tf)
 				}
 
-				// Handle an inlined field that serializes to/from
+				// Handle an embedded field that serializes to/from
 				// a finite number of JSON object members backed by a Go struct.
 				if tf.Kind() == reflect.Struct {
-					if f.unknown {
-						serr = orErrorf(serr, t, "inlined Go struct field %s of type %s with `unknown` tag must be a Go map of string key or a jsontext.Value", sf.Name, tf)
-						continue // invalid inlined field; treat as ignored
-					}
 					if qe.visitChildren {
 						queue = append(queue, queueEntry{tf, f.index, !seen[tf]})
 					}
 					seen[tf] = true
-					continue
+					return
 				} else if !sf.IsExported() {
-					serr = orErrorf(serr, t, "inlined Go struct field %s is not exported", sf.Name)
-					continue // invalid inlined field; treat as ignored
+					serr = orErrorf(serr, t, "embedded Go struct field %s is not exported", sf.Name)
+					return // invalid embedded field; treat as ignored
 				}
 
-				// Handle an inlined field that serializes to/from any number of
+				// Handle an embedded field that serializes to/from any number of
 				// JSON object members back by a Go map or jsontext.Value.
 				switch {
 				case tf == jsontextValueType:
-					f.fncs = nil // specially handled in arshal_inlined.go
+					f.fncs = nil // specially handled in arshal_embedded.go
 				case tf.Kind() == reflect.Map && tf.Key().Kind() == reflect.String:
 					if implementsAny(tf.Key(), allMethodTypes...) {
-						serr = orErrorf(serr, t, "inlined map field %s of type %s must have a string key that does not implement marshal or unmarshal methods", sf.Name, tf)
-						continue // invalid inlined field; treat as ignored
+						serr = orErrorf(serr, t, "embedded map field %s of type %s must have a string key that does not implement marshal or unmarshal methods", sf.Name, tf)
+						handleField()
+						return // invalid embedded field; treat as regular field
 					}
 					f.fncs = lookupArshaler(tf.Elem())
 				default:
-					serr = orErrorf(serr, t, "inlined Go struct field %s of type %s must be a Go struct, Go map of string key, or jsontext.Value", sf.Name, tf)
-					continue // invalid inlined field; treat as ignored
+					serr = orErrorf(serr, t, "embedded Go struct field %s of type %s must be a Go struct, Go map of string key, or jsontext.Value", sf.Name, tf)
+					handleField()
+					return // invalid embedded field; treat as regular field
 				}
 
-				// Reject multiple inlined fallback fields within the same struct.
-				if inlinedFallbackIndex >= 0 {
-					serr = orErrorf(serr, t, "inlined Go struct fields %s and %s cannot both be a Go map or jsontext.Value", t.Field(inlinedFallbackIndex).Name, sf.Name)
-					// Still append f to inlinedFallbacks as there is still a
-					// check for a dominant inlined fallback before returning.
+				// Reject multiple embedded fallback fields within the same struct.
+				if embeddedFallbackIndex >= 0 {
+					serr = orErrorf(serr, t, "embedded Go struct fields %s and %s cannot both be a Go map or jsontext.Value", t.Field(embeddedFallbackIndex).Name, sf.Name)
+					// Still append f to embeddedFallbacks as there is still a
+					// check for a dominant embedded fallback before returning.
 				}
-				inlinedFallbackIndex = i
+				embeddedFallbackIndex = i
 
-				inlinedFallbacks = append(inlinedFallbacks, f)
-			} else {
+				embeddedFallbacks = append(embeddedFallbacks, f)
+			}
+			handleField = func() {
 				// Handle normal Go struct field that serializes to/from
 				// a single JSON object member.
 
@@ -210,14 +205,14 @@ func makeStructFields(root reflect.Type) (fs structFields, serr *SemanticError)
 					tf := indirectType(f.typ)
 					if !(sf.Anonymous && tf.Kind() == reflect.Struct) {
 						serr = orErrorf(serr, t, "Go struct field %s is not exported", sf.Name)
-						continue
+						return
 					}
 					// Unfortunately, methods on the unexported field
 					// still cannot be called.
 					if implementsAny(tf, allMethodTypes...) ||
 						(f.omitzero && implementsAny(tf, isZeroerType)) {
 						serr = orErrorf(serr, t, "Go struct field %s is not exported for method calls", sf.Name)
-						continue
+						return
 					}
 				}
 
@@ -260,6 +255,15 @@ func makeStructFields(root reflect.Type) (fs structFields, serr *SemanticError)
 				f.id = len(allFields)
 				f.fncs = lookupArshaler(sf.Type)
 				allFields = append(allFields, f)
+				if f.format != "" && fs.errUnsupportedFormat == nil {
+					fs.errUnsupportedFormat = &SemanticError{GoType: t, Err: fmt.Errorf("Go struct field %s has unsupported `format` tag option", sf.Name)}
+				}
+			}
+
+			if f.embed {
+				handleEmbed()
+			} else {
+				handleField()
 			}
 		}
 
@@ -325,6 +329,8 @@ func makeStructFields(root reflect.Type) (fs structFields, serr *SemanticError)
 		flattened:    flattened,
 		byActualName: make(map[string]*structField, len(flattened)),
 		byFoldedName: make(map[string][]*structField, len(flattened)),
+
+		errUnsupportedFormat: fs.errUnsupportedFormat,
 	}
 	for i, f := range fs.flattened {
 		foldedName := string(foldName([]byte(f.name)))
@@ -333,7 +339,7 @@ func makeStructFields(root reflect.Type) (fs structFields, serr *SemanticError)
 	}
 	for foldedName, fields := range fs.byFoldedName {
 		if len(fields) > 1 {
-			// The precedence order for conflicting ignoreCase names
+			// The precedence order for conflicting case-insensitive names
 			// is by breadth-first order, rather than depth-first order.
 			slices.SortFunc(fields, func(x, y *structField) int {
 				return cmp.Compare(x.id, y.id)
@@ -341,8 +347,8 @@ func makeStructFields(root reflect.Type) (fs structFields, serr *SemanticError)
 			fs.byFoldedName[foldedName] = fields
 		}
 	}
-	if n := len(inlinedFallbacks); n == 1 || (n > 1 && len(inlinedFallbacks[0].index) != len(inlinedFallbacks[1].index)) {
-		fs.inlinedFallback = &inlinedFallbacks[0] // dominant inlined fallback field
+	if n := len(embeddedFallbacks); n == 1 || (n > 1 && len(embeddedFallbacks[0].index) != len(embeddedFallbacks[1].index)) {
+		fs.embeddedFallback = &embeddedFallbacks[0] // dominant embedded fallback field
 	}
 	fs.reindex()
 	return fs, serr
@@ -391,8 +397,7 @@ type fieldOptions struct {
 	hasName        bool
 	nameNeedEscape bool
 	casing         int8 // either 0, caseIgnore, or caseStrict
-	inline         bool
-	unknown        bool
+	embed          bool
 	omitzero       bool
 	omitempty      bool
 	string         bool
@@ -404,7 +409,6 @@ type fieldOptions struct {
 // the JSON member name and other features.
 func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool, err error) {
 	tag, hasTag := sf.Tag.Lookup("json")
-	tagOrig := tag
 
 	// Check whether this field is explicitly ignored.
 	if tag == "-" {
@@ -428,10 +432,7 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 		return fieldOptions{}, true, err
 	}
 
-	// Determine the JSON member name for this Go field. A user-specified name
-	// may be provided as either an identifier or a single-quoted string.
-	// The single-quoted string allows arbitrary characters in the name.
-	// See https://go.dev/issue/2718 and https://go.dev/issue/3546.
+	// Determine the JSON member name for this Go field.
 	out.name = sf.Name // always starts with an uppercase character
 	if len(tag) > 0 && !strings.HasPrefix(tag, ",") {
 		// For better compatibility with v1, accept almost any unescaped name.
@@ -445,7 +446,7 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 		// In either case, call consumeTagOption to handle it further.
 		var err2 error
 		if !strings.HasPrefix(tag[n:], ",") && len(name) != len(tag) {
-			name, n, err2 = consumeTagOption(tag)
+			name, n, err2 = consumeTagOption(tag, false)
 			if err2 != nil {
 				err = cmp.Or(err, fmt.Errorf("Go struct field %s has malformed `json` tag: %v", sf.Name, err2))
 			}
@@ -454,22 +455,15 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 			err = cmp.Or(err, fmt.Errorf("Go struct field %s has JSON object name %q with invalid UTF-8", sf.Name, name))
 			name = string([]rune(name)) // replace invalid UTF-8 with utf8.RuneError
 		}
-		if name == "-" && tag[0] == '-' {
-			defer func() { // defer to let other errors take precedence
-				err = cmp.Or(err, fmt.Errorf("Go struct field %s has JSON object name %q; either "+
-					"use `json:\"-\"` to ignore the field or "+
-					"use `json:\"'-'%s` to specify %q as the name", sf.Name, out.name, strings.TrimPrefix(strconv.Quote(tagOrig), `"-`), name))
-			}()
-		}
 		if err2 == nil {
 			out.hasName = true
 			out.name = name
 		}
 		tag = tag[n:]
 	}
-	b, _ := jsonwire.AppendQuote(nil, out.name, &jsonflags.Flags{})
+	b, _ := jsonwire.AppendQuote(nil, []byte(out.name), &jsonflags.Flags{})
 	out.quotedName = string(b)
-	out.nameNeedEscape = jsonwire.NeedEscape(out.name)
+	out.nameNeedEscape = jsonwire.NeedEscape([]byte(out.name))
 
 	// Handle any additional tag options (if any).
 	var wasFormat bool
@@ -487,7 +481,7 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 		}
 
 		// Consume and process the tag option.
-		opt, n, err2 := consumeTagOption(tag)
+		opt, n, err2 := consumeTagOption(tag, false)
 		if err2 != nil {
 			err = cmp.Or(err, fmt.Errorf("Go struct field %s has malformed `json` tag: %v", sf.Name, err2))
 		}
@@ -506,7 +500,7 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 				break
 			}
 			tag = tag[len(":"):]
-			opt, n, err2 := consumeTagOption(tag)
+			opt, n, err2 := consumeTagOption(tag, false)
 			if err2 != nil {
 				err = cmp.Or(err, fmt.Errorf("Go struct field %s has malformed value for `case` tag option: %v", sf.Name, err2))
 				break
@@ -524,10 +518,8 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 			default:
 				err = cmp.Or(err, fmt.Errorf("Go struct field %s has unknown `case:%s` tag value", sf.Name, rawOpt))
 			}
-		case "inline":
-			out.inline = true
-		case "unknown":
-			out.unknown = true
+		case "embed":
+			out.embed = true
 		case "omitzero":
 			out.omitzero = true
 		case "omitempty":
@@ -540,10 +532,13 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 				break
 			}
 			tag = tag[len(":"):]
-			opt, n, err2 := consumeTagOption(tag)
+			opt, n, err2 := consumeTagOption(tag, true)
 			if err2 != nil {
 				err = cmp.Or(err, fmt.Errorf("Go struct field %s has malformed value for `format` tag option: %v", sf.Name, err2))
 				break
+			} else if opt == "" {
+				err = cmp.Or(err, fmt.Errorf("Go struct field %s cannot have empty value for `format` tag option", sf.Name))
+				break
 			}
 			tag = tag[n:]
 			out.format = opt
@@ -553,7 +548,7 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 			// This catches invalid mutants such as "omitEmpty" or "omit_empty".
 			normOpt := strings.ReplaceAll(strings.ToLower(opt), "_", "")
 			switch normOpt {
-			case "case", "inline", "unknown", "omitzero", "omitempty", "string", "format":
+			case "case", "embed", "omitzero", "omitempty", "string", "format":
 				err = cmp.Or(err, fmt.Errorf("Go struct field %s has invalid appearance of `%s` tag option; specify `%s` instead", sf.Name, opt, normOpt))
 			}
 
@@ -578,7 +573,7 @@ func parseFieldOptions(sf reflect.StructField) (out fieldOptions, ignored bool,
 // which is either a Go identifier or a single-quoted string.
 // If the next option is invalid, it returns all of in until the next comma,
 // and reports an error.
-func consumeTagOption(in string) (string, int, error) {
+func consumeTagOption(in string, allowQuoted bool) (string, int, error) {
 	// For legacy compatibility with v1, assume options are comma-separated.
 	i := strings.IndexByte(in, ',')
 	if i < 0 {
@@ -592,6 +587,10 @@ func consumeTagOption(in string) (string, int, error) {
 		return in[:n], n, nil
 	// Option as a single-quoted string.
 	case r == '\'':
+		if !allowQuoted {
+			return in[:i], i, fmt.Errorf("invalid character %q at start of option (expecting Unicode letter)", r)
+		}
+
 		// The grammar is nearly identical to a double-quoted Go string literal,
 		// but uses single quotes as the terminators. The reason for a custom
 		// grammar is because both backtick and double quotes cannot be used
@@ -633,6 +632,9 @@ func consumeTagOption(in string) (string, int, error) {
 	case len(in) == 0:
 		return in[:i], i, io.ErrUnexpectedEOF
 	default:
+		if !allowQuoted {
+			return in[:i], i, fmt.Errorf("invalid character %q at start of option (expecting Unicode letter)", r)
+		}
 		return in[:i], i, fmt.Errorf("invalid character %q at start of option (expecting Unicode letter or single quote)", r)
 	}
 }