encoding/json/v2: working group meeting minutes

[aclements]

This issue is a record of the meeting minutes from the json/v2 working group. Please post any discussion in the json/v2 issue. See also the working group project board.

The goal of the json/v2 working group is to drive the json/v2 proposal to a decision, including addressing feedback from the community and the GOEXPERIMENT version of the package, implementing and experimenting with changes, and representing the proposal to the main proposal review committee.

I started the json/v2 working group as an experiment in a better decision-making process for large API proposals. The existing proposal review process has historically not been well-suited to such proposals and tends to leave them languishing, especially when there’s a lack of direct representation on the proposal review committee. The working group aims to address the diffusion of responsibility that can leave large proposals in limbo.

The working group is composed of both members of the Go team at Google and external contributors who have been involved in the json/v2 proposal. I intentionally kept it small to avoid a “committee effect”, and only plan to play a facilitator role myself. So this is also an experiment in more deeply involving trusted members of the Go contributor community in Go’s technical decision making.

[aclements]

Nov 20, 2025

Attendees: @aclements @ChrisHines @dsnet @neild @prattmic

Notes

• How do we move this forward to a formal recommendation the proposal review committee can ingest?
  • @ChrisHines: There’s a collection of sub-issues. Some need to be resolved before finalizing the proposal, and some don’t.
  • @dsnet: Want to make sure the v1 reimplementation is of sufficient fidelity so there are no regressions. There are a few minor behavior changes. Finalized API review. May cut out some features for the initial release. Variadic options are unusual in std, but have proven useful compared to options structs.
  • @ChrisHines: I found a gap with float32 tokens that you can do at the high level, but not at the low level (jsontext).
  • @dsnet: There are several design issues to resolve. Some block it and some don’t. Can we add a “blocks-json-v2” tag?
• @ChrisHines: Related to type-safe struct tags.
  • @aclements: I don’t think this group needs to decide on the type-safe struct tags, but json/v2 could be valuable motivation for that.
  • @ChrisHines: json/v2 needs to support the untyped tags for backwards compatibility.
  • @ChrisHines: We added errors.As before there were generics, and then a new version with generics. People benefited from errors.As without generics, and its existence now isn’t a problem. That suggests it's not a blocker for json/v2.
  • @neild: If we do type-safe struct tags, we would do it for json/v2. It would be a great combined “this is what we’re doing for json” announcement. Do we hold up json/v2 by a release for struct tags? Or have one release of json/v2 with string tags?
  • @ChrisHines: The strings introduce lots of levels of escaping.
  • @ChrisHines and @dsnet: Language proposals take a long time. Wouldn’t want to delay json/v2 by several releases for that.
• Posting discussion minutes
  • On the proposal issue or its own issue?
  • If we do a separate issue just for the minutes, it’s much easier for someone to subscribe to or read just the minutes. Anyone who wants to comment can easily still do so on the main proposal.
  • Describe the working group and process at the top.
• Logistics for getting through sub-issues
  • Agree before meeting each week which ones we’re going to focus on for that meeting.
  • @aclements: A GitHub project would be useful for that.

Action items

• @dsnet: Create a jsonv2-blocker tag
• Collect the set of all json/v2 issues on the tracker as sub-issues
• @aclements: Start a minutes issue
• Triage sub-issues for which are blockers
• @aclements: Push forward and get clarity on typed struct tags proposal.
• @dsnet: File a summary of what json/v2 would look like with typed struct tags.
• Go through discussion and file new issues for anything that needs to get tracked
• Collectively perform another design pass

[aclements]

Dec 4, 2025

Attendees: @aclements @ChrisHines @dsnet @neild @prattmic

Notes

• Went over GitHub project structure
  • Review “Under review”
  • Needs triage → Needs review or post-proposal (or closed)
  • Needs review → Under review
• Deleted jsonv2-blocker tag, since it’s now captured in the project
• Goal for today: move a few into “Under review” so we can start working async
• Go through project
  • Needs triage
    • proposal: encoding/json/jsontext: add constants for each Kind proposal: encoding/json/jsontext: add constants for each Kind #71756
      • Top proposal can obviously be done later, but there’s a variation where we only export the named kinds.
      • Adding them later guarantees inconsistent usage.
      • On the call side, it’s definitely more readable to use the identifiers. E.g., ‘0’ is unclear that it stands for all numbers.
      • Named Kind consts are better for code completion. And you can grep for these ids, or use cross-references.
      • The ‘n’, ‘f’, etc values are literally just the first character in almost all cases, and the parser takes advantage of that today.
      • Let’s just add the diff at the top
    • proposal: encoding/json/v2: MarshallJSONTo: Skip fields when marshalling to json proposal: encoding/json/v2: MarshallJSONTo: Skip fields when marshalling to json #74322
      • Related to proposal: encoding/json/v2: permit SkipFunc for MarshalTo/UnmarshalFrom methods #74324
    • proposal: encoding/json/v2: custom unmarshalers for underlying types should work with named types proposal: encoding/json/v2: custom unmarshalers for underlying types should work with named types #75177
      • Not clear if this is well-defined. int and NamedInt are both just names for the same underlying type. One isn’t “more specific” than the other.
      • There is an existing solution, which is to register an any handler. Handlers get called in order of registration.
    • proposal: encoding/json/jsontext: add Kind.IsValid proposal: encoding/json/jsontext: add Kind.IsValid #75431
      • discussed
    • encoding/json/v2: unable to make omitempty work with pointer or Optional type with goexperiment.jsonv2 encoding/json/v2: unable to make omitempty work with pointer or Optional type with goexperiment.jsonv2 #75623
      • commented
    • encoding/json/v2: proposal: require known fields to exist when unmarshaling encoding/json/v2: proposal: require known fields to exist when unmarshaling #76458
      • moved to post-proposal
    • proposal: encoding/json/v2: escape hatch to omit & override field proposal: encoding/json/v2: escape hatch to omit & override field #75827
      • moved to post-proposal

