JEP 198: Light-Weight JSON API

AuthorMike Duigou
Discussioncore dash libs dash dev at openjdk dot java dot net
Reviewed byBrian Goetz
Endorsed byBrian Goetz
Created2014/06/09 21:22
Updated2017/05/11 17:11


Provide a light-weight API for consuming and generating JSON documents and data streams.




JSON has become the lingua franca for web services and it is time for Java SE to adopt functionality for interacting with and utilizing JSON documents and data streams. This proposal is designed provide the most commonly needed functionality and take advantage of Java 8/9 language and library features.


It is expected that this JEP will be delivered as a set of new sub-packages in the java.util hierarchy and will consist of at least four modules; events, streams, trees, generators. No existing modules, packages, or classes are expected to be modified. The JSON API is not expected to have any dependencies that are not already part of the Java base module.

The stream events and document objects are immutable. Immutability enables dynamic footprint reductions by allowing instance sharing in both streams and document trees. Immutability is particularly important for tree transformations where most of the document tree is generally unmodified by the transformation and it is very desirable to have the original tree and the transformed tree share unmodified portions.

For parsing of JSON, two modes of usage will be provided: event streams and value trees. The event stream mode will provide in-order access to parse tokens or contextual events as they are individually parsed from the data stream (similar to SAX). The value tree mode will provide a navigable value hierarchy representing the entire document (similar to DOM). JSON data streams for output can be generated either from value trees or directly with a sequence of discrete operations (generator).

The APIs will support the following usage modes:


There are existing JSON APIs for Java. The most popular of these generally offer more functionality than the planned API and/or don't take advantage of Java 8/9 language and library features.


Beyond functional testing the key metrics are going to be static and dynamic footprint evaluations for common use cases. User testing and feedback is also going to be important in evolving the initial API.