Configuration
Requires the
configCargo feature, which is enabled by default.
The primary feature of Schematic is a layered serde-driven configuration solution, and is powered
through the Config and ConfigEnum traits, and their
associated derive macro. These macros help to generate and automate the following (when applicable):
- Generates a partial implementation, with all field values wrapped in
Option. - Provides default value and environment variable handling.
- Implements merging and validation logic.
- Models a schema (when
schemaCargo feature enabled). - And other minor features, like context & metadata.
The struct or enum that derives Config represents the final state, after all
partial layers have been merged, and default and environment variable values have
been applied. This means that all fields (settings) should not be wrapped in Option, unless the
setting is truly optional (think nullable in the config file).
#![allow(unused)]
fn main() {
#[derive(Config)]
struct ExampleConfig {
pub number: usize,
pub string: String,
pub boolean: bool,
pub array: Vec<String>,
pub optional: Option<String>,
}
}
This pattern provides the optimal developer experience, as you can reference the settings as-is, without having to unwrap them, or use
matchorif-letstatements!
Usage
Define a struct or enum and derive the Config trait. Fields within the struct
(known as settings) can be annotated with the #[setting] attribute to provide
additional functionality.
#![allow(unused)]
fn main() {
use schematic::Config;
#[derive(Config)]
struct AppConfig {
#[setting(default = 3000, env = "PORT")]
pub port: usize,
#[setting(default = true)]
pub secure: bool,
#[setting(default = vec!["localhost".into()])]
pub allowed_hosts: Vec<String>,
}
}
Loading sources
When all of your structs and enums have been defined, you can then load, parse, merge, and validate a configuration from one or many sources. A source is either a file path, secure URL, inline code string, or a partial in memory.
Begin by importing the
ConfigLoader struct and
initializing it with the Config
type you want to load.
#![allow(unused)]
fn main() {
use schematic::ConfigLoader;
let loader = ConfigLoader::<AppConfig>::new();
}
From here, you can feed it sources to load. For file paths, use the
ConfigLoader::file()
or
ConfigLoader::file_optional()
methods. For URLs, use the
ConfigLoader::url()
method (requires the url Cargo feature, which is not enabled by default). For inline code, use the
ConfigLoader::code()
method, which requires an explicit format, and names the source within errors.
#![allow(unused)]
fn main() {
loader.code("secure: false", "example.yml")?;
loader.file("path/to/config.yml")?;
loader.url("https://ordomain.com/to/config.yaml")?;
}
The formats to use are derived from the trailing file extension.
An optional file that doesn’t exist provides nothing, so it’s left out of ConfigLoadResult.layers.
A partial that’s already in memory, like one parsed from command line arguments, is
added with the
ConfigLoader::partial()
method, along with a name to use within error messages. Nothing is parsed, but it’s otherwise loaded
like any other source: merged in the order it was added, validated, and able to
extend other sources. A relative file it extends is resolved against the
working directory.
#![allow(unused)]
fn main() {
loader.partial("CLI arguments", PartialAppConfig {
port: Some(8080),
..Default::default()
});
}
Like every source, a partial sits below environment variables, which are applied last. For command line arguments to take precedence over the environment, read the variables through your argument parser instead, such as with clap’s
envargument, rather than with#[setting(env)].
And lastly call the
ConfigLoader::load()
method to generate the final configuration. This methods returns a result, which includes the final
configuration, as well as all of the partial layers that were merged into it.
#![allow(unused)]
fn main() {
let result = loader.load()?;
result.config; // AppConfig
result.layers; // Vec<Layer<PartialAppConfig>>
}
The layers are in order of precedence, and each one holds only the values it set, so a value can be
traced to where it came from. The default values come first, as
Source::Defaults, then each source in order, and the
environment variables last, as Source::EnvVars. The default values and
environment variables are left out when they set nothing.
Both are read against what the sources set, so they hold what applies to it: the defaults and variables of the variant an enum’s sources picked, and those of an optional nested config only when it’s present. The environment variables are read first, as a tag’s variable can pick a variant, and the defaults then go under the result.
Automatic schemas
When the schema Cargo feature is enabled, the
Schematic trait will be
automatically implemented for all types that implement
Config and
ConfigEnum. You do not and
should not derive both of these together.
#![allow(unused)]
fn main() {
// Correct
#[derive(Config)]
struct AppConfig {}
// Incorrect
#[derive(Config, Schematic)]
struct AppConfig {}
}
Supported source formats
Schematic is powered entirely by serde, and supports the following formats:
- JSON - Uses
serde_jsonand requires thejsonCargo feature. - Pkl - Uses
rpkland requires thepklCargo feature. - RON - Uses
ronand requires theronCargo feature. - TOML - Uses
tomland requires thetomlCargo feature. - YAML - Uses
serde_norwayand requires theyamlCargo feature. An externally tagged enum variant that holds a value is written as a YAML tag, like!file, rather than a map (more).
None of them is enabled by default, so enable the feature of each format you load. A source with no format to parse it fails to load, with an error that names the feature its extension needs.
Cargo features
The following Cargo features are available:
config(default) - Enables configuration support (all the above stuff).env(default) - Enables environment variables for settings.extends(default) - Enables configs to extend other configs.json- Enables JSON.pkl- Enables Pkl.ron- Enables RON.toml- Enables TOML.url- Enables loading, extending, and parsing configs from URLs.validate(default) - Enables setting value validation.yaml- Enables YAML.
env, extends, url, and validate only apply to configs, so each enables config as well. The
dependencies that only configs use are only compiled with config, so a build for
schemas alone, or without any feature, doesn’t pull them in.