JEP 540 Proposed to Target JDK 28 with a Simple JSON API

A N M Bazlur Rahman · rss · 2026-08-17 source ↗ Reader 🖥️

Changeability & Optionality Modularity & Coupling Software Design Fundamentals Worse Is Better

JEP 540 proposes a deliberately narrow, strict, immutable, dependency-free JSON API for the JDK standard library — trading the completeness of libraries like Jackson and Gson for interface simplicity — and ships it as an incubating module so the community can pressure-test its navigation, exception, conversion and construction ergonomics before the design is finalized.

theoretical · expository — News reporting on a JDK Enhancement Proposal's design and status. It is mostly explanatory (what the API does, how it is shaped) rather than argumentative, but it carries an implicit design-philosophy argument: a JDK-provided JSON API should trade completeness for narrow scope, strictness and zero dependency, with incubation as the mechanism for testing that bet.

Structure

Part	Role
Status and scope framing: JEP 540 moves to Proposed to Target for JDK 28; deliberately narrower than Jackson/Gson (no data binding, no streaming, no lenient parsing).	context
Core API walkthrough: Json/JsonValue sealed hierarchy, direct access methods, parse() example.	evidence for the 'simple navigation' half of the design bet
Construction walkthrough: factory methods (JsonObject.of, JsonString.of, etc.) and the added ceremony this requires.	evidence + acknowledged weakness, held up as a likely area of incubation feedback
Strictness discussion: no lenient mode, duplicate-key rejection, its RFC 8259 conformance and interoperability risk.	evidence for the 'strict semantics' half of the design bet, with a flagged tradeoff
Pattern-matching and conversion methods (asInt/asLong/asDouble/tryGet/tryValue).	evidence of ergonomic design choices building on the sealed hierarchy
Historical contrast with JEP 198 (2014, never delivered, broader scope).	context establishing this as a second, narrower attempt at the same goal
Incubation mechanics: --add-modules requirement, what incubation is meant to test.	conclusion / next steps

Key terms

Incubator module
A JDK API distribution status (here jdk.incubator.json) that ships the feature for real use and feedback while explicitly reserving the right to change it incompatibly or remove it before it becomes a permanent, guaranteed part of the platform.
Strictness
The parser's refusal to accept any deviation from RFC 8259 — no comments, no trailing commas, no other syntax extensions, and rejection of duplicate object-member names — with no lenient/permissive mode offered as an alternative.
tryGet vs. tryValue
Two distinct optional-access methods that let the API distinguish 'this member is absent' from 'this member is present and explicitly JSON null': tryGet() returns an Optional containing JsonNull for an explicit null, while tryValue() returns an empty Optional for JsonNull.

Propositions

explicitJEP 540 deliberately narrows its scope below full-featured libraries like Jackson and Gson, excluding data binding, streaming, a permissive parsing mode, and syntax extensions.conf: high
extendsWorse is better: JSON versus XML · p17 — JEP 540 instantiates the worse-is-better thesis inside the JDK's own standard library: it deliberately ships a less complete JSON API than Jackson/Gson, betting that narrow interface simplicity (plus zero external dependency) beats completeness for the common case.
explicitDeclaring access methods directly on the sealed JsonValue interface lets callers traverse JSON objects and arrays without repeatedly casting intermediate values.conf: high
explicitConstructing JSON values through explicit factory methods adds ceremony, because ordinary Java strings, numbers, and booleans must be wrapped before being placed in an object or array.conf: high
explicitThe parser's strict rejection of duplicate object-member names is a real interoperability risk, since RFC 8259 only recommends uniqueness rather than requiring it, and other parsers handle duplicates inconsistently.conf: high
supportsWorse is better: JSON versus XML · p10 — JEP 540's own authoritative, spec-first parser confirms JSON's lack of comment/lenient-syntax support is a real, unresolved weakness for configuration-style use — even the JDK's own new implementation doesn't add a permissive mode to compensate.
explicitShipping as an incubating module is meant to let the OpenJDK community evaluate and potentially change the navigation model, exception semantics, numeric conversions, and construction ergonomics before the API is finalized.conf: high
implicitA dependency-free, JDK-provided JSON API is worth building even though mature third-party libraries already fully solve JSON parsing and generation, because the common tasks it targets (reading config, inspecting a REST response, generating a small payload) do not need those libraries' full feature set.conf: medium

