zio-properties: A ZIO alternative to Spring Properties

Posted byrealadrianfilipPosted inUncategorizedTags:, , , , , , ,

EDIT: zio-properties 1.0 is now available on Maven Central
“com.adrianfilip” %% “zio-properties” % “1.0″

I like versatility when configuring application properties.

For instance: In Kubernetes I use environment variables, locally or in a local docker container I may use property files, environment properties, command line arguments, system properties or a mix of any of them.

Also there are many benefits to a simple and easy way of loading properties applicable on multiple use cases.

Versatility and simplicity in this case can be reduced to:

  • multiple sources
  • property resolution order

In order to achieve that I have built a library called zio-properties (on top of zio-config and magnolia) that checks multiple sources and retrieves properties based on a standard resolution order.

With one line of code you can now create a ZLayer that loads your properties from 5 default sources.

where AppProperties is the case class for your properties.

For this example let’s define it as:

The property sources used by zio-properties are (in the order of their resolution):

  1. Command line arguments
  2. System properties
  3. Environment variables
  4. HOCON files
    1. Looks for an application.conf if hoconFile and profile properties are not present in any previous source and application.conf in present in the classpath
    2. if the hoconFile property is present in any previous source – the mentioned file will be used (and profile is ignored for hocon file resolution). Fails if file not found in classpath.
    3. if hoconFile property is not present in any previous source and profile is not present in any previous source – application.conf file will be used if present (does not fail if file not found in classpath)
    4. if profile property is present
      1. and profile.lowercase ==“prod” or  profile.lowercase ==“” then application.conf file will be used if present (does not fail if file not found in classpath) otherwise
      2. application-${profile.lowercase}.conf file will be used if present (does not fail if file not found in classpath) otherwise
  5. Property files
    1. Looks for an application.properties if propertiesFile and profile properties are not present in any previous source and application.properties in present in the classpath
    2. if the propertiesFile property is present in any previous source – the mentioned file will be used (and profile is ignored for properties file resolution). Fails if file not found in classpath.
    3. if propertiesFile property is not present in any previous source and profile is not present in any previous source – application.properties file will be used if present (does not fail if file not found in classpath)
    4. if profile property is present
      1. and profile.lowercase ==“prod” or  profile.lowercase ==“” then application.properties file will be used if present (does not fail if file not found in classpath) otherwise
      2. application-${profile.lowercase}.properties file will be used if present (does not fail if file not found in classpath) otherwise


zio-properties will look in the property sources based on resolution order and will use the value from the first place where it finds it.


For instance (using the above AppProperties) for the scenario where
application.properties: db.port=3306
and Environment variables: db_port=6000
and no mention of the property anywhere else
results in zio-properties using 6000 because Environment variables are ahead of Property files in the resolution order.

How can you use it?

As you can see in a few lines of code you have created your AppProperties and are ready to use it in your application. Also because the AppProperties are provided from a Layer you can specify that as the R in ZIO[R, E, A] to your effects to avoid of passing them as parameters. That looks like this:

You can find the entire zio-properties project (with example and tests) on my Github: https://github.com/adrianfilip/zio-properties.


I recommend you also check out zio-config (@afsalt2, @jdegoes) and magnolia (@propensive).

EDIT: Now it also supports HOCON.

EDIT2: Available now on maven central: “com.adrianfilip” %% “zio-properties” % “1.0″

You can find me on:

Leave a comment