zio/zio-config
56.4
Adequate · 6 November 2026
5k
lines of production code
Scala
primary language
4
measurements over time
What this system is
This system is a configuration management library for the ZIO ecosystem that enables applications to load and parse settings from diverse sources, including AWS SSM, HOCON, YAML, TOML, and XML. It provides robust automatic derivation of configuration descriptors for Scala case classes and sealed traits via Magnolia, while supporting integration with external type systems like Cats, Scalaz, Refined, and Pureconfig. The library ensures type safety and flexibility through features like key naming conventions, discriminated unions, and structured documentation generation.
How it got here
2019–2021 — ZIO 2 migration and Magnolia integration
28 changes.
The project migrated its build infrastructure to ZIO 2, Scala 3, and sbt 1.13, while introducing a new Magnolia-based auto-derivation system for configuration descriptors. This period focused on expanding ecosystem compatibility by adding support for Cats, Scalaz, Pureconfig, Refined, and Enumeratum, alongside new providers for HOCON and YAML. Comprehensive test coverage and documentation generation utilities were also implemented to support these new features and ensure stability across multiple platforms.
2022–2026 — multi-format config provider expansion
6 changes.
This period focused on expanding the library's configuration capabilities by adding support for AWS SSM Parameter Store, XML, and TOML formats. It also introduced syntax enhancements for key mapping and error formatting, alongside comprehensive test coverage for new and existing providers.
Features
Add AWS Systems Manager Parameter Store configuration provider
Users can now load configuration directly from AWS Systems Manager (SSM) Parameter Store. A new \ParameterStoreConfigProvider\ implementation queries parameters by path with recursive traversal and automatic decryption, converting them into a \ConfigProvider\. This is exposed via a convenient \fromParameterStore\ extension method on \ConfigProvider\, allowing applications to seamlessly integrate SSM parameters into their configuration sources.
aws/shared, zio-aws/shared · high confidence
Add Pureconfig integration for configuration reading
Users can now leverage Pureconfig to read configuration values within ZIO Config. A new \pureconfig\ module provides a \fromPureconfig\ method that accepts a Pureconfig \ConfigReader\, allowing existing Pureconfig parsers to be used directly to define ZIO \Config\ descriptors. This enables seamless interoperability, letting you parse complex types using Pureconfig's ecosystem while maintaining the ZIO Config API for loading and nesting.
pureconfig/shared · high confidence
Add Scala 2 magnolia-based auto-derivation for ZIO Config
Introduces a new \DeriveConfig\ typeclass and \deriveConfig\ helper in the \zio.config.magnolia\ package for Scala 2.12/2.13, enabling automatic derivation of configuration descriptors for case classes and sealed traits. This feature supports standard types (e.g., \String\, \Int\, \Duration\, \URI\), collections (\List\, \Set\, \Map\), and nested structures, while allowing users to customize key naming via annotations like \@kebabCase\, \@snakeCase\, \@prefix\, and \@postfix\, and to provide descriptions with \@describe\.
magnolia/shared/src/main/scala-2.12-2.13 · high confidence
Add Scalaz type-class instances and conversion helpers
zio-config now supports Scalaz by providing implicit Applicative instances for Config and utility functions to convert ZIO Config types to Scalaz data structures (IList, ISet, ==\>\>, Maybe). Users can now seamlessly integrate zio-config with Scalaz-based codebases without manual conversion.
scalaz/shared · high confidence
Add TOML configuration support
Users can now load configuration from TOML files, paths, readers, or strings using the new \TomlConfigProvider\. This adds a new \zio.config.toml\ module that integrates with the existing \ConfigProvider\ API, allowing applications to parse TOML-formatted settings alongside other supported formats.
toml/shared · high confidence
Add Typesafe Config provider for ZIO
Users can now load configuration from Typesafe Config (HOCON) sources using ZIO effects. This change introduces the \TypesafeConfigProvider\ object and extension methods on \ConfigProvider\ (e.g., \fromResourcePath\, \fromHoconFile\, \fromHoconString\) that wrap the underlying Typesafe Config library. It supports both synchronous and ZIO-based (\ZIO.attempt\) loading, allows enabling comma-separated values as lists, and handles complex nested structures, optional fields, and null values in HOCON configurations.
typesafe/shared · high confidence
Add support for Enumeratum enums in configuration
Users can now read Enumeratum enum values directly from configuration sources. This change introduces a new \zio.config.enumeratum\ package that provides specific config readers for standard \EnumEntry\, as well as numeric and character variants (\IntEnum\, \LongEnum\, \ShortEnum\, \ByteEnum\, \CharEnum\, and \StringEnum\). These readers automatically parse string representations from configuration into the corresponding Scala enum types, handling validation and error reporting for invalid values.
enumeratum/shared · high confidence
Added Scala 3 auto-derivation examples for discriminated sum types
New example files demonstrate how to use ZIO Config's Magnolia integration in Scala 3 to automatically derive configuration from case classes, including support for discriminated sum types (sealed traits) using the @discriminator annotation and custom naming via @name.
magnolia/shared/src/main/scala-dotty/zio/config/magnolia/examples · high confidence
Added macro-based tuple conversion support for Scala 2
A new TupleConversion mechanism has been introduced for Scala 2.x, enabling automatic conversion between case classes and tuples (including single-parameter, multi-parameter, and zero-parameter cases) via compile-time macros. This allows users to seamlessly convert configuration values represented as case classes into tuple formats and vice versa, simplifying data transformation workflows within the configuration library.
core/shared/src/main/scala-2.x · high confidence
Added refined type support for configuration descriptors
The library now provides built-in support for the \eu.timepit:refined\ library, allowing configuration values to be automatically validated against refined predicates. Users can use the new \refine\ function to apply a specific predicate to an existing configuration descriptor, or use \refineType\ to derive a configuration directly from a fully formed refined type (e.g., \NonEmptyString\). This enables stricter type safety in configuration parsing without manual validation logic.
refined/shared/src/main · high confidence
Added shared configuration examples for zio-config
The examples/shared area now includes a comprehensive suite of demonstration files and configuration resources for the zio-config library. This addition introduces HOCON and YAML configuration files (application.conf, application.yml) alongside Scala examples covering auto-derivation (including sealed traits, custom keys, and PureConfig interop), manual configuration descriptions, list and map handling, error reporting, and documentation generation. These files serve as reference implementations for users to understand how to integrate and use the library's features.
examples/shared · high confidence
Added support for Cats NonEmpty collections in configuration
The cats integration module now provides specific configuration descriptors for Cats' NonEmpty collections, including NonEmptyChain, NonEmptyList, and NonEmptyMap. Users can now directly parse configuration values into these types, with the library automatically handling validation to ensure the resulting collections are not empty, returning a Config.Error.InvalidData if the source data is empty.
cats/shared/src/main/scala/zio/config/cats · high confidence
Adds Cats typeclass instances for ZIO Config
The \zio.config.cats.instances\ package now provides implicit typeclass instances that integrate ZIO Config with the Cats ecosystem. Users can now treat \Config\ as an \Applicative\ and \SemigroupK\, allowing for applicative composition and alternative combination of configuration descriptions. Additionally, \ConfigProvider\ instances now support \Semigroup\ semantics (combining providers via fallback) and \Config.Error\ supports equality checks via \Eq\.
cats/shared/src/main/scala/zio/config/cats/instances · high confidence
Experimental XML configuration provider added
An experimental XML configuration provider is now available, allowing users to load configuration from XML strings via \ConfigProvider.fromYamlString\ (note: method name remains \fromYamlString\ despite XML functionality). This new capability includes an XML parser (\XmlParser\) that converts XML strings into a flattened map structure (\XmlObject\), which is then wrapped in a standard \ConfigProvider\. The implementation relies on \zio-parser\ for tokenizing and parsing XML tags, attributes, and text content.
xml/shared/src/main · high confidence
New configuration documentation and key-conversion utilities
The library now includes a ConfigDocsModule that allows users to convert configuration schemas into structured Table formats for documentation generation, alongside new key-conversion functions (toKebabCase, toSnakeCase, addPrefixToKey) and a path interpolator in the main package object to simplify configuration path handling.
core/shared/src/main/scala/zio/config · high confidence
New syntax extension for config key mapping and error formatting
The \zio.config.syntax\ package now provides new implicit classes to enhance configuration handling. Users can transform config keys using \mapKey\, \toKebabCase\, \toSnakeCase\, \toUpperCase\, and \toLowerCase\ on \Config\ objects, facilitating easier integration with various naming conventions. Additionally, a \prettyPrint\ method is available on \Config.Error\ to render detailed, tree-structured error messages for debugging. The package also introduces \IndexKey\ for generating indexed string representations and \ConfigProviderZIO\ support for handling asynchronous config provider loading.
core/shared/src/main/scala/zio/config/syntax · high confidence
Scala 3 auto-derivation for Config types
Users can now automatically derive \Config\ instances for their case classes and sealed traits in Scala 3 using the \derives Config\ syntax or the \DeriveConfig\ typeclass. This new magnolia-based implementation supports standard types, collections, and discriminated sum types, while also allowing customization via annotations like \@name\, \@discriminator\, and \@describe\ to control key naming and metadata.
magnolia/shared/src/main/scala-dotty/zio/config/magnolia · high confidence
Behavioural changes
Add ZIO 2-compatible YAML configuration provider with safe environment variable handling
The YAML module now provides a new \YamlConfigProvider\ and companion extension methods on \ConfigProvider\ (e.g., \fromYamlFile\, \fromYamlString\, \fromYamlReader\) that integrate with ZIO 2's \Task\ type for effectful loading. A key behavioral change is the introduction of \EnvConfigImpl\, which customizes how environment variable templates (like \:-\ and \:?\) are resolved, ensuring safe and consistent handling of missing environment variables during YAML parsing. Additionally, the provider supports an \enableCommaSeparatedValueAsList\ flag to control whether comma-separated values in YAML strings are treated as lists or plain strings.
yaml/shared/src/main · high confidence
Added empty platform-specific trait for ZIO Config on Native
A new empty trait \PropertyTypePlatformSpecific\ has been added to the ZIO Config core library to support the Native platform. This change provides a placeholder for platform-specific property type definitions, enabling the library to compile and function correctly on Native targets by satisfying platform-specific interface requirements.
core/native · low confidence
Added empty version-specific support objects for Scala 2.12 and 2.13
Empty \VersionSpecificSupport\ objects were added to the \zio.config\ package for both Scala 2.12 and 2.13. These files currently contain no implementation, serving as placeholders for future version-specific logic.
core/shared/src/main/scala-2.12, core/shared/src/main/scala-2.13 · low confidence
Improved error messages for unsupported derivation types
The library now provides clearer, explicit error messages when attempting to derive configuration descriptors for List, Option, or Either types directly. Instead of generic compilation errors, users will see specific guidance on how to wrap these types in a case class or use manual derivation methods like \Config.listOf\, \.optional\, or \.orElseEither\.
derivation/shared/src/main/scala-2.12 · high confidence
New derivation constraints and configuration annotations
The library now prevents automatic derivation for \List\, \Option\, and \Either\ types, requiring users to explicitly wrap them in a case class or use manual descriptors like \listOf\ or \optional\. Additionally, new annotations are available to customize configuration keys: \discriminator\ for discriminated union types, \kebabCase\ and \snakeCase\ for naming conventions, and \prefix\/\postfix\ for key modification. A \kebabCaseLegacy\ annotation is also added for backward compatibility.
derivation/shared/src/main/scala · high confidence
Optimized tuple derivation for Scala 3 config generation
The Scala 3-specific code generation for deriving configurations has been refactored to reduce the amount of generated code. This is achieved by introducing a new \TupleConversion\ mechanism in \TupleConversion.scala\ that leverages Scala 3's \Mirror\ and \Tuple.fromProductTyped\ for more efficient conversions between products and tuples, alongside a new \VersionSpecificSupport\ object to house version-specific logic.
core/shared/src/main/scala-3.x · high confidence
Test coverage
Added Scala 3-specific test coverage for automatic derivation, defaults, and documentation; Added property-based tests for the XML config provider and parser; Added test coverage for Typesafe HOCON configuration parsing; Added test suite for indexed configuration sequences and documentation generation; Added tests for Refined numeric and string type support; Added tests for YAML configuration reading; Added tests for automatic derivation of discriminated sum types; Added tests for key-format annotations and sealed trait derivation.
Dependencies
Build infrastructure updated to sbt 1.13.0 and Scala 3.9.0
The build system has been upgraded to sbt 1.13.0, and the project now supports Scala 3.9.0 alongside Scala 2.12.21 and 2.13.18. This change introduces Scala 3 compilation support, disables parallel execution for Scala 3 tests, and updates various build plugins including sbt-scalafix, sbt-buildinfo, and sbt-ci-release to their latest versions.
project · high confidence
Migrate CI to zio-sbt-ci plugin and update dependency versions
The build configuration now uses the zio-sbt-ci plugin to generate CI workflows, replacing the previous handwritten setup while preserving the existing test matrix across Java 17/21/25, Scala 2.12/2.13/3, and JS/JVM/Native platforms. This change also updates several key dependencies to their latest versions: ZIO to 2.1.26, zio-aws-ssm to 7.28.29.19, AWS SDK to 1.12.797, Magnolia to 0.17.0, Refined to 0.11.4, and Pureconfig to 0.17.8.
(dependencies) · high confidence
Housekeeping
Repository initialization and tooling setup
The repository has been initialized with essential configuration files, including a Contributor License Agreement (CLA), an Apache 2.0 License, and a Nix flake for reproducible development environments. Development tooling is standardized via \.scalafmt.conf\ (version 3.11.5), \.scalafix.conf\, and \.gitattributes\, while CI automation is configured through \.mergify.yml\ to automatically handle Scala Steward dependency updates. The project also specifies Node.js 20.9.0 via \.nvmrc\ and updates the README to reflect current installation and usage instructions.
(repo-wide) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 62 → 56 (-5.9)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.2) — scores are not directly comparable.
Lenses
- Code Health 75 → 75 (+0.0)
- Architecture 73 → 72 (-1.1)
- Maturity 55 → 54 (-1.2)
- Readiness 65 → 65 (-0.1)
- Security 66 → 49 (-17.0)
- Performance 100 → 100 (+0.0)
Resolved (5)
- Outdated: com.github.pureconfig:pureconfig-core_2.13
- Outdated: dev.zio:zio-aws-ssm_2.13
- Outdated: dev.zio:zio-streams_2.13
- Outdated: dev.zio:zio_2.13
- Outdated: org.tomlj:tomlj
New (1)
- Dependency hygiene PARTLY measured — sbt declarations read, dependency currency not (Maven Central unreachable)
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
zio/zio-config was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 6 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 821b69408daf05cf19a1dc18f37549bda7fc9fee — the exact code this score is about.
- Scored under rubric-2026.11.2 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.3+preprod-410a2463fa58.