Created: 2012-03-23 00:09
Updated: 2017-06-23 18:50
License: mit


Build Status

OmniConfig is a Ruby library that provides flexible configuration for your applications or libraries. The key idea behind OmniConfig is the separation of configuration definition and configuration loading. This allows you to define your available configuration values, and have that configuration loaded from anywhere, such as JSON files, Ruby structures, a remote server (like ZooKeeper), etc.

For documentation, there is a comprehensive user guide available.


Omniconfig is distributed as a gem. Any software that wants to be configured with omniconfig will require this gem:

$ gem install omniconfig


OmniConfig is a schema-based configuration library. This allows OmniConfig to validate structure and types of incoming configuration values. Of course, embracing the dynamic nature of Ruby, it is perfectly possible to accept any values and do decoding yourself, if you wish. However, most applications have a finite set of configuration parameters.

Defining a schema for your configuration is easy:

# This lets us drop the namespace for the types, not necessary but helpful
include OmniConfig::Type

person = OmniConfig.structure({
  "name" => String,
  "age"  => Integer

root = OmniConfig.structure({
  "manager"   => String,
  "employees" =>

The easiest way to show what the above schema looks like is using JSON. Note that if you choose to support JSON as a configuration language, then this actually works!

  "manager": "Mitchell Hashimoto",
  "employees": [
    { "name": "John", "age": "42" },
    { "name": "Tim", "age": "24" },
    { "name": "Amy", "age": "32" }

Once your schema is defined, you need to create an OmniConfig object, tell it of your schema, and assign a set of loaders to it which know how to load actual configuration from specific sources:

config =

This tells OmniConfig for the config instance to accept the structure root (which we defined above), and to load from a set of sources. Note that sources added later will override those set earlier (so any conflicting configuration found when reading Ruby will override that of the JSON, for example).

Finally, load it, and use your new configuration:

settings = config.load

# Use it
puts "The manager is: #{settings["manager"]}"
puts "Employees count: #{settings["employees"].length}"

Amazing! The true power in this approach is that there is a distinct separation between available configuration settings and the loading of these settings, allowing the loading to come from many sources.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more