JEP 540: Simple JSON API (Now in Incubator)

There's a nice Java library called Clojure with a lightweight syntax if you need to work with data structures and concurrency in Java a lot:

    (println (json/generate-string {:providers ["SUN" "SunRsaSign" "SunEC"]}))

Java lacks the expressiveness to make it much better than this. There's a reason almost all the "replacement Java" languages add something to support DSLs, e.g. type safe builders in Kotlin [1]

The kotlin stdlib-adjacent json lib does it like this

   buildJsonObject {
     putJsonArray("providers") {
        add("SUN")
        add("SunRsaSign")
        add("SunEC")
     }
   }

[1] https://kotlinlang.org/docs/type-safe-builders.html

    Json.writeTo(System.out)
        .object()
            .array("providers")
                .element("SUN")
                .element("SunRsaSign")
                .element("SunEC")
            .end()
        .end();

    Json.writeTo(System.out)
        .object()
            .array("providers").withElements("SUN", "SunRsaSign", "SunEC")
        .end();

I'm not involved with the design of this API, but it seems to me that the issue on the JSON generation side (where you're complaining about ceremony) is feature creep. Creating the API you want on top of the proposed one is trivial (even in user code), but then where do you stop? If you have that conversion, it seems reasonable to also support, say, sets and records; maybe even enums.

Indeed, Java JSON libraries typically offer all these conveniences and more, but this package is not intended to replace them - as the JEP clearly states ("It is not a goal to create an API that supplants established external JSON libraries"). It is intended to support only simple JSON tasks without requiring a library. For that goal, feature creep is particularly problematic: the more you offer (which reduces the need for the popular libraries in more situations) the greater the pressure to add even more.

Often, it's best to start with the minimum required, and then, as the API gets used in the field, see what the most valuable convenience methods to add on top.

FWIW, in Kotlin's native JSON library, the API is almost identical.

    val json = JsonObject(
        mapOf(
            "providers" to JsonArray(
                listOf(
                    JsonPrimitive("SUN"),
                )
            )
        )
    )

    println(json)

Of course nobody generally does it this way, usually you take a List/Map and directly serialize that with a helper

    val data = mapOf("providers" to listOf("SUN", "SunRsaSign", "SunEC"))

    val kotlinxJSON = Json.encodeToJsonElement(data)
    val jacksonJSON = ObjectMapper().writeValueAsString(data)

I really wish the JDK devs would start using constructors again. I understand why factory methods exist but everything these days is of/from/newInstance/something else. Dart/Scala/Kotlin have all really solved this with language features and construction is uniform. For example in Dart they have factory constructors: https://dart.dev/language/constructors#factory-constructors

    sealed Interface A {
        class B: A
        class C: A
        companion object {
            operator fun invoke(s: String) = when (s) {
                "B" -> B()
                "C" -> C()
            }
        }
    }

    val a = A("B")

Currently, JsonObject.of has this signature:

    static JsonObject of(Map<String, ? extends JsonValue> map);

java.lang.String and other types don't extend JsonValue, and java lacks any trait-like way to add this functionality to existing types, so you would have to change the signature to this:

    static JsonObject of(Map<String, ? extends Object> map);

Now you can pass any Object in, but the typechecker can't ensure that it is convertible to json anymore. I.e. it will have to check at runtime that it's either JsonValue or another type that is has a known conversion for (Integer, Double, String, List, Map, etc.). The jackson ObjectMapper e.g. has a lot of configuration available to tell it how to do these conversions on arbitrary types, and I think they want to eliminate that kind of ceremony.

It does seem like any serious application is going to use another library, and this will be useful for very simple json usage or single-file hello-world type programs (e.g. to go along with Implicitly Defined Classes and the Flexible Launch Protocol).

You almost can, with Jackson:

  jshell> new ObjectMapper().valueToTree(Map.of("providers", List.of("SUN", "SunRsaSign", "SunEC")));
  $4 ==> {"providers":["SUN","SunRsaSign","SunEC"]}

(or was that the joke?)

Yes, what's the point of JsonObject at all? Why JsonString when there is String? Why JsonArray when there is List? JDK only needs a function to convert from JSON format to the normal data structures it already has and back.

