JEP 540: Simple JSON API (Now in Incubator)

Programming
Developer Tools
Open Source
Infrastructure

JEP 540 adds a small JSON API to the JDK as an incubator module. It gives Java a standard way to parse JSON text into a typed tree of JSON values, inspect it, and serialize that tree back out. The JEP is explicit about what it is not trying to do: no full data binding to arbitrary Java objects, no attempt to replace Jackson, Gson, or JSON-B, and no broad kitchen-sink feature set. That scope landed with many readers. They saw a genuine hole in the standard library for one-file tools, JShell sessions, lightweight utilities, and code that just needs to read or emit a bit of JSON without dragging in a heavyweight dependency.

The sharpest criticism was aimed at JSON creation, not parsing. The proposed API makes callers wrap native Java strings, numbers, booleans, lists, and maps into explicit JsonValue types, which undercuts the JEP's own promise of low ceremony. Several people pointed out that Java libraries already show easier ways to turn normal collections into JSON, and argued that even a minimal standard API should at least accept obvious scalar and collection types. Others pushed back that this awkwardness is partly intentional. Once the JDK starts auto-converting Java collections and primitives, the pressure to add records, enums, sets, and custom mappings arrives immediately. That is exactly the slippery slope this JEP is trying to avoid. The more durable support in the comments was for the tree model itself. A dedicated JsonValue hierarchy avoids the ambiguity of representing JSON as raw Map<String, Object> and List<Object>, especially around numbers and heterogeneous arrays. People were particularly happy that numbers preserve arbitrary precision until the caller asks for a specific Java type, and that duplicate object keys are rejected instead of silently accepted. That makes the API safer than many "just use native types" shortcuts. There were also complaints about some specific design choices. The biggest one was putting get methods on the base JsonValue type so wrong-type access and missing-key access both turn into the same unchecked exception. Readers saw that as a pattern-matching miss and a debugging footgun. A smaller but recurring concern was that the API only handles strict JSON. That keeps the surface area clean, but makes it a poor fit for human-edited config files where comments and JSONC-style niceties matter. The practical landing point was clear. This looks useful as a standard, maintained JSON tree API for simple programs and for teams that already hand-roll light marshaling around a parser. It does not look like a credible replacement for established production JSON stacks, especially where streaming, data binding, configuration-heavy serialization, or large payload performance matter.

If you run Java teams, treat this as a useful baseline for scripts, tooling, and small services, not as a replacement for Jackson-class libraries. The thing to watch during incubation is whether OpenJDK adds just enough convenience for common JSON creation without drifting into a half-built competing ecosystem.

July 23, 2026
openjdk.org
Discuss on HN

Discussion mood

Cautiously positive about finally getting a built-in JSON API, but skeptical that the current write-side ergonomics match the JEP's simplicity goals. Support comes from wanting a standard no-dependency tree parser in the JDK, while criticism centers on verbose construction, questionable API shape around get and exceptions, and the decision to stay strict JSON only.

Key insights

Why raw Map and List are not enough

Using ordinary Java collections as the in-memory model sounds simpler, but it breaks down on the exact places JSON is slippery. Numbers do not map cleanly to one Java numeric type, arrays can mix types freely, and a sealed JsonValue hierarchy gives Java code something predictable to pattern-match on instead of collapsing everything into List<Object> and Map<String,Object> with ambiguous Number values.

If you build your own JSON layer on the JVM, keep a distinct JSON tree model unless your use case is strictly one-way serialization. Native collections are fine at boundaries, but they are a poor universal representation for arbitrary parsed JSON.

Attribution:

pron #1 #2
dtech #1
prpl #1

This is not a streaming JSON stack

The proposal is built around materializing a full JsonValue tree in memory. That rules out incremental parsing and generation for large payloads, which means it is the wrong primitive for high-throughput services that care about memory pressure or want to start work before the last byte arrives. For ordinary CRUD APIs, several readers said that tradeoff is acceptable because payload sizes are rarely where latency lives.

Do not plan migrations from Jackson streaming or similar APIs to this for hot paths. Use it where payloads are modest and the main benefit is removing a dependency, not where JSON processing is part of your performance budget.

Attribution:

drdexebtjl #1
wewtyflakes #1
gavinray #1

Base-type get methods invite avoidable errors

Putting get("key") and get(index) directly on JsonValue flattens two different failures into one unchecked exception. You cannot tell at a glance whether code accessed the wrong JSON shape or just missed a field, and Java's recent pattern matching features already provide a cleaner way to force type checks before member access.

