<!--- DO NOT EDIT IN JIRA. EDIT ON ORAHUB. SEE COMMENTS. -->

Summary

Provide convenience methods to help Java developers read and write JSON documents without the overhead of installing an external library. Many useful JSON processing tasks can be accomplished with minimal coding. This is an incubating API.

History

This JEP supersedes JEP 198, Light-Weight JSON API. Circumstances have changed in the intervening years, and this JEP is pursuing a different approach.

Goals

• Provide the ability to process RFC 8259-compliant JSON documents with the lowest possible ceremony.

• Avoid requiring developers to add dependencies in order to consume JSON data.

• Provide operations conforming strictly to RFC 8259, to facilitate machine-to-machine communications, while avoiding JSON variants, multiple parsing configurations, and optional syntactic features.

• Implement a limited set of JSON processing features, focusing on fundamental JSON data types, querying, and extraction, while omitting operations such as streaming, data binding, and serialization. See the Alternatives section for discussion.

• Ensure that the JDK itself is capable of consuming and producing JSON, using only built-in mechanisms.

Non-Goals

• It is not a goal to replace applications' existing usage of external JSON libraries.

Motivation

JSON is ubiquitous in modern computing, and Java developers can choose from a wide range of established JSON libraries: Jackson, Gson, Jakarta JSON Processing and Binding, FastJson2, and many more. These libraries provide not only parsing of JSON documents, but also higher level features such as data binding (converting Java objects to and from JSON with a high degree of customization), event-based streaming, and parsing of extended JSON syntax such as JSON5.

However, developers often need to perform simple tasks that extract and process data from JSON documents. For these tasks, programmers will often use languages such as Python or Go. It should be equally simple to accomplish such tasks in Java. As examples, consider the following tasks, which are accompanied by truncated snippets of related JSON:

• Given a Terraform JSON configuration file, validate the shape of a resource by, e.g., checking it is both "Standard" and "Micro".

  {
      "availability_domain": "Uocm:PHX-AD-1",
      "compartment_id": "ocid1.compartment.oc1..exampleuniqueID",
      "shape": "VM.Standard.E2.1.Micro"
  }

• Given a JSON response from the National Weather Service REST API which provides the weather forecast for a city, extract the current temperature and compute an average over time.

  {
      "startTime": "2025-12-11T06:00:00-05:00",
      "endTime": "2025-12-11T18:00:00-05:00",
      "isDaytime": true,
      "temperature": 35,
      "temperatureUnit": "F",
  }

• Given a JSON response from a Jira REST API, such as the Java Bug System used in OpenJDK, track the number of open enhancements by querying issues.

  {
      "self":"https://bugs.openjdk.org/rest/api/2/issuetype/7",
      "id":"7",
      "name":"Enhancement",
      "subtask":false,
      "avatarId":14707
  }

It would be ideal if developers could tackle simple tasks like these in Java without installing an external library or feeling that another language would make them more productive.

Java has made great strides in handling simple tasks with short no-ceremony programs -- var declarations, convenience methods for collections, compact source files (no more public static void main), running programs from source (java Task.java), and so on. Offering convenience methods to extract data from JSON documents continues this trend.

JSON support in the JDK also paves the way for use of JSON by the JDK, because the JDK cannot have external dependencies. One potential use case is for configuration files. The JDK uses Properties format for several configuration files, such as java.security. A weakness of Properties format is that it has no support for storing structured data. For example, to represent an array in a Properties file, one can use a series of sequentially numbered properties -- a clumsy workaround at best:

    security.provider.1=SUN
    security.provider.2=SunRsaSign
    security.provider.3=SunEC
    ...

With JSON built into the JDK, configuration files can represent arrays quite naturally using JSON arrays.

In addition, the JDK can produce diagnostic output in JSON. For example, the following jcmd command produces a thread dump in JSON format:

  jcmd <pid> Thread.dump_to_file -format=json threaddump.out

A portion of the output file looks like this:

  {
      "name": "workerThread",
      "tid": "28",
      "stack": [
          "java.base\/jdk.internal.vm.Continuation.yield(Continuation.java:388)",
          "java.base\/java.lang.VirtualThread.yieldContinuation(VirtualThread.java:352)",
          "java.base\/java.lang.VirtualThread.park(VirtualThread.java:515)"
      ]
  }

It is extremely useful to be able to process this data using only mechanisms built into the JDK.

Enabling the incubating API

