How to document a yaml spec?

Hi everyone,

​

I've written an internal python package for my company to use, and I want to make sure the documentation is high-quality. Part of the package uses a config file (yaml). The config file can have many different options and structure.

I'm wondering if anyone has any great examples for how to document .yaml file structures so users can understand better how to formulate a valid yaml config for the given piece of software.

For example, if the yaml file is required to have a top-level my_key key:

--- my_key: 

How do I document this so the user knows my_key is required? Further, if my_key can take one of two valid options (e.g. my_val_1 or my_val_2) , how do we document that so the user knows?

--- my_key: my_val_1 | my_val_2 

These are just examples, of course. I'm looking for a general guide on how to document such constraints.

Any info you can provide would be great! Thanks a lot