Guides

Use these guides when you are wiring PistonConfig into an application, choosing a backend, defining typed access, or planning upgrade behavior.

Start with the full startup flow, then branch into the access style or operational feature your project needs.

Core Workflow

Load, merge, override, read, and save a document.

Install modules with Gradle, Maven, the BOM, Maven Central, and GitHub Packages.

Dispatch loaders by extension and keep application behavior format-neutral.

Edit documents, nodes, comments, paths, and decorations directly.

Encode domain value objects through typed serializers or static-field codecs.

Map Java records and classes to typed config files.

Declare typed keys once and read values through shared property declarations.

Compare manual nodes, typed stores, static fields, and custom serialization.

Choose YAML, TOML, HOCON, JSON-family, or properties support.

Merge shipped defaults into existing user documents safely.

Apply process environment and system property values on top of files.

Run ordered schema migrations and store the applied version.

Test codecs, mappings, migrations, and round-trip behavior.

Report missing values, invalid types, and source-aware config errors.