The Convenience API for JSON is an incubator module, disabled by default. The API is offered in the module jdk.incubator.json. To try it out, you must request that the incubator module be resolved, both at compile time and at run time if necessary.

To compile with javac and run with java, run the following:

javac --add-modules jdk.incubator.json MyApplication.java
java --add-modules jdk.incubator.json MyApplication

To use the source code launcher, run the following:

java --add-modules jdk.incubator.json MyApplication.java

To use jshell, run the following:

jshell --add-modules jdk.incubator.json

Description

The jdk.incubator.json.Json class provides a simple parsing experience for in-memory JSON documents that conform to RFC 8259. It returns a hierarchy of jdk.incubator.json.JsonValue instances that expose the names, types, and values of JSON data. Using this class can be as simple as:

  var name = Json.parse(doc).get("name").string();

Json and JsonValue are designed with the following principles:

1. JSON documents are schema-less. JsonValue provides methods to assert expectations about the names and types of JSON data, making it easy to write code to navigate and extract data from documents with known structure. Once written, the code becomes the de facto specification of the schema for those JSON documents and serves as a kind of conformance test for them. It is thus advantageous for the code that asserts document structure to be simple and easy to read.

2. JSON syntax has four primitives (strings, numbers, booleans, and null) and two structures (objects and arrays). The JsonValue interface has six sub-interfaces that correspond directly to these JSON syntactic elements.

3. Developers often interact with JSON in an exploratory manner, writing code not using a specification but instead trying it out against example documents. JsonValue provides methods that fail fast with clear error messages, enabling developers to quickly explore unfamiliar JSON data.

4. JSON documents can change freely over time, or even have differing structure within the same document. Code that extracts data from documents must handle missing values and unexpectedly typed values in a resilient way. JsonValue provides techniques to flexibly handle these situations.

With these two classes, it is possible to accomplish many tasks in just a few lines. As an example, this code parses a JSON document returned from the National Weather Service REST API and streams through its objects, computing the average temperature of New York City over the seven-day forecast period returned in the response.

  import java.net.*;
  import java.net.http.*;
  import jdk.incubator.json.Json;

  var query = "https://api.weather.gov/gridpoints/OKX/33,35/forecast";
  var client = HttpClient.newHttpClient();
  var request = HttpRequest.newBuilder(URI.create(query)).build();
  var response = client.send(request,
  HttpResponse.BodyHandlers.ofString());
  JsonValue json = Json.parse(response.body());
  json.get("properties").get("periods").elements().stream()
      .mapToInt(j -> j.get("temperature").toInt())
      .average()
      .ifPresent(IO::println);

JSON syntactic elements and Java types

A JSON document has six kinds of syntactic elements.

1. A JSON string, delimited with double quotes:

      "Hello"
      "My name is 'Bob'"
      "\u006a\u0061\u0076\u0061"

2. A JSON number, represented in base 10 using decimal digits:

      6  6.0  31.84  2.9E+5

3. A JSON object, delimited by { } and composed of comma-separated members. A member has a name (also called a key) and a value, separated by a colon:

      {
          "address" : "123 Smith Street",
          "value" : 31.84,
          "coordinates" : [ 37, 23, 41, -121, 57, 10 ]
      }

4. A JSON array, delimited by [ ] and composed of comma-separated JSON values:

      [ 1, 2, 3, { "value": "4" }, [ 5, 6 ] ]

5. The JSON boolean literals: true and false

6. The JSON null literal: null

Each of the JSON syntactic elements has a corresponding Java subtype of the JsonValue interface. This interface is sealed so that it is not user extensible. User code can be assured that every JsonValue instance is always one of this fixed set of subtypes.

  sealed interface JsonValue
  permits JsonString, JsonNumber, JsonObject, JsonArray, JsonBoolean, JsonNull {
      ...
  }

  interface JsonString  extends JsonValue { ... }
  interface JsonNumber  extends JsonValue { ... }
  interface JsonObject  extends JsonValue { ... }
  interface JsonArray   extends JsonValue { ... }
  interface JsonBoolean extends JsonValue { ... }
  interface JsonNull    extends JsonValue { ... }

Parsing and navigating JSON documents

Json parses JSON documents as text in the form of either a String or char[]. For example, a JSON document might be a REST API response body read from network, a configuration file read from disk, or some other text payload produced by an application. Parsing a JSON document takes only one method call:

  JsonValue jv = Json.parse(doc);

