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.
.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
.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
(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
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
configu delete --schema "some-schema"