json5-java

This is a reference implementation of the JSON5 standard in Java 11+, capable of parsing and serialization of JSON5 data.

This library is an enhanced version of Synt4xErr0r4 / json5, which provides a better full-fledged API inspired by Google's Gson library.

Features

• Fully supports JSON5 according to the specification
• Extensive API for interacting with elements, inspired by Google's Gson library
• Supports comment parsing and writing (if they can be associated with an Json5Element)
• Fine-grained configuration options
• No runtime dependencies – ensures a clean supply chain

Installation

Download the latest release manually or add it as a Maven dependency. Don't worry the project is already in the Maven Central Repository. See the configuration below for your favorite build system.

Add via Maven

<dependencies>
    <dependency>
        <groupId>de.marhali</groupId>
        <artifactId>json5-java</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>

Add via Gradle

repositories {
  mavenCentral()
}

dependencies {
  implementation("de.marhali:json5-java:3.0.0")
}

Usage

This library can be used by either configuring a Json5 instance or by using the underlying Json5Parser and Json5Writer.

The following section describes how to use this library with the Json5 core class.

Configure Json5 instance

See Configuration Options for a full overview of possible options.

import de.marhali.json5.config.Json5Options;
import de.marhali.json5.Json5;

// Create Json5 instance using builder pattern to configure desired options
Json5 json5 = Json5.builder(builder -> builder
    .quoteless()
    .quoteSingle()
    .parseComments()
    .writeComments()
    .prettyPrinting()
    .build()
);

// Using configuration object
Json5Options options = Json5Options.builder()
    // ...
    .build();
Json5 json5 = new Json5(options);

Parsing

During parsing, a JSON5 file or string is converted into the corresponding Json5Element's.

import de.marhali.json5.Json5;
import de.marhali.json5.Json5Element;

Json5 json5 = ...

// Parse from a String
Json5Element element = 
        json5.parse("{ 'key': 'value', 'array': ['first val','second val'] }");

// ...

// Parse from a Reader or InputStream
try (InputStream stream = ...) {
    Json5Element element = json5.parse(stream);
    // ...
} catch (IOException e) {
    // ...
}

Serialization

During serialization, Json5Element's are converted to their string representation so that they can be written to a file, for example.

import de.marhali.json5.Json5;
import de.marhali.json5.Json5Element;

Json5Element element = ...

// Serialize to a String literal
String jsonString = json5.serialize(element);

// ...

// Serialize to a Writer or OutputStream        
try (OutputStream stream = ...) {
    json5.serialize(element, stream);
    // ...
} catch (IOException e) {
    // ...
}

Documentation

Detailed javadoc documentation can be found at javadoc.io.

API

This library provides a few core classes to interact with JSON5 elements.

• Json5: Core class for parsing and serialization
• Json5Options: Library configuration and options builder
• Json5Element: Root class for every JSON5 element
• Json5Null: Class representing the JSON5 null value
• Json5Object: Represents a JSON5 object
• Json5Array: Represents a JSON5 array
• Json5Primitive: Holds any primitive value (Boolean, Number or String)

For a better understanding of how to use the API, take a look at the unit tests.

Configuration Options

This library supports a few customizations to adjust the behaviour of parsing and serialization. For a detailed explanation see the Json5Options class.

• stringifyUnixInstants
• stringifyAscii
• allowNaN
• allowInfinity
• allowInvalidSurrogates
• quoteSingle
• quoteless
• allowBinaryLiterals
• allowOctalLiterals
• allowHexFloatingLiterals
• allowLongUnicodeEscapes
• allowTrailingData
• parseComments
• writeComments
• trailingComma
• insertFinalNewline
• digitSeparatorStrategy
• duplicateBehaviour
• indentFactor

To get started using this library, Json5Options.DEFAULT may be a good starting point, as these are the recommended options.

License

This library is released under the Apache 2.0 license.

Partial parts of the project are based on Gson and Synt4xErr0r4 / json5. The affected classes contain the respective license notice.

Contact

Marcel Haßlinger - @marhali_de - Portfolio Website

Project Link: https://github.com/marhali/json5-java

Donation

If this library helps you to reduce development time, you can give me a cup of coffee :)