java.util.json Backport for JDK 21+

A backport of the experimental java.util.json API from the OpenJDK jdk-sandbox “json” branch, plus an incubating JSON Type Definition (JTD) validator (RFC 8927).

Early access / unstable: APIs and behaviour may change as upstream evolves.
Maven Central GitHub Design Paper (PDF) OpenJDK jdk-sandbox

Quick Start

Maven

<dependency>
    <groupId>io.github.simbo1905.json</groupId>
    <artifactId>java.util.json</artifactId>
    <version>2026.01.26</version>
</dependency>

Parse and access

import jdk.sandbox.java.util.json.*;

JsonObject obj = (JsonObject) Json.parse("{\"name\":\"Alice\",\"age\":30}");

String name = obj.get("name").string();
long age = obj.get("age").toLong();

What’s Included

  • Immutable JSON values: JsonObject, JsonArray, JsonString, JsonNumber, JsonBoolean, JsonNull
  • Typed factories: build JSON with JsonObject.of, JsonArray.of, JsonString.of, JsonNumber.of, JsonBoolean.of
  • Type-safe accessors: obj.get("x").string(), value.toLong(), value.toDouble(), value.bool()
  • JTD validator (RFC 8927): module json-java21-jtd for real-world JSON-heavy logic

Record Mapping (explicit, typed)

import jdk.sandbox.java.util.json.*;
import java.util.*;

record User(String name, String email, boolean active) {}
record Team(String teamName, List<User> members) {}

Team team = new Team("Engineering", List.of(
    new User("Alice", "alice@example.com", true),
    new User("Bob", "bob@example.com", false)
));

JsonValue teamJson = JsonObject.of(Map.of(
    "teamName", JsonString.of(team.teamName()),
    "members", JsonArray.of(team.members().stream()
        .map(u -> JsonObject.of(Map.of(
            "name", JsonString.of(u.name()),
            "email", JsonString.of(u.email()),
            "active", JsonBoolean.of(u.active())
        )))
        .toList())
));

Run the README Examples

mvn package
java -cp ./json-java21/target/java.util.json-*.jar:./json-java21/target/test-classes \
  jdk.sandbox.java.util.json.examples.ReadmeExamples

Replace * with the actual version number from the JAR filename.

JSON Test Suite Compatibility

# Run human-readable report
mvn exec:java -pl json-compatibility-suite

# Run JSON output (dogfoods the API)
mvn exec:java -pl json-compatibility-suite -Dexec.args="--json"

JSON Type Definition (JTD) Validator

This repo includes an incubating JTD validator (RFC 8927) in module json-java21-jtd. Per RFC 8927, the empty schema {} accepts all JSON instances.

import json.java21.jtd.Jtd;
import jdk.sandbox.java.util.json.*;

JsonValue schema = Json.parse("""
  {
    "properties": {
      "name": {"type": "string"},
      "age": {"type": "int32"}
    }
  }
""");

JsonValue data = Json.parse("{\"name\":\"Alice\",\"age\":30}");

Jtd.Result result = new Jtd().validate(schema, data);
// result.isValid() == true

Status

This code (as of 2026-01-25) is derived from the OpenJDK jdk-sandbox repository “json” branch. The API may evolve as the upstream design develops.

License

GNU General Public License version 2 with Classpath exception (same as OpenJDK).