Configu Schemas

Configu's schemas are declarations of keys that your code needs to function properly. With Configu, keys can be described with human-friendly annotations and have default values; our innovative .cfgu.json format, allows a simple approach to defining a configuration schema with type safety, human-friendly annotations, powerful patterns and templates, and more.

The .cfgu.json format is represented as-code, it's very easy for humans to understand and it is safe to be stored on your source-control alongside with the code (due to Configu's concept the .cfgu.json will never contain a sensitive value).

Creating A Schema

To create a schema, a file with a .cfgu.json extension needs to be created to store the details of your configuration schema in JSON format. The simplest way to do this is to run:

configu init --name some-schema

... somewhere in your source repository where it can be tracked. You should track these files like any other code. You can create as many .cfgu.json files as you need, and we encourage you to use Configu for any tool that exists in your development workflow - even ad-hoc build scripts.

To create a new configuration with a small demonstration schema, run configu init --examples which will give you an overview of how types, defaults, notes and templates work together.

Changing A Schema

You can add as many keys of any type as you wish to your configuration as your application evolves. You should treat your .cfgu.json files as the source of truth for your configuration schemas, and use your version control to manage versions and changes as they're coupled to your applications.

Ordinary maintenance tasks are changing the default values, notes, templates and patterns associated with your schema, which is easy to accomplish by editing the associated .cfgu.json file as needed and letting it go through your existing review / PR process.

Once you want to initialize values and create a set for it, you can use configu upsert (Read more on how to manage values).

Our IDE plugins provide very convenient completion and lookup to make this process as simple as possible. (Read more about our IDE plugins)

Renaming & Deprecation

If you need to rename a schema key, you can do this, just be aware that changing the name is actually two operations:

  • The key (as we know it) is deprecated
  • A new key with the new name or type is then added

Deprecation is a sort of 'soft' delete - we remove the configuration key from Configu's view when filling sets, but we keep a reference to it in case of rollback. Users with Administration access can prune deprecated keys as needed.

Deleting A Schema

warning

Be sure about deleting a schema!

Note that unlike configuration keys, schemas themselves are hard-deleted, not deprecated, so please be sure that's what you want to do. They can be re-created by restoring them in your repository, and upserting them again in the event that you make a mistake.

You should favor having a team admin periodically prune deprecated keys from schemas instead of re-creating them; you really only want to delete a schema if it won't be needed in the future.

You can delete schema using the delete command

configu delete --schema "some-schema"