README
¶
yamlcfg
yamlcfg is a wrapper around the goccy/go-yaml library and provides a convenient way to configure Go applications with YAML and environment variables.
The library can also automatically call Validate functions if present on the given config struct.
Why?
Not every configuration value needs to be an environment variable. Database pool sizes, timeouts, feature flags, and other stable settings are better expressed as static YAML values that live in version control alongside your code. But secrets and environment-specific values (database URLs, API keys, listen addresses) still need to come from the environment.
yamlcfg lets you combine both in a single config file — static values that rarely change sit next to ${VAR} references that get resolved at startup. This means fewer environment variables to manage, sensible defaults via ${VAR:default} syntax, and a single file that documents your application's full configuration surface.
Installation
go get github.com/aranw/yamlcfg
Environment Variables
yamlcfg expands environment variables in YAML values using the ${VAR} syntax:
database_url: "${DATABASE_URL}"
Default values are supported with ${VAR:default}:
log_level: "${LOG_LEVEL:info}"
port: "${PORT:8080}"
Environment variables can also appear within larger strings:
dsn: "host=${DB_HOST:localhost} port=${DB_PORT:5432} dbname=${DB_NAME:myapp}"
Note: bare $VAR references (without braces) are treated as literal strings and not expanded.
Usage
Parse
Reads a YAML file from disk and unmarshals it into the given type:
type Config struct {
LogLevel string `yaml:"log_level"`
Port int `yaml:"port"`
}
cfg, err := yamlcfg.Parse[Config]("config.yaml")
if err != nil {
log.Fatal(err)
}
ParseWithConfig
Parses a YAML file with pre-populated default values. Fields not present in the YAML file retain their defaults:
defaults := &Config{
LogLevel: "info",
Port: 8080,
}
cfg, err := yamlcfg.ParseWithConfig(defaults, "config.yaml")
if err != nil {
log.Fatal(err)
}
ParseFS
Reads a YAML file from an embed.FS:
//go:embed config.yaml
var configFS embed.FS
cfg, err := yamlcfg.ParseFS[Config](configFS, "config.yaml")
if err != nil {
log.Fatal(err)
}
UnmarshalConfig
Unmarshals raw YAML bytes directly, expanding environment variables:
data := []byte(`log_level: "${LOG_LEVEL:debug}"`)
var cfg Config
if err := yamlcfg.UnmarshalConfig(&cfg, data); err != nil {
log.Fatal(err)
}
Validation
If your config struct implements a Validate() error method, it will be called automatically after unmarshalling:
type Config struct {
LogLevel string `yaml:"log_level"`
}
func (c *Config) Validate() error {
validLevels := []string{"debug", "info", "warn", "error"}
if !slices.Contains(validLevels, c.LogLevel) {
return fmt.Errorf("invalid log level: %s", c.LogLevel)
}
return nil
}
Options
All loading functions accept functional Options. Decoding is strict by default (unknown fields and duplicate keys are rejected); options can relax or extend that behaviour:
cfg, err := yamlcfg.Parse[Config]("config.yaml",
yamlcfg.AllowUnknownFields(), // ignore unknown keys
yamlcfg.AllowDuplicateKeys(), // last duplicate key wins
yamlcfg.AllowFieldPrefixes("x_"), // let strict mode pass keys with these prefixes
yamlcfg.UseOrderedMap(), // decode untyped maps as *yaml.MapSlice
)
Cross-file references
Anchors and aliases can be defined in other YAML files, enabling shared defaults.yaml-style configs:
cfg, err := yamlcfg.Parse[Config]("config.yaml",
yamlcfg.WithReferenceFiles("defaults.yaml"),
)
WithReferenceDirs and WithRecursiveDirs load reference files from directories, WithReferenceReaders from any io.Reader, and WithEmbeddedReferences from the same embed.FS used with ParseFS:
cfg, err := yamlcfg.ParseFS[Config](configFS, "config.yaml",
yamlcfg.WithEmbeddedReferences(configFS, "defaults.yaml"),
)
Note: ${VAR} environment variable expansion only applies to the main config data, not to referenced files.
Pluggable validation
Besides the Validate() error interface, a StructValidator can be plugged in — the interface implemented by go-playground/validator, so tag-based validation runs automatically after decoding:
validate := validator.New()
cfg, err := yamlcfg.Parse[Config]("config.yaml",
yamlcfg.WithValidator(validate), // struct tags like `validate:"min=1"`
)
Typed errors
YAML errors returned by this package wrap the underlying typed errors from goccy/go-yaml, so failures can be handled programmatically with errors.As:
var fieldErr *yamlcfg.UnknownFieldError
if errors.As(err, &fieldErr) {
line, col, _ := yamlcfg.Position(err)
log.Printf("unknown field at config.yaml:%d:%d", line, col)
}
Convenience predicates IsSyntaxError, IsTypeError, IsUnknownFieldError, IsDuplicateKeyError and IsOverflowError are also available, and every typed error's Error() includes the offending source line with a position marker.
License
The yamlcfg package is licensed under the MIT license. Please see the LICENSE file for details.
Documentation
¶
Index ¶
- func IsDuplicateKeyError(err error) bool
- func IsOverflowError(err error) bool
- func IsSyntaxError(err error) bool
- func IsTypeError(err error) bool
- func IsUnknownFieldError(err error) bool
- func Parse[T any](path string, opts ...Option) (*T, error)
- func ParseFS[T any](fs embed.FS, path string, opts ...Option) (*T, error)
- func ParseWithConfig[T any](cfg *T, path string, opts ...Option) (*T, error)
- func Position(err error) (line, column int, ok bool)
- func UnmarshalConfig[T any](cfg *T, data []byte, opts ...Option) error
- type DuplicateKeyError
- type Error
- type Option
- func AllowDuplicateKeys() Option
- func AllowFieldPrefixes(prefixes ...string) Option
- func AllowUnknownFields() Option
- func UseOrderedMap() Option
- func WithEmbeddedReferences(fsys embed.FS, paths ...string) Option
- func WithRecursiveDirs(dirs ...string) Option
- func WithReferenceDirs(dirs ...string) Option
- func WithReferenceFiles(paths ...string) Option
- func WithReferenceReaders(readers ...io.Reader) Option
- func WithValidator(v StructValidator) Option
- type OverflowError
- type StructValidator
- type SyntaxError
- type TypeError
- type UnknownFieldError
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsDuplicateKeyError ¶ added in v0.8.0
IsDuplicateKeyError reports whether err was caused by a duplicate mapping key (only possible without AllowDuplicateKeys). goccy currently reports duplicate keys as a SyntaxError whose message says the key is "already defined", so this check also matches that form.
func IsOverflowError ¶ added in v0.8.0
IsOverflowError reports whether err was caused by a number that overflows the destination Go type.
func IsSyntaxError ¶ added in v0.8.0
IsSyntaxError reports whether err was caused by malformed YAML.
func IsTypeError ¶ added in v0.8.0
IsTypeError reports whether err was caused by a YAML value that cannot be converted to the destination Go type.
func IsUnknownFieldError ¶ added in v0.8.0
IsUnknownFieldError reports whether err was caused by a YAML key that does not match any struct field (only possible without AllowUnknownFields).
func Parse ¶
Parse takes the given path and attempts to read and unmarshal the config The given config will also be validated if it has a Validate function on it
Example ¶
package main
import (
"log/slog"
"github.com/aranw/yamlcfg"
)
type Config struct {
LogLevel string `yaml:"log_level"`
}
func main() {
cfg, err := yamlcfg.Parse[Config]("config.yaml")
if err != nil {
slog.Error("loading yaml config", "err", err)
return
}
_ = cfg.LogLevel
}
Output:
func ParseFS ¶
ParseFS attempts to load the given path and config from a embed.FS
Example ¶
package main
import (
"embed"
"log/slog"
"github.com/aranw/yamlcfg"
)
type Config struct {
LogLevel string `yaml:"log_level"`
}
//go:embed testdata
var testdata embed.FS
func main() {
cfg, err := yamlcfg.ParseFS[Config](testdata, "config.yaml")
if err != nil {
slog.Error("loading yaml config", "err", err)
return
}
_ = cfg.LogLevel
}
Output:
func ParseWithConfig ¶ added in v0.2.0
ParseWithConfig takes the given config and path and attempts to read and unmarshal the config The given config can be populated with default values If the given config implements a `Validate() error` function this will be called
Example ¶
package main
import (
"log/slog"
"github.com/aranw/yamlcfg"
)
type Config struct {
LogLevel string `yaml:"log_level"`
}
func main() {
defaults := &Config{
LogLevel: "info",
}
cfg, err := yamlcfg.ParseWithConfig(defaults, "config.yaml")
if err != nil {
slog.Error("loading yaml config", "err", err)
return
}
_ = cfg.LogLevel
}
Output:
func Position ¶ added in v0.8.0
Position returns the line and column (1-based) of the YAML token that caused err, if that information is available.
func UnmarshalConfig ¶
UnmarshalConfig takes the provided yaml data and unmarshals it into the provided config struct. It will return an error if the decoding fails or if the yaml data is not in the expected format. It will also expand any environment variables in the yaml data
Example ¶
package main
import (
"fmt"
"log/slog"
"github.com/aranw/yamlcfg"
)
type Config struct {
LogLevel string `yaml:"log_level"`
}
func main() {
data := []byte(`log_level: "debug"`)
var cfg Config
if err := yamlcfg.UnmarshalConfig(&cfg, data); err != nil {
slog.Error("unmarshalling config", "err", err)
return
}
fmt.Println(cfg.LogLevel)
}
Output: debug
Types ¶
type DuplicateKeyError ¶ added in v0.8.0
type DuplicateKeyError = yaml.DuplicateKeyError
DuplicateKeyError reports a duplicate mapping key.
type Error ¶ added in v0.8.0
Error is implemented by every typed error below. It provides the offending token, a plain message, and pretty source-formatted output.
type Option ¶ added in v0.8.0
type Option func(*decodeConfig)
Option customises how a YAML config is decoded. Options are accepted by Parse, ParseWithConfig, ParseFS and UnmarshalConfig.
func AllowDuplicateKeys ¶ added in v0.8.0
func AllowDuplicateKeys() Option
AllowDuplicateKeys allows duplicate mapping keys in the YAML input. Without this option duplicate keys are an error. When allowed, the last value wins.
func AllowFieldPrefixes ¶ added in v0.8.0
AllowFieldPrefixes, while strict decoding is enabled, allows YAML keys with the given prefixes to bypass the unknown field check.
func AllowUnknownFields ¶ added in v0.8.0
func AllowUnknownFields() Option
AllowUnknownFields disables strict decoding so that YAML keys that do not match any struct field are ignored instead of rejected.
func UseOrderedMap ¶ added in v0.8.0
func UseOrderedMap() Option
UseOrderedMap preserves mapping key order by decoding untyped values (interface{} destinations) as a *yaml.MapSlice instead of a map.
func WithEmbeddedReferences ¶ added in v0.8.0
WithEmbeddedReferences allows a config parsed from an embed.FS to reference anchors and aliases defined in other YAML files from the same embed.FS. Files are opened lazily, so a missing file surfaces as a decode error.
func WithRecursiveDirs ¶ added in v0.8.0
WithRecursiveDirs works like WithReferenceDirs but searches the given directories recursively.
func WithReferenceDirs ¶ added in v0.8.0
WithReferenceDirs allows the config to reference anchors and aliases defined in YAML files under the given directories (searched non-recursively).
func WithReferenceFiles ¶ added in v0.8.0
WithReferenceFiles allows the config to reference anchors and aliases defined in the given YAML files. Note that environment variable expansion only applies to the main config data, not to referenced files.
func WithReferenceReaders ¶ added in v0.8.0
WithReferenceReaders allows the config to reference anchors and aliases defined in YAML documents read from the given readers.
func WithValidator ¶ added in v0.8.0
func WithValidator(v StructValidator) Option
WithValidator registers a StructValidator that runs against the decoded value before decoding is considered successful.
type OverflowError ¶ added in v0.8.0
type OverflowError = yaml.OverflowError
OverflowError reports a number that overflows the destination type.
type StructValidator ¶ added in v0.8.0
type StructValidator = yaml.StructValidator
StructValidator validates a decoded value. It matches the interface implemented by validation libraries such as go-playground/validator (see validator.Validate.Struct), which can be plugged in directly.
type SyntaxError ¶ added in v0.8.0
type SyntaxError = yaml.SyntaxError
SyntaxError reports malformed YAML, including duplicate mapping keys.
type TypeError ¶ added in v0.8.0
TypeError reports a YAML value that cannot be converted to the destination Go type.
type UnknownFieldError ¶ added in v0.8.0
type UnknownFieldError = yaml.UnknownFieldError
UnknownFieldError reports a YAML key with no matching struct field.
Source Files