Parsing is strict: the document must conform to RFC 8259. Syntax extensions such as trailing commas or comments are not supported. In addition, documents must not have objects with duplicate member names. This policy, permitted by the RFC, provides maximum interoperability and predictability, and it reduces concerns about processing malformed or ambiguous JSON documents. See the Alternatives section for a full discussion.

Successful parsing returns an instance of JsonValue. Unsuccessful parsing throws an unchecked JsonParseException. This exception includes a detail message that provides specific information about the exact error and where it occurred in the document.

Most JSON documents have a JSON object or JSON array at the root. These in turn contain other JSON values, often nested objects and arrays, eventually bottoming out at the primitive JSON values: string, number, boolean, or null.

A parsed JSON document results in a hierarchy of JsonValue instances that reflects the same structure as the document. In principle, one could cast the root JsonValue to a JsonArray or JsonObject and perform operations on references of those types. However, many operations can be performed directly on JsonValue without the need for casting.

Once you have obtained the root JsonValue with parse, you can assert your expectation about the presence of a member in the JSON object, or the presence of an element in the JSON array, by calling one of the following access methods. These methods return the member value or array element as a JsonValue.

• get(String) obtains the value of a member. If the JsonValue is not a JsonObject, or if the member is not present, JsonAssertionException is thrown.

• element(int) obtains an array element. If the JsonValue is not a JsonArray, or if the array index is invalid, JsonAssertionException is thrown.

  var json = Json.parse("""
      { "foo": "bar" }
      """);
  JsonValue bar = json.get("foo"); // JsonValue for the string "bar"

  var json = Json.parse("""
      ["foo", "quux"]
      """);
  JsonValue quux = json.element(1); // JsonValue for the string "quux"

A JSON null can appear as the value of any member or array element, e.g.,

  var json = Json.parse("""
      { "foo": null }
      """);

  var json = Json.parse("""
      ["foo", null]
      """);

If a JSON value might or might not be a JSON null, you can process it with the method valueOrNull, which returns an Optional. If the JSON value is a JSON null, the Optional is empty; otherwise, the Optional contains a JsonValue that is not a JsonNull.

In the following example, operations are only performed on the JsonValue for the foo member if its value is not a JsonNull.

  var json = Json.parse("""
      { "foo": null }
      """);
  json.get("foo")
      .valueOrNull()
      .ifPresent(result -> ...);

Converting JSON values to Java values

You can assert your expectation about the type of a JSON value and convert it to the corresponding Java type by calling one of the following conversion methods that appear on the JsonValue interface:

    String string();
    int toInt();
    long toLong();
    double toDouble();
    boolean bool();
    Map<String, JsonValue> members();
    List<JsonValue> elements();

For example, to read a JSON value that you expect to be a JSON string, you convert it to a Java String:

  var json = Json.parse("""
      { "foo": "baz" }
      """);
  String s = json.get("foo").string(); // s is "baz"

To navigate deeply into a JSON document, you can chain access methods and convert to a Java type only at the end:

  var json = ...
  int count = json.get("...").get("...").get("...").toInt();

A conversion method succeeds only if the JSON value is of the asserted JSON type and it can be converted to the desired Java type.

• string() asserts that the JsonValue is a JsonString and returns a Java String that represents the JSON string with all RFC 8259 JSON escape sequences translated to their corresponding characters.

• toInt() asserts that the JsonValue is a JsonNumber, and if its numeric value can be represented exactly as a Java int, returns that int value.

• toLong() asserts that the JsonValue is a JsonNumber, and if its numeric value can be represented exactly as a Java long, returns that long value.

• toDouble() asserts that the JsonValue is a JsonNumber, and if its numeric value can be represented accurately as a Java double, returns it as a double value.

• bool() asserts that the JsonValue is a JsonBoolean and returns a Java boolean value of true or false.

• members() asserts that the JsonValue is a JsonObject and returns an unmodifiable Map<String, JsonValue> that represents the members of this JsonObject. If the JSON object contains no members, an empty Map is returned.

• elements() asserts that the JsonValue is a JsonArray and returns an unmodifiable List<JsonValue>. If the JSON array contains no elements, an empty List is returned.

If any of the type assertions or data conversions fails, a JsonAssertionException is thrown.

Numeric conversions can fail for a variety of reasons other than type assertions. (This is the reason for the to prefix on toInt, toLong, and toDouble.) See Json numerics for a deeper discussion of number handling and conversions.

