Repository files navigation

This module hosts an experimental implementation of v2encoding/json.The API is unstable and breaking changes will regularly be made.Do not depend on this in publicly available modules.

Any commits that make breaking API or behavior changes will be markedwith the string "WARNING: " near the top of the commit message.It is your responsibility to inspect the list of commit changeswhen upgrading the module. Not all breaking changes will lead to build failures.

Aproposal to include this module in Go asencoding/json/v2 andencoding/json/jsontext has been started on the Go Github project on 2025-01-30. Please provide your feedback there.At present, this module is available within the Go standard library as a Go experiment.See"A new experimental Go API for JSON" for more details.

• Mostly backwards compatible: If possible, v2 should aim to bemostlycompatible with v1 in terms of both API and default behavior to ease migration.For example, theMarshal andUnmarshal functions are the most widely useddeclarations in the v1 package. It seems sensible for equivalent functionalityin v2 to be named the same and have a mostly compatible signature.Behaviorally, we should aim for 95% to 99% backwards compatibility.We do not aim for 100% compatibility since we want the freedom to breakcertain behaviors that are now considered to have been a mistake.Options exist that can bring the v2 implementation to 100% compatibility,but it will not be the default.

• More flexible: There is along list of feature requests.We should aim to provide the most flexible features that addresses most usages.We do not want to over fit the v2 API to handle every possible use case.Ideally, the features provided should be orthogonal in nature such thatany combination of features results in as few surprising edge cases as possible.

• More performant: JSON serialization is widely used and any bit of extraperformance gains will be greatly appreciated. Some rarely used behaviors of v1may be dropped in favor of better performance. For example,despiteEncoder andDecoder operating on anio.Writer andio.Reader,they do not operate in a truly streaming manner,leading to a loss in performance. The v2 implementation should aim to be trulystreaming by default (see#33714).

• Easy to use (hard to misuse): The v2 API should aim to makethe common case easy and the less common case at least possible.The API should avoid behavior that goes contrary to user expectation,which may result in subtle bugs (see#36225).

• v1 and v2 maintainability: Since the v1 implementation must stay forever,it would be beneficial if v1 could be implemented under the hood with v2,allowing for less maintenance burden in the future. This probably implies thatbehavioral changes in v2 relative to v1 need to be exposed as options.

• Avoid unsafe: Standard library packages generally avoid the use ofpackageunsafe even if it could provide a performance boost.We aim to preserve this property.

While this module aims to possibly be the v2 implementation ofencoding/json,there is no guarantee that this outcome will occur. As with any major changeto the Go standard library, this will eventually go through theGo proposal process.At the present moment, this is still in the design and experimentation phaseand is not ready for a formal proposal.

There are several possible outcomes from this experiment:

1. We determine that a v2encoding/json would not provide sufficient benefitover the existing v1encoding/json package. Thus, we abandon this effort.
2. We propose a v2encoding/json design, but it is rejected in favor of someother design that is considered superior.
3. We propose a v2encoding/json design, but rather than adding an entirelynew v2encoding/json package, we decide to merge its functionality intothe existing v1encoding/json package.
4. We propose a v2encoding/json design and it is accepted, resulting inits addition to the standard library.
5. Some other unforeseen outcome (among the infinite number of possibilities).

This module is primarily developed by@dsnet,@mvdan, and@johanbrandhorstwith feedback provided by@rogpeppe,@ChrisHines, and@rsc.

Discussion about semantics occur semi-regularly, where arecord of past meetings can be found here.

This package aims to provide a clean separation between syntax and semantics.Syntax deals with the structural representation of JSON (as specified inRFC 4627,RFC 7159,RFC 7493,RFC 8259, andRFC 8785).Semantics deals with the meaning of syntactic data as usable application data.

TheEncoder andDecoder types are streaming tokenizers concerned with thepacking or parsing of JSON data. They operate onToken andValue typeswhich represent the common data structures that are representable in JSON.Encoder andDecoder do not aim to provide any interpretation of the data.

Functions likeMarshal,MarshalWrite,MarshalEncode,Unmarshal,UnmarshalRead, andUnmarshalDecode provide semantic meaning by correlatingany arbitrary Go type with some JSON representation of that type (as stored indata types like[]byte,io.Writer,io.Reader,Encoder, orDecoder).

This diagram provides a high-level overview of the v2json andjsontext packages.Purple blocks represent types, while blue blocks represent functions or methods.The arrows and their direction represent the approximate flow of data.The bottom half of the diagram contains functionality that is only concernedwith syntax (implemented by thejsontext package),while the upper half contains functionality that assignssemantic meaning to syntactic data handled by the bottom half(as implemented by the v2json package).

In contrast to v1encoding/json, options are represented as separate typesrather than being setter methods on theEncoder orDecoder types.Some options affects JSON serialization at the syntactic layer,while others affect it at the semantic layer.Some options only affect JSON when decoding,while others affect JSON while encoding.

The v2json package changes the default behavior ofMarshal andUnmarshalrelative to the v1json package to be more sensible.Some of these behavior changes have options and workarounds to opt intobehavior similar to what v1 provided.

This table shows an overview of the changes:

Seediff_test.go for details about every change.

One of the goals of the v2 module is to be more performant than v1,but not at the expense of correctness.In general, v2 is at performance parity with v1 for marshaling,but dramatically faster for unmarshaling.

Seehttps://github.com/go-json-experiment/jsonbench for benchmarkscomparing v2 with v1 and a number of other popular JSON implementations.