konform

konform is a schema-first configuration library for Go. Define typed config structs once, then load from files and environment with defaults, validation, strict checks, and load reporting.

Configuration in Go often ends up split across multiple libraries and custom glue code. That usually leads to duplicated mapping logic, unclear precedence, and inconsistent validation.

konform keeps this explicit and predictable by using struct tags as the schema and a small loading API.

konform is not trying to be the most feature-rich configuration framework. It is optimized for strict, typed, schema-first loading with explainable outcomes.

Use konform when you want predictable, typed config behavior and explicit failure modes. Use Viper/Koanf when you need broader provider ecosystems, dynamic config workflows, or more runtime flexibility.

• Schema-first configuration from typed Go structs
• Multiple sources: environment variables, .env files, YAML/JSON/TOML files, YAML/JSON/TOML bytes
• Environment prefixing for env and .env lookups via konform.WithEnvPrefix(...)
• Defaults via struct tags
• Custom decoding via encoding.TextUnmarshaler (including pointer fields)
• Validation rules (required, min, max, len, minlen, maxlen, regex, oneof, nonzero, url, email)
• Custom validators via konform.WithCustomValidator(...)
• Strict mode (konform.Strict()) for unknown structured keys and mapping conflicts
• Unknown-key handling modes: konform.ModeWarn, konform.ModeError, konform.ModeOff
• Load report with field values and value sources
• Secret masking in reports using secret:"true"
• Nested struct support
• Deterministic precedence through explicit source order
• Clear, human-friendly validation and decode errors

go get github.com/nzhussup/konform

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/nzhussup/konform"
)

type Config struct {
	Server struct {
		Host string `key:"server.host" default:"127.0.0.1"`
		Port int    `key:"server.port" default:"8080" env:"PORT"`
	}
	Database struct {
		URL string `key:"database.url" env:"DATABASE_URL" validate:"required" secret:"true"`
	}
	Log struct {
		Level string `key:"log.level" default:"info"`
	}
}

func main() {
	var cfg Config

	report, err := konform.Load(
		&cfg,
		konform.FromYAMLFile("config.yaml"),
		konform.FromDotEnvFile(".env"),
		konform.FromEnv(),
		konform.WithEnvPrefix("APP_"),
		konform.WithUnknownKeySuggestionMode(konform.ModeWarn),
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v\n", cfg)
	report.Print(os.Stdout)
}

konform applies values in this order:

defaults < file < .env < env

This behavior is controlled by the order of options passed to Load. If multiple sources set the same field, the later source wins.

Use konform.Strict() to enforce:

• unknown keys in structured sources are errors
• decode/type mismatches are errors
• invalid mapped env values are errors
• duplicate/conflicting key or env mappings are errors
• unrelated environment variables are ignored

• key: path used for YAML/JSON lookup (defaults to struct field path when omitted)
• env: environment variable name
• default: default value used when the field is zero-valued before source loading
• validate: validation rules after all sources are applied
• secret: if truthy (true, 1, yes, on), report value is masked as ***

• konform.ModeWarn (default): print warning, continue load
• konform.ModeError: return decode error
• konform.ModeOff: ignore unknown keys

Set mode with:

konform.WithUnknownKeySuggestionMode(konform.ModeError)

Load returns (*LoadReport, error).

Report entries include:

• resolved path
• final value (masked for secret fields)
• source (default, file path, env:VAR_NAME, or zero)

Print formatted report:

report.Print(os.Stdout)

See runnable examples in examples/:

• examples/basic
• examples/env
• examples/yaml
• examples/json
• examples/toml
• examples/report

More docs:

• Getting Started
• Features
• Strict Mode
• Reporting
• Reference
• Stability and Support Policy

• Minimal magic
• Explicit behavior
• Idiomatic Go APIs and errors

Konform follows semantic versioning and a documented compatibility policy. See Stability and Support Policy.

MIT. See LICENSE.