Table of Contents
YAML
Best practices
YAML specifications suffer from implicit typing decisions (src), e.g. Norway country code "NO" is parsed as False, "3.5.3" parsed as string and "3.5" as float. Many other issues with implicits found here.
To avoid these problems, with some inspiration from yaml.info and home-assistant.io:
- Always use 2 spaces for indentation, no tabs
- Avoid the use of 'yes' and 'no' (these are mapped to True and False)
- Lists should be indented, and should use flow style if short or nested in another list
- Mappings should not use flow style
- Nulls should be implicitly marked, avoiding '~' and 'null'
- Strings should always be quoted, and use double-quotes unless control sequences are to be avoided
- Use no chomping operators '|' and '>' (folded) instead of '\n', and strip '|-' and '>-' to remove trailing newline
example: indented: value: true dicefaces: - [1, 2, 3] - [4, 5, 6] thisisnull: thisisstring: "3.4" multilinestring: >- I am a multiple line string that is folded. New paragraph.
On TOML
TOML is official integrated into Python, with the pyproject.toml shebang and all. This format is the easiest to read when nesting is low. But the structure becomes nigh-unreadable with nesting:
A likely often quoted comment on TOML, by PyTOML author when inquired about integrating his library into pip:
TOML is a bad file format. It looks good at first glance, and for really really trivial things it is probably good. But once I started using it and the configuration schema became more complex, I found the syntax ugly and hard to read... I personally abandoned TOML and as such, I'm not planning on adding any new features...
- avakar commented on May 9, 2016
Caveat being, configuration files indeed vary quite wildly, so pick your poison when it comes to which configuration syntax one chooses. YAML (without the fancy features) and TOML are good candidates. JSON is iffy due to the strict syntax (the commas plague me), so CSON for CoffeeScript is likely a better alternative if tooling is present.