> Surely there could be some way of creating a JsonArray of native Java Strings, Booleans, Doubles, and Integers without requiring clients to explicitly convert each value into a JsonValue

I think so to, and it surprises me that they write

“A key goal driving the recent evolution of the Java Platform has been to enable simple tasks to be accomplished more easily and with less ceremony. Features serving this goal include convenience factory methods for collections […]”

and don’t, from that, decide that this API needs such factory methods.

The API also doesn’t make JsonObject or JsonArray collections, requiring one to use ‘asMap’ or ‘asArray’ before iterating over them.

What benefit does that carry? That one can implement those interfaces as records?

You can inline native type-safe JSON directly in Java with the manifold project.

    /*[Dude.json/] {
      "Name": "Scott",
      "Age": 100,
      "Address": {
        "Street": "345 Syracuse Way",
        "City": "Atlantis"
      }
    }
    */

    Dude dude = Dude.fromSource();
            
    out.println(dude.getName());
    out.println(dude.getAge());
    out.println(dude.getAddress().getCity());

https://github.com/manifold-systems/manifold

Yeah, I agree.

The clean way of doing this is to build a json marshaling mechanism for the type system as it already exists. This is doable in Java, and some json libraries (e.g. gson) are already capable of this.

I must admit I don't fully understand the motivation behind this JEP. Like when would I ever reach for this?

A stated goal of the API is to have "low ceremony" when reading arbitrary JSON files. I agree the JSON creation API looks pretty clunky, but the parsing API looks fairly simple.

I was going to make fun of Java before even opening the page with something to the tune of `AbstractBeanJsonSimpleFactory` but looks like reality beat me to it, heh.

minimal-json scratches this itch really well for me. Dead simple API. Unfortunately not maintained anymore, but I'm still using it, even for new projects, because it just works so well.

Even Rust syntax is so much clean and better than this...

But isn't JSON de facto conceptually a glorified Map<String,Object> ?

That is indeed baffling and regrettable. Perhaps they believe that users will just hard-cast what .parse() returns to JsonObject/JsonArray/whatever, and that the resulting ClassCastException will be uglier and harder to debug than whatever errors are currently produced by calling .get() on something other than JsonObject?

The alternative has bad ergonomics, chained `.get`s which are the most common operation become:

   json.asObject().get("prop1").asObject().get("prop2")...

Not sure why they didn't include the BigDecimal conversion directly on the JsonNumber object instead of going through the String representation.

Duplicate keys are a parse exception.

> Additionally, documents must not have objects with duplicate member names.

My understanding from reading this is the complete opposite. This library is explicitly not supporting the features that web servers need to be performant and handle production traffic, like streaming.

A web server using this could only start parsing when it receives the last byte, and could only start responding when it’s done serializing, all while holding non-lazy trees of JsonValue objects in memory.

Yeah - json is fine as a readable mechanical exchange format, but without comments it's essentially unusable for anything humans need to touch :/

I'm somewhat boggled that json5 hasn't grown to be more of a thing.

its crazy its taken Java so long to realise this

If I'm guessing correctly what you mean by "serialization", the JEP refers to it as "data binding" and includes a section on why it's not going to be part of this library.

Eh, I think it's a good tradeoff. If it losslessly supported deserializing comments/JSONC, or trailing commas, or JSON-lines, or whatever, the serialization APIs would get more complicated. Every time you serialize you'd have to decide which of several formats you were producing. Automatic round-trippability would still be impossible in that world, since e.g. "deserialize JSON-ish, set one key=value, reserialize" would then risk producing a not-strictly-JSON object that broke whatever it was sent to, so then you'd need a whole bunch of different serialization configs/settings, which would confuse newbies (either they produce something that's subtly different from what they need, or they accidentally strip out information).

As similar as all the almost-JSON formats are, I still think it's best to keep APIs single-purpose: one for JSON, one for JSON-lines, one for JSONC, and so on. It's a larger code surface, but a less potentially surprising one.

I’m very happy that these exes are unchecked (incl jackson3).

If parsing fails - how often can you do anything else than just abort and log/show an error..

Checked exceptions are nice in theory, but it is very context dependent if checked’ness is useful, I would prefer that libraries do not expose them.

You forgot Javascript :)

Even a relatively barebones systems language like Zig has std.json. Odin has it too.