java

jsonfold - Java

Compact and readable JSON formatting for humans.

jsonfold makes pretty-printed JSON more compact without turning it back into unreadable one-line JSON.

Most JSON serializers offer two extremes:

• compact machine output:

{"meta":{"version":1,"ok":true},"ids":[1,2,3,4],"matrix":[[1,2],[3,4]]}

• fully expanded pretty-printing for humans

{
  "meta": {
    "version": 1,
    "ok": true
  },
  "ids": [
    1,
    2,
    3,
    4
  ],
  "matrix": [
    [
      1,
      2
    ],
    [
      3,
      4
    ]
  ]
}

jsonfold sits in the middle. It keeps the readable structure of pretty JSON, but selectively folds small containers and packs short scalar runs when they fit within a target line width.

{
  "meta": { "version": 1, "ok": true },
  "ids": [ 1, 2, 3, 4 ],
  "matrix": [ [ 1, 2 ], [ 3, 4 ] ]
}

jsonfold is implemented as a streaming JSON formatting filter. It post-processes the pretty-printed JSON generated by an existing serializer.

Modules

The Java implementation consists of two Maven modules:

jsonfold-core

Core formatting engine.

Features:

• No Jackson dependency
• Streaming formatter
• Pack, fold and join operations
• Configurable formatting rules
• Can be used with any JSON serializer

jsonfold-jackson

Jackson integration and command-line utility.

Features:

• Jackson ObjectMapper integration
• Custom pretty printer optimized for JSONFold
• Standalone CLI tool
• Optional key sorting

Building

Build all modules:

mvn package

Build from a clean checkout:

mvn clean package

Installation

Requirements:

• Java 17+
• Maven 3.8+
• Jackson 2.12+ (Not tested on Jackson 3 Yet).

Available from Maven Central.

Core Formatter

If you are using Jackson for generating JSON (in a service, or in a client), look at the section Jackson Integration

It is possible to use jsonfold on top of other serializer. In this case, only the core module is needed.

Maven

<dependency>
    <groupId>dev.jsonfold</groupId>
    <artifactId>jsonfold-core</artifactId>
    <version>${jsonfold.version}</version>
</dependency>

Formatting Existing JSON

String json = Files.readString(Path.of("input.json"));

StringWriter out = new StringWriter();

try (JSONFoldWriter writer = new JSONFoldWriter(out)) {
    writer.write(json);
}

System.out.println(out);

Using a Custom Configuration

// Using predefined configuration.
JSONFold cfg = JSONFold.preset("high").withWidth(100) ;

// OR, Customize existing configuration.
JSONFold cfg = new JSONFold().withWidth(100) ;
cfg.setPackArrayItems(16) ;
cfg.setFoldArrayItems(16) ;

// Create a streaming writer
String json = Files.readString(Path.of("input.json"));
try (JSONFoldWriter writer = new JSONFoldWriter(System.out, cfg, true) ) {
    writer.write(json) ;
}

Jackson Integration

Maven

<dependency>
    <groupId>dev.jsonfold</groupId>
    <artifactId>jsonfold-jackson</artifactId>
    <version>${jsonfold.version}</version>
</dependency>

Configure an Existing ObjectMapper

import dev.jsonfold.format.JacksonJsonFold ;

ObjectMapper mapper = new ObjectMapper();

JacksonJsonFold.configure(mapper);

mapper.writerWithDefaultPrettyPrinter().writeValue(System.out, value);

Explicit Pretty Printer

ObjectWriter writer =
    mapper.writer(
        JacksonJsonFold.prettyPrinter(2)
    );

writer.writeValue(System.out, value);

Using JSONFoldWriter

Object value = mapper.readValue(input, Object.class);

JSONFold cfg = JSONFold.preset("default").withWidth(100) ;

Writer out = new JSONFoldWriter(
    System.out,
    cfg
);

mapper.writer(
        JacksonJsonFold.prettyPrinter(2))
      .writeValue(out, value);

CLI

In addition to modules that can be integrated into any Java project, A small self-contained JAR file provides CLI formatting capabilities (based on the Jackson JSON serializer). Use the full path to the jsonfold.jar file

Format JSON from standard input:

java -jar /path/to/jsonfold.jar < input.json

Format a file:

java -jar /path/to/jsonfold.jar data.json

Use a different compaction preset:

java -jar /path/to/jsonfold.jar \
    --compact=max \
    --width=100 \
    data.json

Sort object keys:

java -jar /path/to/jsonfold.jar \
    --sort-keys \
    data.json

Display help:

java -jar /path/to/jsonfold.jar --help

Presets

none
low
default
med
high
max

Performance

jsonfold is designed as a streaming formatter.

It does not parse JSON itself. Instead, it processes the pretty-printed output produced by an existing serializer and applies packing, folding and joining rules while preserving readability.

Memory usage is proportional to the currently open container hierarchy rather than the entire document size.

License

MIT License