Here is an example of validating a Terraform configuration by checking the shape of each Terraform instance:

  // A snippet from a larger JSON document
  var config = Json.parse("""
    {
      "oci_core_instance": {
        "web_server": {
          "availability_domain": "Uocm:PHX-AD-1",
          "compartment_id": "ocid1.compartment.oc1..exampleuniqueID1",
          "shape": "VM.Standard.E2.1.Micro"
        },
        "name_server": {
          "availability_domain": "Uocm:PHX-AD-1",
          "compartment_id": "ocid1.compartment.oc1..exampleuniqueID2",
          "shape": "VM.DenseIO.E4.Flex"
        }
      }
    }
    """);

  for (var instance : config.get("oci_core_instance").members().entrySet()) {
      var shape = instance.getValue().get("shape").string();
      if (!shape.contains("Standard")) {
          System.err.println(instance.getKey() + " has invalid shape: " + shape);
      }
  }

Handling evolution of JSON documents

JSON documents can be unpredictable, so your expectations about them might not always hold.

• You might call access methods to assert the presence of member names or array indices that do not exist in the JSON objects and JSON arrays of a given document.

• You might call conversion methods that assert incorrect types for JSON values.

If you make incorrect assertions with access methods or conversion methods, they throw JsonAssertionException. This exception is unchecked, as it is not expected to be handled. This makes scripts and small programs easier to read and write.

  var json = Json.parse("""
      { "foo": "abc" }
      """);
  var theBar = json.get("bar"); // throws JsonAssertionException
  boolean b = json.get("foo").bool(); // throws JsonAssertionException

The exception message describes the route leading from the root of the JSON document to the unexpected JSON value, as well as the position in the JSON document. This is helpful when a chain of access methods navigates deeply into the document. For example, suppose a JSON object used to have this member:

  "person": { ... }

but now has this member:

  "customer": { ... }

The exception thrown by get("person") will report the location of the change:

  jdk.incubator.json.JsonAssertionException: JsonObject member "person" does
  not exist. Path: "...". Location: line 7, position 44.

Handling optional members

If you know that a JSON object might or might not have a member with a given name, you can call the access method getOrAbsent. This returns an Optional containing the value or an empty Optional if the member does not exist. (This contrasts with get, which asserts that the member exists and throws an exception if it does not.)

The getOrAbsent() method will throw JsonAssertionException if it is not called on a JsonObject.

For example, the following response to a REST call would not have the "result" member if the call was unsuccessful; you can defensively handle this scenario with getOrAbsent.

  var json = Json.parse("""
      {
          "jsonrpc": "2.0",
          "id": 1,
          "result": {
              "projectName": "Demo Project",
              "files": ["foo.txt", "bar.txt"]
          }
      }
      """);
  json.getOrAbsent("result")
      .ifPresent(result -> processFiles(result.get("files")));

Handling structural variations

Most JSON documents have uniform structure, but it's possible for some JSON documents to have variable structure. This variation might occur across different documents produced by different software; or it might occur over time as the document generation software evolves; or it might even occur within the same document.

Consider an object that has a member whose value is a string. At some point the underlying data model may change to require multiple strings, and so the single string might be replaced with an array of strings. In this way, differently-structured JSON documents might exist "in the wild" simultaneously, some with a single string and some with an array of strings. Combining objects from these documents may result in a single JSON document containing similar objects with slightly different structures.

As a concrete example, let's look at a JSON document containing a single object whose "payload" member is a string:

  {
      "payload": "foo"
  }

As the software evolves, a requirement might emerge to have the payload be an array of strings:

  {
      "payload": [
          "bar",
          "baz",
          "quux"
      ]
  }

Parsing either document results in a hierarchy of JsonValue instances. However, code that successfully processes the first document:

  var s = Json.parse(doc).get("payload").string();

fails with a JsonAssertionException when processing the second document, because get("payload") returns a JsonArray instead of the expected JsonString.

It's possible to use instanceof to check the type of the value, but in cases such as this, it may be more effective to use a type pattern within a switch statement:

  switch (Json.parse(doc).get("payload")) {
      case JsonArray ja -> processPayload(ja.elements());
      case JsonString js -> processPayload(List.of(js));
      default -> // error handling
  }

Generating JSON documents

It is often necessary to generate plain text from a JSON document. The toString() method returns a compact string representation where all members, elements, and values are emitted on the same line with no whitespace between them.

For example, this code:

  var json = Json.parse("""
      {
          "service" : "web_server",
          "id" : 3
      }
      """);
  IO.println(json.toString());

