Skip to content

Configuration Formats

Jump to bottom
Shaun Remekie edited this page Jun 30, 2017 · 4 revisions

Qaz supports configuration files written in the following formats:

  • YAML
  • HCL
  • JSON

Which format to use is entirely up to the user, however, there a limitations/disadvantages to each format, making each more suited for particular deployments.

JSON

JSON is self-describing and easy to understand (in small doses). It serves as a configuration format on various projects and fronts many many APIs.

Advantages:

  • Well supported, there are a ton of JSON examples and validation tools online
  • Familiar syntax
  • Able to represent complex data types, Lists, Maps(dictionaries), Strings, Integers, Bool

Disadvantages:

  • Does not support comments
  • Does not support non-String keys (eg: 1: "one")
  • Can become difficult to read/manage in larger more verbose documents

Use Cases:

  • Smaller, non-complex deployment configuration files
  • API config sources, that is, when using AWS Lambda or HTTP(s) APIs as a source for configuration

HCL

HCL stands for Hashicorp Configuration Language and was created to be a best of both worlds configuration language for their projects.

Advantages:

  • Supports comments
  • Familiar & easy to read syntax (even at scale)
  • Easily adapted if you've worked with HashiCorp stuff before

Disadvantages:

  • Not as widely used as JSON/YAML, support may be difficult to come-by beyond the Github project page
  • (@the time of writing) Unable to represent nested Maps, that is, a Map within a Map. HCL instead seems to create a List within the Map.

Use Case:

  • Great for more Array/List oriented configuration files
  • Readability is less affected at scale making HCL a great format for larger configuration files

YAML

YAML is a human readable structured data format, used extensively for configuration files and templates in various projects.

Advantages:

  • Well supported, there are various examples on syntax as well as validation tools available online.
  • Able to represent complex data types, Lists, Maps(dictionaries), Strings, Integers, Bool
  • Supports non-String keys (eg: 123: "one two three")
  • Semi-Readable at scale
  • More forgiving syntax and easy to learn, read and adapt.

Disadvantages:

  • Can become tedious and verbose at scale
  • Encourages more complex data structures which can result in more complex templates

Use Case:

  • Great for all standard projects of any size
  • Projects that require complex data-types and non-String keys
Clone this wiki locally