ConfigKit's simple Load accepts one strict YAML source (or explicit defaults-only input). LoadLayered additionally combines explicit lower-priority source groups with an independently selected main input. Sources can be host files, native fs.FS files, labeled bytes or readers, or snapshotted mappings. Enabled explicit imports compose strictly within their group; precedence between groups combines mappings recursively. Both entry points return a complete, validated configuration with detached metadata and safe diagnostics. Applications may perform audited defaulting and normalization through a resolver, then report domain errors and warnings through read-only semantic validation. Secret tags and a path predicate drive deterministic redacted effective YAML. Typed secret references resolve environment names before validation, and explicit secrets-directory bootstrap is available as a separate startup operation. Explicit CLI override records apply after inheritance and typed decoding, before application resolution. Value explanation is available through detached structured records and deterministic redacted output. Built-in extends relationships let a mapping inherit from a named sibling during the same load, retaining explicit presence and source/derivation history. The root Diff API compares frozen effective values from two successful same-type loads; the configuration contract and consumer guide describe its safe changed-region records and maintained workflows.

Sources can also be explicitly placed as sequence items. Configuration declarations and application registrations can give selected sequences scalar identities and choose how they combine across precedence and inheritance. Strict peers combine distinct records, while higher-priority collections can replace, append, or upsert whole records. See the sequence contract, maintained catalog examples, and ADR 0017.

Imports are also explicit: a source may name files, search declared directories, or select files with path globs. Applications can set load-wide import defaults while keeping declaration-specific exceptions. Files are acquired in authored declaration order; dependency-ready composition uses a shared stable scheduler. ConfigKit does not search conventional application paths implicitly. See the import contract, consumer examples, and ADR 0015 and ADR 0016.

Main-file discovery is explicit too: applications choose and order Search descriptions and pass SearchConfig to the existing load APIs. See the discovery contract, consumer guide, and ADR 0019.

type Config struct {
    Enabled bool `yaml:"enabled"`
    Workers int  `yaml:"workers"`
}

func ReadConfig(path string) (Config, error) {
    result, err := configkit.Load[Config](configkit.File(path))
    if err != nil {
        return Config{}, err
    }
    return result.Config, nil
}

Design philosophy

ConfigKit favors one coherent, predictable configuration model over flexibility for reproducing each consumer's conventions. Its goal is to let applications load once, inspect where final values came from, and distinguish explicit values from omissions with minimal configuration bookkeeping. Applications retain their domain rules and execution responsibilities.

Loading is synchronous and complete on return. Applications normally load once near startup and then use the final configuration and metadata; ConfigKit stays inactive until explicitly called again. Applications may initiate additional loads as needed. See the loading lifecycle for completion and ownership details.

Within a configuration tier, independent contributions compose strictly: shared mappings combine, while overlapping non-mapping definitions are errors. Between precedence tiers, mappings combine recursively, retaining omitted lower-priority children; other values replace lower-priority values. The main document and its imports form one strictly composed tier. Explicit underlay groups sit below it and above typed defaults; a selected overlay applies before inheritance, while explicit CLI overrides apply after decoding and before application resolution. The configuration contract owns the detailed combination rules and input-specific constraints. Declared or registered collections combine distinct identified records within strict tiers and use their selected operation at precedence boundaries; other sequences keep their strict-conflict and whole-value-replacement behavior.

The architecture goals explain these priorities and how genuine new needs can justify extending the shared model. The future feature list preserves candidates for consideration in future releases.

The configuration contract describes implemented behavior, including input destinations. The consumer adoption guide provides maintained simple, layered, mounted-collection, and identified-prompt examples alongside the migration shapes. Input placement decisions are recorded in ADR 0011 and sequence placement and composition in ADR 0014. See the development guide for repository orientation and the release procedure for maintainer-only candidate and publication steps.

ConfigKit code is licensed under the LGPL v3.0 or later.

Open Source attribution notices are available.