Skip to content
CAI
Software that uses CAICheck a score

zio/zio-config

56.4

Adequate · 6 November 2026

5k

lines of production code

Scala

primary language

4

measurements over time

CAI band scale
CAI trend line
CAI lens gauges

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.