Skip to main content

JSON5L Basics

Juneau supports converting arbitrary POJOs to and from JSON5L — a combination of the relaxed JSON5 dialect and JSONL's newline-delimited framing (one document per line). JSON5L is a good fit for human-edited line-delimited config and data files: it keeps JSONL's "one record per line" streaming model while tolerating comments, unquoted keys, single-quoted strings, and trailing commas on each line.

The Json5lSerializer converts POJOs to JSON5L, and the Json5lParser creates POJOs from JSON5L by parsing each line as a JSON5 value.

JSON5L support is included in juneau-marshall.

Maven
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-marshall</artifactId>
    <version>${juneau.version}</version>
</dependency>

Quick Start​

// A simple bean
public class Person {
    public String name;
    public int age;
    public Person() {}
    public Person(String name, int age) { this.name = name; this.age = age; }
}

// Serialize a list of beans to JSON5L
List<Person> people = List.of(new Person("Alice", 30), new Person("Bob", 25));
String json5l = Json5l.of(people);

By default the output is strict RFC-8259 JSON per line — byte-identical to JSONL:

{"name":"Alice","age":30}
{"name":"Bob","age":25}

Strict by default, JSON5 sugar opt-in​

The serializer emits strict JSON per line by default, keeping output maximally portable (any JSONL or JSON consumer can read it). Enable json5Sugar() to emit JSON5 sugar — single-quoted strings and unquoted field names where safe:

Json5lSerializer s = Json5lSerializer.create().json5Sugar().build();
String json5l = s.write(people);

Produces:

{name:'Alice',age:30}
{name:'Bob',age:25}

Parsing​

The parser accepts the full JSON5 dialect on each line. Because JSON5 is a strict superset of JSON, it also reads plain JSONL input unchanged:

// Strict JSONL, JSON5-sugared, or mixed lines all parse
String input =
    "// a header comment\n" +
    "{name:'Alice',age:30}\n" +
    "{\"name\":\"Bob\",\"age\":25}  // trailing comment\n";

List<Person> parsed = Json5l.to(input, List.class, Person.class);

Comment handling​

JSON5L follows JSON5 comment rules line-by-line:

  • A line that is blank or contains only a comment (// ... or a single-line /* ... */) is skipped, like a blank line.
  • Inline comments within a record's JSON are tolerated (e.g. {a:1} // note).
  • A /* ... */ block comment must open and close on the same physical line — block comments cannot span record boundaries, since each line is parsed independently.

Media Types​

  • Produces: application/json5l
  • Accepts: application/json5l, application/json5lines (alias), text/json5l, and (at a reduced q-value) the JSONL family application/jsonl, application/jsonlines, application/x-ndjson, text/jsonl.

REST Integration​

// JSON5L is included in BasicUniversalConfig
@Rest
public class MyResource extends RestServlet implements BasicUniversalConfig { ... }

Limitations​

  • No pretty-printing: Each value must fit on a single line; useWhitespace() is always suppressed.
  • First-line-only for single-object targets: When parsing to a single non-collection type, only the first non-blank, non-comment line is parsed; trailing lines are ignored.
  • No record-spanning block comments: A /* ... */ comment must begin and end on the same line.

Annotations​

@Json5lConfig applies to both Json5lSerializer and Json5lParser on a REST class or method (see Context Annotations). Its only attribute today is rank; JSON5L has no @Json5l data annotation or @Json5lApply.

See Also