I present for your consideration the library I made when spiraling
about this problem space a few years ago
https://github.com/bowbahdoe/json
https://javadoc.io/doc/dev.mccue/json/latest/dev.mccue.json/dev/mccue/json/package-summary.html
Notably missing during the design process here were patterns, hence
the JsonDecoder design. I haven't been able to evaluate how patterns
affect that on account of them not being out.
I will more thoroughly peruse the draft of java.util.json at a later
date, but my initial observations/comments:
* I am not sure having JsonValue be distinct from Json has value.
* toUntyped feels a little strange to me - the only type information
presumably lost is the sealed-ness of the hierarchy. The interplay
between that and toNumber is also a little unnerving.
* One notion that I found helpful was that a class could be "json
encodable," meaning there is a method to call to obtain a canonical
json representation.
record Person(String name) implements JsonEncodable {
@Override
public Json toJson() {
return Json.objectBuilder()
.put("namen", name)
.build();
}
}
Which helper methods like Json#of(List<? extends
JsonEncodable>) could make use of. Json itself (JsonValue in your
prototype) could then have a vacuous implementation.
* Terminology wise - I went with reading/writing for the actual
parsing/generation of json and encoding/decoding for the mapping of
those representations to/from specific classes. The merits are not
top of mind, just noting the difference. read/write vs
parse/toString+toDisplayString
* One thing I did was make the helper methods in Json null tolerant
and the ones in the specific subtypes like JsonString not. This was
because from what I saw of usages of javax.json/jakarta.json that
nullability was a footgun and correcting for it required changes to
code structure (breaking up builder chains with if (x != null) checks)
* The functionality you want from JsonNumber could be achieved by
making it just extend Number
(https://github.com/bowbahdoe/json/blob/main/src/main/java/dev/mccue/json/JsonNumber.java)
instead of a bespoke toNumber. You need the extra methods to go to
big decimal and co, but it's just an extension to the behavior of
Number at that point.
* JsonObject and JsonArray could implement Map<String, Json> and
List<Json> respectively. This lowers the need for toUntyped() - since
presumably one of the use cases for that is turning the json tree
into something that more generic map/list traversal code can handle.
It also complicates any lazy loading somewhat.
* Assuming patterns can be placed on interfaces, you might want to
consider something similar to JsonDecoder, but with a pattern instead
of a method that throws an exception.
// Where here fromJson would box up the logic for testing and
extracting from each element in the array.
List<Person> people = array(json, Person::fromJson);
* I don't think there is sufficient cause for anything to be
non-sealed at this point.
* JsonBoolean and JsonNull do not have reasonable alternative
implementations - as far as I can imagine, maybe i'm wrong - so maybe
those can just be final classes?
* If you seal up the whole hierarchy then its pretty trivial to make
it serializable
(https://github.com/bowbahdoe/json/blob/main/src/main/java/dev/mccue/json/serialization/JsonSerializationProxy.java)
On Thu, May 15, 2025 at 11:29 PM Remi Forax <fo...@univ-mlv.fr> wrote:
Hi Paul,
yes, not having a simple JSON API in Java is an issue for beginners.
It's not clear to me why JsonArray (for example) has to be an
interface instead of a record ?
I understand why Json.parse() only works on String and char[] but
the API make it too easy to have many performance issues.
I think you need versions using a Reader and a Path.
Bonus point, if there is a method walk() that also returns a
JsonValue but the List/Map inside JsonArray/JsonObject are
populated lazily.
Minor point: Json.toDisplayString() should takes a second
parameters indicating the number of spaces used for the
indentation (like JSON.stringify in JS).
regards,
Rémi
----- Original Message -----
> From: "Paul Sandoz" <paul.san...@oracle.com>
> To: "core-libs-dev" <core-libs-dev@openjdk.org>
> Sent: Thursday, May 15, 2025 10:30:42 PM
> Subject: Towards a JSON API for the JDK
> Hi,
>
> We would like to share with you our thoughts and plans towards
a JSON API for
> the JDK.
> Please see the document below.
>
> -
>
> We have had the pleasure of using a clone of this API in some
experiments we are
> conducting with
> ONNX and code reflection [1]. Using the API we were able to
quickly write code
> to ingest and convert
> a JSON document representing ONNX operation schema into
instances of records
> modeling the schema
> (see here [2]).
>
> The overall out-of-box experience with such a minimal
"batteries included” API
> has so far been positive.
>
> Thanks,
> Paul.
>
> [1] https://openjdk.org/projects/babylon/
> [2]
>
https://github.com/openjdk/babylon/blob/code-reflection/cr-examples/onnx/opgen/src/main/java/oracle/code/onnx/opgen/OpSchemaParser.java#L87
>
> # Towards a JSON API for the JDK
>
> One of the most common requests for the JDK is an API for
parsing and generating
> JSON. While JSON originated as a text-based serialization
format for JSON
> objects ("JSON" stands for "JavaScript Object Notation"),
because of its simple
> and flexible syntax, it eventually found use outside the
JavaScript ecosystem as
> a general data interchange format, such as framework
configuration files and web
> service requests/response formats.
>
> While the JDK cannot, and should not, provide libraries for
every conceivable
> file format or protocol, the JDK philosophy is one of
"batteries included",
> which is to say we should be able to write basic programs that
use common
> protocols such as HTTP, without having to appeal to third party
libraries.
> The Java ecosystem already has plenty of JSON libraries, so
inclusion in
> the JDK is largely meant to be a convenience, rather than
needing to be the "one
> true" JSON library to meet the needs of all users. Users with
specific needs
> are always free to select one of the existing third-party
libraries.
>
> ## Goals and requirements
>
> Our primary goal is that the library be simple to use for
parsing, traversing,
> and generating conformant JSON documents. Advanced features,
such as data
> binding or path-based traversal should be possible to implement
as layered
> features, but for simplicity are not included in the core API.
We adopt a goal
> that the performance should be "good enough", but where performance
> considerations conflict with simplicity and usability, we will
choose in favor
> of the latter.
>
> ## API design approach
>
> The description of JSON at `https:://json.org
<http://json.org>` describes a JSON document using
> the familiar "railroad diagram":
> 
>
> This diagram describes an algebraic data type (a sum of
products), which we
> model directly with a set of Java interfaces:
>
> ```
> interface JsonValue { }
> interface JsonArray extends JsonValue { List<JsonValue> values(); }
> interface JsonObject extends JsonValue { Map<String, JsonValue>
members(); }
> interface JsonNumber extends JsonValue { Number toNumber(); }
> interface JsonString extends JsonValue { String value(); }
> interface JsonBoolean extends JsonValue { boolean value(); }
> interface JsonNull extends JsonValue { }
> ```
>
> These interfaces have (hidden) companion implementation classes
that admit
> greater flexibility of implementation than modeling them
directly with records
> would permit.
> Further, these interfaces are unsealed. We compromise on the
sealed sum of
> products to enable
> alternative implementations, for example to support alternative
formats that
> encode the same information in a JSON document but in a more
efficient form than
> text.
>
> The API has static methods for parsing strings into a
`JsonValue`, conversion to
> and from purely untyped representations (lists and maps), and
factory methods
> for building JSON documents. We apply composition consistently,
e.g, a
> JsonString has a string, a JsonObject has a map of string to
JsonValue, as
> opposed to extension for structural JSON values.
>
> It turns out that this simple API is almost all we need for
traversal. It gives
> us an immutable representation of a document, and we can use
pattern matching to
> answer the myriad questions that will come up (Does this object
have key X? Does
> it map to a number? Is that number representable as an
integer?) when going
> from an untyped format like JSON to a more strongly typed
domain model.
> Given a simple document like:
>
> ```
> {
> "name": "John”,
> "age": 30
> }
> ```
>
> we can parse and traverse the document as follows:
>
> ```
> JsonValue doc = Json.parse(inputString);
> if (doc instanceof JsonObject o
> && o.members().get("name") instanceof JsonString s
> && s.value() instanceof String name
> && o.members().get("age") instanceof JsonNumber n
> && n.toNumber() instanceof Long l && l instanceof int age) {
> // use "name" and "age"
> }
> ```
>
> Later, when the language acquires the ability to expose
deconstruction patterns
> for arbitrary interfaces (similar to today's record patterns, see
>
https://openjdk.org/projects/amber/design-notes/patterns/towards-member-patterns),
> this will be simplifiable to:
>
> ```
> JsonValue doc = Json.parse(inputString);
> if (doc instanceof JsonObject(var members)
> && members.get("name") instanceof JsonString(String name)
> && members.get("age") instanceof JsonNumber(int age)) {
> // use "name" and "age"
> }
> ```
>
> So, overtime, as more pattern matching features are introduced
we anticipate
> improved use of the API. This is a primary reason why the API
is so minimal.
> Convenience methods we add today, such as a method that
accesses a JSON
> object component as say a JSON string or throws an exception,
will become
> redundant in the future.
>
> ## JSON numbers
>
> The specification of JSON number makes no explicit distinction
between integral
> and decimal numbers, nor specifies limits on the size of those
numbers.
> This is a common source of interoperability issues when
consuming JSON
> documents. Generally users cannot always but often do assume
JSON numbers are
> parsable, without loss of precision, to IEEE double-precision
floating point
> numbers or 32-bit signed integers.
>
> In this respect the API provides three means to operate on the
JSON number,
> giving the user full control:
>
> 1. Underlying string representation can be obtained, if
preserving syntactic
> details such as leading or trailing zeros is important.
> 2. The string representation can be parsed to an instance of
`BigDecimal`, using
> `toBigDecimal` if preserving decimal numbers is important.
> 3. The string representation can be parsed into an instance of
`Long`, `Double`,
> `BigInteger`, or `BigDecimal`, using `toNumber`. The result
of this method
> depends on how the representation can be parsed, possibly
losing precision,
> choosing a suitably convenient numeric type that can then be
pattern
> matched on.
>
> Primitive pattern matching will help as will further pattern
matching features
> enabling the user to partially match.
>
> ## Prototype implementation
>
> The prototype implementation is currently located into the JDK
sandbox
> repository
> under the `json` branch, see
> here
>
https://github.com/openjdk/jdk-sandbox/tree/json/src/java.base/share/classes/java/util/json
> The prototype API javadoc generated from the repository is also
available at
>
https://cr.openjdk.org/~naoto/json/javadoc/api/java.base/java/util/json/package-summary.html
>
> ### Testing and conformance
>
> The prototype implementation passes all conformance test cases
but two,
> available
> on https://github.com/nst/JSONTestSuite. The two exceptions are
the ones which
> the
> prototype specifically prohibits, i.e, duplicated names in JSON
objects
>
(https://cr.openjdk.org/~naoto/json/conformance/results/parsing.html#35).
>
> ### Performance
>
> Our main focus so far has been on the API design and a functional
> implementation.
> Hence, there has been less focus on performance even though we
know there are a
> number of performance enhancements we can make eventually.
> We are reasonably happy with the current performance. The
> implementation performs well when compared to other JSON
implementations
> parsing from string instances and traversing documents.
>
> An example of where we may choose simplicity and usability over
performance
> is the rejection of JSON documents containing objects that in
turn contain
> members
> with duplicate names. That may increase the cost of parsing,
but simplifies the
> user
> experience for the majority of cases since if we reasonably
assume JsonObjects
> are
> map-like, what should the user do with such members, pick one
the last one?
> merge
> the values? or reject?
>
> ## A JSON JEP?
>
> We plan to draft JEP when we are ready. Attentive readers will
observe that
> a JEP already exists, JEP 198: Light-Weight JSON API
> (https://openjdk.org/jeps/198). We will
> either update this JEP, or withdraw it and draft a new one.
