JEP 540: Simple JSON API (Now in Incubator)

📋 Administrative Overview

Summary: This proposal establishes a standardized, lightweight API for the creation and parsing of JSON documents. The primary objective is to eliminate the mandatory reliance on third-party libraries for basic JSON operations and minimize the amount of boilerplate code required.

---

📜 Historical Context

This JEP serves as a replacement for JEP 198 (Light-Weight JSON API), which was originally proposed in 2014. Because the landscape of Java development and JSON usage has evolved significantly over the last decade, a completely different architectural approach has been adopted here.

---

🎯 Project Objectives

The primary aim is to provide a "low-ceremony" method for handling RFC 8259 compliant JSON within the Java Platform.

Key Goals:

• Strict Conformance: Support only the data types and operations necessary for RFC 8259 to ensure seamless machine-to-machine communication.
• Simplicity: Explicitly avoid complex features like:
  • Multiple parsing configurations.
  • Syntax extensions.
  • Data binding.
  • Streaming APIs.
• Readability: Ensure that code used to navigate known JSON structures is intuitive. Since JSON lacks a formal schema, the Java code itself should act as a de facto readable schema.
• Exploratory Capability: Facilitate the quick analysis of unknown JSON documents via "fail-fast" methods and descriptive error messages.
• Resilience: Provide mechanisms to handle evolving document structures (e.g., missing or unexpected values) gracefully.
• JDK Integration: Enable the JDK to natively parse and generate JSON.

🚫 Non-Goals

This API is not intended to replace comprehensive external libraries such as:

• Jackson
• Gson
• Jakarta JSON Processing/Binding
• Fastjson 2

These libraries provide advanced functionality—such as JSON5 support, event-based streaming, and highly customizable data binding (mapping Java objects to JSON)—that falls outside the scope of this simple API.

---

💡 Motivation & Use Case

Often, developers only need to perform trivial tasks. In languages like Go or Python, these tasks are concise; Java should be no different.

Example Scenario: Calculating the average temperature from a U.S. National Weather Service REST API response.

{
  "periods": [
    { "number": 1, "name": "Today", "temperature": 54, "temperatureUnit": "F" },
    { "number": 2, "name": "Tonight", "temperature": 48, "temperatureUnit": "F" },
    { "number": 3, "name": "Thursday", "temperature": 68, "temperatureUnit": "F" }
  ]
}

To find the average, one must parse the document, locate the periods array, and iterate through the temperatures. Mathematically, this is represented as: $\text{Average} = \frac{\sum_{i=1}^{n} \text{temperature}_i}{n}$

By reducing ceremony, Java aligns with recent platform improvements like var declarations, convenience factory methods for collections, and the ability to run source files directly.

---

🛠️ Integration within the JDK

Because the JDK cannot depend on external libraries, a native JSON API allows the platform to modernize its own configuration. Currently, the JDK relies on .properties files, which struggle with structured data.

Comparison of Configuration Styles:

---

📖 API Description

The jdk.incubator.json API is centered around the JsonValue interface.

JSON Data Types

The API maps directly to the JSON specification:

1. Strings: Double-quoted text (e.g., "Hello").
2. Numbers: Base-10 decimals (e.g., 31.84, 2.9E+5).
3. Booleans: true or false.
4. Null: The null literal.
5. Objects: Key-value pairs enclosed in { }.
6. Arrays: Ordered lists of values enclosed in [ ].

Interface Hierarchy

The following diagram illustrates the relationship between the core interfaces:

Each of these sub-interfaces—JsonString, JsonNumber, JsonBoolean, JsonNull, JsonObject, and JsonArray—provides the specific operations required to manipulate that particular JSON type.

Figure 1: Conceptual representation of the Simple JSON API structure.