PistonConfig

PistonConfig is a Java 25 configuration library for projects that need one document model across YAML, TOML, HOCON, JSON, JSONC, JSON5, and .properties.

Load a human-edited file, preserve comments and source detail where the backend exposes it, merge defaults, apply overrides, run migrations, and read values through the access style that fits your project.

Install

dependencies {
  implementation(platform("net.pistonmaster:pistonconfig-bom:0.1.0-SNAPSHOT"))
  implementation("net.pistonmaster:pistonconfig-core")
  implementation("net.pistonmaster:pistonconfig-yaml")
}

Load and Save

var path = Path.of("config.yml");
var loader = YamlConfigFormat.INSTANCE.loader();
var document = ConfigLoaders.load(path, loader);

document.mergeDefaults(defaults, MergeOptions.conservative());
ConfigLoaders.save(path, loader, document);

Start With the Job You Have

Choose modules

Select backends and access modules, then generate Gradle or Maven snippets.

Set up a config file

Build defaults, load a user file, merge missing values, apply overrides, and save the result.

Choose a format backend

Compare YAML, TOML, HOCON, JSON, JSONC, JSON5, and properties behavior.

Map object configs

Use annotated Java classes for defaults, comments, names, and path prefixes.

Centralize typed keys

Declare ConfigMe-style static properties with defaults, comments, and typed reads.

Copy a startup flow

Use a complete load, migrate, merge, override, validate, read, and save example.

How the Pieces Fit

Main Capabilities

Lossless Core

Objects, lists, scalars, nulls, comments, key decorations, source locations, scalar style, collection style, and backend metadata.

Established Backends

SnakeYAML, Apache Commons Configuration, json5-java, Night Config, and Lightbend Config do the parser-specific work.

Typed Access

Use built-in scalar codecs, custom codecs, annotations, static fields, or direct document edits from the same model.

Operational Tools

Merge defaults, apply environment and system property overrides, and run ordered schema migrations.

Reference Shortcuts

Need	Page
Compare all modules	Modules
Inspect public types	API Surface
Compare format behavior	Format Comparison
Understand metadata constants	Format Metadata
Pick the correct startup sequence	Startup Order