[aclements]

Dec 11, 2025

Attendees: @aclements @ChrisHines @dsnet @neild

Notes

• Review AIs
  • No updates.
• Go through project
• Review “Under review”
  • proposal: encoding/json/v2: decide on default representation for time.Duration #71631
    • JavaScript TC39 is working on standardizing durations, and there’s a general sense that whatever JavaScript does defines what the Internet does. The proposal is far enough along that it’s more a matter of “when” than “if”.
    • In a perfect world we would just align with TC39. However, TC39 Temporal.Duration can represent inexact units like “years”. If you try to perform math on two durations, it will throw RangeError, implying that Duration doesn’t have a native accurate value for nominal units.
    • Java’s Duration also uses TC39 and is compatible with TC39’s syntax. When parsing a string into a duration, it will reject inexact units. (It does accept “days”, which it treats as 24 hours.)
    • Marshalling has to pick a format (but all time.Durations are representable in TC39). Unmarshalling can support multiple (unambiguous) formats, so we could say “if it starts with PT, parse it as ISO 8601/TC39; if it looks like a number, parse it as fractional seconds.”
    • encoding/json today marshals as a nanosecond number. That’s a big footgun that we regret.
    • Keeping it as a number but changing the units would be a dangerous change.
    • The options seem to be
      • 1) We could require a format tag and not have a default. It would be an error to not tag a time.Duration.
      • 2) We could marshal as ISO 8601/TC39, and unmarshal a number as nanoseconds and a “PT” string as ISO 8601/TC39.
    • Changing the default representation is hazardous because someone could upgrade to json/v2 and suddenly something else in the JSON pipeline breaks. Suggests fail-fast. ISO 8601 would make sense if we didn’t have any history here, but we do.
    • If we make it an error now, we could empirically determine if there is a “right” default in the future.
    • ⇒ Marshall will require a format tag.
    • If unmarshall sniffs the format, then it would be easy for a service to unintentionally support duration formats it didn’t intend.
    • If we require the format for marshalling, there’s no overhead to requiring it for unmarshall.
    • We could provide a fuzzy unmarshaller, which people could call.
    • We could support a list of format options. Marshall would always use the first format, but unmarshall would go through the list. That’s something we could add later.
    • Fuzzy unmarshalling is an opening for request smuggling.
    • ⇒ Unmarshall will require a format tag.
    • @neild to summarize discussion
• Needs triage → Needs review or post-proposal (or closed)
• Needs review → Under review
  • encoding/json/v2: investigate replacing jsontext.Internal symbol #73435
    • Long ago, in a galaxy far, far away, this was all in one package. Then we noticed that all of the documentation distinguished between high-level and low-level things. And thus was born jsontext.
    • Internal exists because json/v2 can do some things more efficiently by reaching into jsontext.
    • We could fix this with a bunch of type aliases to internal things. That messes up documentation viewing today, but that’s something we’d like to fix anyway.
      • You want to see the documentation, the definition of the type, and any methods.
      • Closed proposal: proposal: go/doc: inline type alias documentation #44905. But we keep hitting this, so @aclements thinks it’s worth revisiting
    • The existence of Internal is a bit of a smell. Shouldn’t json/v2 be able to use the public API of jsontext?
    • @dsnet will explore what it would look like to put this into an internal package and use type aliases. If that looks good, we’ll revisit representing this nicely in pkgsite.
  • proposal: encoding/json/v2: encode time with format:unix as integer instead of float #73486
    • Radical idea: format can already take a time package format string. What if we expanded those to support formatting UNIX seconds?
    • Float vs int seconds? Float carries strictly more information.
    • Does it have to be format:? Could it be something else that takes a printf formatter and applies it to UNIX time?
    • ⇒ format:unix means floating point. The most obvious name should be the highest precision. We can add something in the future for int and other formats of UNIX time.
    • @neild will update.