Styleguide/toolchain to use for YAML linting/repairing

[sujaypatil96]

All LinkML schemas are specified/authored in YAML, which like other (programming, formatting, etc.) languages out there has it's own styleguide/best practices that need to/can be followed while creating files in that format.

When this issue was raised as a discussion item at a past LinkML developers meeting, the team came up with four solutions that can be used --

• yamllint (linting)
• prettier (formatting)
• yq (formatting)
• yamlfmt (formatting -- recommended by Sam Willison)

We need to evaluate the pros and cons of each of the above tools and devise a standard workflow for linting (and possibly repairing) YAML files.

[sujaypatil96]

Once the workflow has been standardized, it can be added to the BBOP best practices guide: https://berkeleybop.github.io/best_practice/ and also the linkml-project-cookiecutter: https://github.com/linkml/linkml-project-cookiecutter

[sujaypatil96]

This is how mixs is trying to enforce YAML linting: GenomicsStandardsConsortium/mixs#808

[twhetzel]

yamllint looks like a good option for functionality and ease of use.

[amc-corey-cox]

I like prettier but only from the perspective that I have used it before and it is fairly straightforward to incorporate it into our current workflow.

It's strength and weakness in this context is that it is configurable, i.e. you can turn on and off different rules. In the context of a style-guide and best-practice this actually makes it a bit more complex because we would also need to specify which rules, if any, we want to allow turning off. However, this can be quite beneficial for certain projects that have YAML styles that have a specific rule or two they want to operate differently.

One positive that I strongly recommend in any of our solutions is something that allows per-line disabling of linting rules. Prettier has this feature and it is rather nice to just note why your skipping a rule once in a while; it often results in cleaner code.