If this API ships unchanged, wrap access behind your own helpers rather than scattering chained get calls through application code. That will give you clearer errors and a single place to enforce shape validation.

Attribution:

nikeee #1
zbentley #1

Strict JSON keeps the API clean but weakens config use

Refusing comments, trailing commas, and JSONC-style variants keeps the core API narrow and avoids a mess of parser and serializer modes. The cost is that it remains awkward for files humans are expected to edit and preserve. That clashes with examples that position JSON as a replacement for richer configuration formats, because round-tripping strips the context humans rely on.

Use this for machine-generated or machine-consumed JSON. For user-facing configuration, keep using a format with comments and round-trip support, or plan a separate parser path.

Attribution:

esprehn #1
zbentley #1
Groxx #1
Sankozi #1

The omission of data binding is deliberate

Many readers initially expected another object mapper, then noticed the JEP carefully avoids that goal. The target is the gap below JSON-B, Jackson, and Gson: small programs that need parsing, navigation, and basic emission without annotation systems, custom serializers, or a large dependency tree. That narrower ambition explains both the appeal and the frustration around missing convenience features.

Judge this API against ad hoc scripts and tiny utilities, not against full framework serialization. If your code depends on records, annotations, custom naming, or schema evolution, you are still in third-party-library territory.

Attribution:

delusional #1
IanGabes #1
ameliaquining #1
pron #1

Number and duplicate-key handling are unusually sane

The API preserves arbitrary-width JSON numbers until the caller explicitly converts them, which avoids the silent precision loss common in libraries that eagerly coerce everything to double. It also rejects duplicate object keys at parse time instead of guessing which value should win. Those choices make the parser stricter, but much safer for finance, identifiers, and other data where lossy parsing becomes a hidden bug.

If you process externally supplied JSON with large integers or exact decimals, this default behavior is a real advantage. Keep those values as JsonNumber until the business layer decides the target type.

Attribution:

q3k #1 #2
lmz #1

Against the grain

A simple standard parser is enough for many teams

For people who already avoid annotation-driven object mappers, a built-in tree parser plus explicit marshaling code is not a compromise. It is the preferred style. That view cuts against complaints that the JEP is too small to matter. A maintained standard parser removes the need to drag in a full serialization framework just to get basic JSON support.

If your team already writes explicit request and response translation code, this API could shrink dependencies without much pain. Audit where you are using Jackson or Gson only for tree parsing, because those are the easiest wins.

Attribution:

whartung #1
delusional #1

Unchecked parse errors fit real usage

The complaint about unchecked exceptions assumes callers can often recover. In many programs they cannot. If JSON parsing fails, the next step is usually to log, reject the input, or exit. For those cases, checked exceptions mostly add boilerplate without creating better control flow.

If your code treats malformed JSON as a terminal request error anyway, unchecked exceptions may simplify handlers rather than hurt them. Reserve stricter checked-style wrappers for libraries or long-running pipelines that genuinely recover.

Attribution:

crewindream #1

In plain english

CRUD ↩

Create, Read, Update, Delete, the basic operations used in many data-driven applications and APIs.

JDK ↩

Java Development Kit, the standard software kit used to build and run Java programs.

JEP ↩

JDK Enhancement Proposal, the design document process used by OpenJDK to propose and describe new Java platform features.

JShell ↩

Java's interactive command-line REPL, short for Read-Eval-Print Loop, for trying out code snippets quickly.

JSON ↩

JavaScript Object Notation, a common plain-text format for structured data.

JSON-B ↩

Java API for JSON Binding, a standard for converting between Java objects and JSON automatically.

JSONC ↩

JSON with comments, a non-standard variant of JSON that allows comment syntax for human-edited files.

Reference links

Core proposal and standards

JEP 540: Simple JSON API
The actual OpenJDK proposal being discussed, describing the API's goals and non-goals.
JSON.org
Referenced to show that a JSON document root can be any JSON value, not just an object or array.

Existing JVM JSON libraries and alternatives

Jackson
The dominant Java JSON library repeatedly used as the comparison point for tree APIs, data binding, and production features.
Kotlin type-safe builders
Used to illustrate how Kotlin supports more ergonomic JSON-building DSLs than plain Java.
Manifold
Mentioned as a project that can generate type-safe JSON access and inline JSON in Java source.