Swiftpack.co - Package - IBM-Swift/Configuration


Build Status macOS Linux Apache 2 codecov


Configuration is a Swift package for managing application configurations. Using Configuration, an application can easily load and merge configuration data from multiple sources and access them from one central configuration store.

Configuration supports configuration keys as paths. That is, a key is a qualified path selector written in the [parent]<separator>[child] syntax. This allows applications to retrieve configuration objects at any level of specificity.

Version Info

The latest release of Configuration (v2.x.x) runs on Swift 4.0 and newer, on both macOS and Ubuntu Linux

API Documentations

Full API documentations for Configuration can be found here.


Via Swift Package Manager

Add Configuration to your Package.swift:

let package = Package(
  name: "<package-name>",
  dependencies: [
    // Swift 4
    .package(url: "https://github.com/IBM-Swift/Configuration.git", .upToNextMajor(from: "2.0.0"))

    // Swift 3
    .Package(url: "https://github.com/IBM-Swift/Configuration.git", majorVersion: 1)


The core of the Configuration package is the ConfigurationManager class. To manage your application's configurations, first create an instance of the ConfigurationManager class.

import Configuration

let manager = ConfigurationManager()

Using the ConfigurationManager instance, you can then load and retrieve configurations:

manager.load(file: "config.json").load(.environmentVariables)
let value = manager["path:to:configuration:value"]

Loading Configuration Data

Configuration has many methods to load configuration data.

NOTE: In all cases, configuration key paths are case sensitive.

From a Raw Any Object:

    "hello": "world",
    "foo": [
        "bar": "baz"

From Command-line Arguments:


To inject configurations via the command-line at runtime, set configuration values when launching the executable, like so:

./myApp --path.to.configuration=value

You can set your preferred argument prefix (default: --) and path separator (default: .) strings when instantiating ConfigurationManager.

From Environment Variables:


Then, to use it in your application, set environment variables like so:


You can set your preferred path separator (default: __) string when instantiating ConfigurationManager.

From a Data Object:

let data = Data(...)
manager.load(data: data)

From a File:

manager.load(file: "/path/to/file")

By default, the file argument is a path relative from the location of the executable (i.e., .build/debug/myApp); if file is an absolute path, then it will be treated as such. You can change the relative-from path using the optional relativeFrom parameter, like so:

// Resolve path against PWD
manager.load(file: "../path/to/file", relativeFrom: .pwd)

// or

// Resolve path against a custom path
manager.load(file: "../path/to/file", relativeFrom: .customPath("/path/to/somewhere/on/file/system"))

NOTE: The following relativeFrom options, .executable (default) and .pwd, will reference different file system locations if the application is ran from inside Xcode than if it were ran from the command-line. You can set a compiler flag, i.e. -DXCODE, in your xcodeproj and use the flag to change your configuration file loading logic.

NOTE: Because BasePath.project depends on the existence of a Package.swift file somewhere in a parent folder of the executable, changing its location using swift build --build-path is not supported

From an URL:

let url = URL(...)
manager.load(url: url)

NOTE: The URL MUST include a scheme, i.e., file://, http://, etc.

From Multiple Sources:

You can chain these methods to load configuration data from multiple sources all at once. If the same configuration key exists in the multiple sources, the one most recently loaded will override the ones loaded earlier. In this simple example,

manager.load(["foo": "bar"]).load(["foo": "baz"])

the value for foo is now baz because ["foo": "baz"] was more recently loaded than ["foo": "bar"]. The same behavior applies to all other load functions.

NOTE: Currently, Configuration only supports JSON and PLIST formats for resources loaded from Data, file, or URL. You can write a custom deserializer to parse additional formats.

Accessing Configuration Data

To get individual configuration values after they have been loaded, use:


The configuration store is represented as a tree, where the path elements in keys are delimited by colons (:). For instance, the key VCAP_SERVICES:cloudantNoSQLDB:0:credentials:host would traverse into VCAP_SERVICES, cloudantNoSQLDB, array index 0, credentials, and then host to grab the value. Here is a JSON example of the structure:

        "cloudantNoSQLDB": [
                "credentials": {
                    "host": <value-goes-here>

The value returned is typed as Any?. Therefore, it's important to cast the value to the type you want to use. For instance:

let stringValue = manager["VCAP_SERVICES:cloudantNoSQLDB:0:credentials:host"] as? String

You can also retrieve configuration objects via partial paths; for example, if you use manager["VCAP_SERVICES:cloudantNoSQLDB:0:credentials"], the result is a dictionary of the key-values in credentials.

To get all configuration values in the configuration store, use


The return value is raw representation of all configuration values currently in the configuration store.


Configuration was inspired by nconf, a popular NodeJS hierarchical configuration manager.


Apache 2.0


Stars: 18
Help us keep the lights on



3.0.0 - Nov 20, 2017


  • Extracts Path Resolution logic to external repository. FileKit

2.0.0 - Nov 2, 2017


  • Full migration to Swift 4, removing backward compatibility for future releases
  • Reverts deprecation of BasePath.project

1.0.3 - Sep 13, 2017

What's New

  • Add support for Swift 4

1.0.2 - Aug 28, 2017

What is new

  • BasePath.project load from file option is now deprecated
  • ~Support Carthage~

1.0.1 - Jul 13, 2017

What is new

  • No longer log at error level
  • Support compilation using Swift 4 snapshots
  • Improve comments/readme/tests