prints:

  {"service":"web_server","id":3}

Note that the behavior of toString() differs from string(), which throws an exception if the JsonValue is not a JsonString.

The static method Json.toDisplayString() emits a "pretty-printed" version of a JSON document, where members and elements are separated by newlines, and nested structures are indented by the given amount. For example, use the following to print the above structure with two spaces of indentation:

  IO.println(Json.toDisplayString(json, 2));

which prints:

  {
    "service": "web_server",
    "id": 3
  }

The output of both toString() and Json.toDisplayString() are parsable by Json.parse() and will return a JSON structure that is equivalent to the original.

JSON numerics <a id="numerics"></a>

RFC 8259 syntax allows decimal numbers with arbitrary precision and range, and the Java JSON API allows JSON numbers to be processed losslessly. This is unnecessary for most applications, for which more common numeric types are sufficient. RFC 8259 states that good interoperability among JSON implementations can be achieved by using IEEE 754 64-bit binary floating point. This format corresponds to Java's double type.

The toDouble() method converts a numeric JSON value to a Java double. The JSON value must lie within the range that a double can represent. If the value is out of range, an exception is thrown; positive or negative infinity values are never returned. The double value NaN (not-a-number) cannot be represented in JSON and is also never returned. However, negative zero is supported.

If the JSON value has more precision than can be represented in a double, the value is rounded to the closest double value. For example:

  double d1 = Json.parse("3.141592653589793238462643383279").toDouble();
  // d1 is 3.141592653589793, the nearest double value

  double d2 = Json.parse("1.8E309").toDouble();
  // throws JsonAssertionException, out of range

Integral numeric values are quite frequently used, so the toInt() method converts a numeric JSON value to a Java int value. The JSON value must be exactly representable as an int, otherwise an exception is thrown. Numbers that have a syntactic fractional part but that represent integral values are converted successfully. For example:

  int i1 = Json.parse("123.0").toInt();       // succeeds
  int i2 = Json.parse("234.56E2").toInt();    // succeeds
  int i3 = Json.parse("345.6").toInt();       // fails
  int i4 = Json.parse("2147483648").toInt();  // fails

The conversion method toLong() is similar to toInt() except that it returns a Java long value and supports any JSON numeric value that can be represented exactly as a long.

If you need a narrower primitive type than int or double, you can use instanceof primitive matching to perform a safe conversion. (Primitive Types in Patterns is a preview feature.) For example, if you expect a JSON number to be representable with a short, you can do the following:

  var json = Json.parse("""
      {
          "id": 12345,
          "price": 10.99
      }
      """);
  if (json.get("id").toInt() instanceof short s) {
      // use s
  } else {
      // report out-of-range error
  }

As mentioned previously, JSON decimal numbers can have arbitrary precision and range. The toDouble(), toInt(), and toLong() methods by definition process only a subset of JSON numeric values, as they either reject certain inputs or discard information via rounding. To preserve JSON numeric data without loss of information, you can convert essentially any JSON number to a Java BigDecimal by doing the following:

  var bd = new BigDecimal(json.toString());

Alternatives

• Provide a full feature set instead of limited feature set. <a id="features"></a>

The large set of external JSON libraries that already exist (including those mentioned previously) comprises an extremely broad feature set. The task is therefore to select a subset of these features suitable to include in the JDK. The selected features should provide the greatest value relative to their cost.

We've excluded the commonly provided feature of data binding. This is undeniably useful and convenient for many applications. However, it would add a significant API footprint and increase implementation and maintenance costs dramatically. Moreover, there are use cases that don't require data binding; we thus consider this feature not strictly necessary. That Jackson and Jakarta JSON factor data binding into separate modules is an implicit recognition that there are use cases that don't need data binding and that can exclude this dependency.

A streaming API is clearly essential for certain narrow, specialized use cases. However, it requires a fair amount of complexity in applications in order to perform relatively simple data extraction tasks. We've thus excluded this feature on that basis.

This left us with a DOM-like approach where JSON documents are parsed into a tree of JSON-specific objects from which data can be extracted easily. The API is extremely small, and it incurs correspondingly small implementation and maintenance costs. This satisfies the needs of a significant subset of JSON applications from the very simplest to the moderately complex.

It's possible for an application to start off using the JDK JSON API, but eventually for its needs to grow to include features such as data binding. Such an application will need to migrate to an external library that supports that feature. We don't view that as a flaw, and it isn't sufficient justification to include high-cost features such as data binding in the JDK.