Arguments

A minimal, strict, immutable, dependency-free JSON API belongs in the JDK standard library, even alongside mature third-party alternatives.

Explicit premises:

Common JSON tasks (config reading, REST response inspection, small payload generation) don't require data binding or streaming.
Direct access methods on the sealed JsonValue hierarchy avoid repeated casting during traversal.
Incubator-module status lets the design change or be withdrawn based on feedback, lowering the cost of getting details wrong up front.

Implicit premises:

The value of eliminating an external dependency for simple JSON work outweighs the cost of building and maintaining a second, narrower JSON implementation alongside already-popular libraries.
Strict RFC 8259 conformance (no comments, no trailing commas, no duplicate keys) is worth its ergonomic and interoperability cost, because a standard-library API should model the specification rather than the permissive JSON most real-world documents actually use.

Inferences:

If JEP 540 reaches Target and ships, some application code doing simple JSON work could drop Jackson or Gson as a compile-time dependency, shrinking dependency trees for that use case.
Because the parser rejects duplicate keys and offers no lenient mode, migrating existing code from a permissive third-party parser to this API could newly fail on real-world JSON documents that were previously accepted.

Narratives

A short code example parsing a weather-API-style response body and navigating four levels deep (properties → periods → [0] → temperature) with chained get() calls ending in asInt().
→ Shows, rather than argues, that direct-on-JsonValue access methods make common navigation terse and cast-free — supporting proposition 2.
A code example building a JsonObject via JsonObject.of(Map.of(...)) with each value explicitly wrapped in JsonString.of/JsonNumber.of/JsonBoolean.of.
→ Shows the construction-side ceremony the article names as a likely feedback target — supporting proposition 3, in tension with the ease shown by the parsing example.

Questions addressed

✅ Should the JDK ship a built-in JSON API when mature third-party libraries (Jackson, Gson) already exist?
Yes, for a deliberately narrow slice of common tasks — not as a general replacement for those libraries.
✅ How should a minimal JSON API expose typed access without excessive casting?
A sealed JsonValue hierarchy with access/conversion methods declared directly on the interface, plus pattern-matching switches over the sealed subinterfaces.
✅ How should the API distinguish a missing object member from one explicitly set to JSON null?
tryGet() returns Optional<JsonValue> containing JsonNull for an explicit null; tryValue() returns an empty Optional for JsonNull, and both are empty when the member is absent versus present respectively.
⭕ Is rejecting duplicate JSON object-member names the right strictness call given RFC 8259 only recommends (not requires) uniqueness?
The article names it as an interoperability risk but does not resolve whether the tradeoff is correct.
⭕ Why did the JDK's earlier attempt at a JSON API (JEP 198, 2014) never get delivered, and does JEP 540 avoid whatever caused that?
The article mentions JEP 198 existed and was broader in scope, but does not explain why it stalled or whether JEP 540's narrower design specifically addresses that failure.

Gaps

incompleteConstruction ergonomics (wrapping every Java primitive in a factory call before it can enter a JSON object or array) is flagged as 'one likely area for feedback,' but the article never explores what alternative designs — builder APIs, varargs helpers, or implicit boxing conveniences used by other JSON libraries — might resolve it, or why the JEP authors chose explicit factories over those alternatives in the first place.
Read next: The JEP 540 specification's own 'Alternatives' section, and any core-libs-dev / amber-dev mailing-list discussion from the incubation period proposing alternative construction APIs.
incompleteThe article notes JEP 198 (2014) was a broader, never-delivered predecessor but does not explain why it stalled, leaving the reader unable to judge whether JEP 540's narrower scope specifically fixes the reason the earlier attempt failed, or whether it risks repeating that failure for different reasons.
Read next: JEP 198 itself and any OpenJDK retrospective or mailing-list history on why a JDK-native JSON API was proposed in 2014 and never delivered.
incompleteDuplicate-member-name rejection is framed purely as a general interoperability inconvenience, but the article never connects it to the security literature on parser-differential attacks (where two parsers in a pipeline disagree on which duplicate key wins, enabling validation bypass or smuggling) — an angle where a strict, spec-first standard-library parser is unusually well positioned, but the piece doesn't make that case.
Read next: Security research and write-ups on JSON/HTTP parser-differential and duplicate-key smuggling vulnerabilities.