Layer configs from several files
FileSource picks the first matching file — one config wins, the rest are ignored. LayeredFileSource is the merge counterpart: it collects one file per search dir, folds them into a single serde_json::Value tree, applies programmatic overrides, and deserializes into your model. Use it when a base config (say, ~/.config/myapp/myapp.yaml) should be overridden by a project or environment file rather than replaced by it.
Swap the source
use scarab_config_file::LayeredFileSource;
// same Discovery conventions as FileSource::for_app
let cfg: MyConfig = LayeredFileSource::for_app("myapp").load()?;Under Discovery::for_app the dirs are [".", "~/.config/myapp"] and the last dir is the base: ~/.config/myapp/myapp.yaml loads first, ./myapp.yaml merges over it. Within each dir only the preferred file counts — myapp.yaml beats myapp.yml beats myapp.toml, and the losers are not merged.
Precedence, lowest to highest
<dir>/<name>.<ext>per search dir, last dir first- the explicit path /
$<NAME>_CONFIGfile — merged on top of every dir layer (unlikeFileSource, where it replaces discovery) overrides— flat dotted-path keys, the highest layer
use scarab_config_file::LayeredFileSource;
use serde_json::json;
use std::collections::BTreeMap;
let mut src = LayeredFileSource::<MyConfig>::for_app("myapp");
src.explicit = Some("./deploy/prod.yaml".into()); // top file layer
src.overrides = BTreeMap::from([
("server.port".to_string(), json!(8443)),
("server.tls.enabled".to_string(), json!(true)),
]);
let cfg = src.load()?;Merge semantics
Layers merge as serde_json::Value, never on your typed model — MyConfig only needs DeserializeOwned (no Serialize). merge_value does the folding:
- objects merge key-wise, recursively — a key the overlay omits survives from the base
- scalars, arrays, and null replace — arrays never concatenate; set
[c]over[a, b]and you get[c]
Each layer file must parse to a mapping — a top-level array or scalar is an error naming the path (config layer is not a mapping). Mixed formats across dirs are fine: a TOML user config under a YAML project config merges cleanly. A parse error names the file it came from.
Inspect the layers
layer_paths() returns the resolved layer paths in merge order (lowest precedence first) — handy for logging what will be merged:
for p in src.layer_paths()? {
println!("layer: {}", p.display());
}parse_layer(path) parses one file into a serde_json::Value if you need to inspect or transform a layer yourself; load_with(env) takes the same injected env lookup as FileSource for tests.
When not to layer
- You want "one file wins, done" — that's
FileSource; don't pay for a merge you don't need. - Your model can't round-trip through
serde_json::Value— e.g. it deserializes from a non-self-describing format lossily. The merge happens on JSON, so exotic serde attributes (#[serde(with)], borrowed data) may not survive the intermediateValue.