• Integrate an external JSON library.

The JDK could integrate an external library as a downstream fork. This would raise some difficult issues over licensing and governance. There would be continual tension over changes flowing in both directions, arising from potentially different criteria regarding specification quality, compatibility, release schedules, and so forth. It seems likely that these costs, plus the additional maintenance burden on the JDK, would outweigh the benefit of integrating an external library.

• Do nothing, as JSON is already handled completely by external libraries.

Since the JDK cannot have external dependencies, this approach would preclude the JDK itself from adding new features that produce and consume JSON.

Any application that adds an external dependency incurs a cost in doing so. There are probably applications that could benefit from using JSON but that do not, because their cost to add a dependency is too high. Such applications would benefit from having JSON support directly in the JDK.

• Allow duplicate member names within objects. <a id="duplicates"></a>

This has been a longstanding issue with JSON. Early specifications were underdetermined with respect to the handling of duplicate member names. This led to a situation where implementations behaved inconsistently with each other or provided application-settable options to select the desired handling policy for duplicate names. Unfortunately, an object with duplicate names is fundamentally ambiguous. When the issue of duplicate names was discussed on the ES-Discuss mailing list in 2013, concern about prohibiting duplicate names was that doing so would invalidate existing documents. Thus, the "should be unique" wording (instead of "must") was retained, and it has been carried over to current specifications. In particular, RFC 8259 says

The names within an object SHOULD be unique. ... An object whose names are all unique is interoperable in the sense that all software implementations receiving that object will agree on the name-value mappings. When the names within an object are not unique, the behavior of software that receives such an object is unpredictable.

The unpredictability arises when the object is processed by a system consisting of multiple, independently-developed JSON implementations. This can lead to hard-to-diagnose errors, security vulnerabilities, decreased interoperability, and general lack of robustness. This phenomenon is discussed in RFC 9413, "Maintaining Robust Protocols".

For these reasons we have chosen a strict approach where duplicate names are unconditionally treated as errors. The strict approach enables Java developers to have higher assurance over the correctness of documents being read. One hopes that the erroneous documents mentioned in the 2013 ES-Discuss conversation have been corrected in the intervening years, and that the software that produced those documents has been fixed.

• Support trailing commas, comments, or other parsing options.

There are several variants of JSON that support comments or trailing commas within arrays and objects. These options are intended to facilitate hand-editing of JSON documents; for example, see JSON5. Such options are not provided, given this project's focus on machine-to-machine communication.

Indeed, this implementation provides no parsing options at all. Adding options enlarges the testing matrix, opens the possibility for interoperability errors, and increases overall development and maintenance burden.

A common workaround is to use a custom preprocessor. For example, comments can be stripped out before parsing, which is arguably one of the main reasons the JSON syntax itself never introduced comments. The following simple snippet shows how to remove single-line comments (lines starting with #) prior to parsing:

String jsonc = Files.readString(Path.of("somefilewithcomments.json"));
String json = jsonc.replaceAll("(?m)^\\s*#.*$", "");
JsonValue jv = Json.parse(json);

Testing

JSON, which appears straightforward in syntax, has a history of varying behavior across different implementations. Having evolved through multiple specifications, differences in behavior have emerged over time in the handling of certain ambiguous and even malicious JSON inputs. As a last mover, the JDK JSON library benefits from being aware of the wide range of edge case inputs that previous implementations have encountered.

The JDK JSON library will be rigorously tested to ensure that only canonical forms of RFC 8259 JSON can be parsed and generated. This is important for ensuring that this library cannot be used to create inconsistencies when interacting with other JSON implementations within a larger system. To accomplish this, our testing approach will not only add comprehensive unit tests to the JDK and JCK, but also leverage the established conformance suite Parsing JSON is a Minefield, which contains numerous edge case inputs.

Risks and Assumptions

• We assume that a minimal set of JSON processing methods with sensible default behavior and acceptable performance offers significant value when developers need to write prototypes and short programs.

• We assume that the input JSON documents can fit in memory (String or char[]). Since we adopt a tree-based model, if we were to allow JSON sources such as a file, issues such as insufficient memory would be possible with large documents. This decision aligns with our minimal design philosophy.

• During the incubation period, we will gather more information about use cases involving generating and transforming JSON documents, in order to evolve these areas of the API. In addition, we will continue to consider forthcoming pattern matching language features that might affect the design of the API.