Sane YAML With JSON Schema

2020-06-11

Most popular CI/CD systems use YAML as input language for their pipelines. Debugging pipelines is always annoying due to long feedback cycles, but I get particularly upset if the reason for failure is malformed YAML.

GitHub Actions syntax error

How do I stay sane?

Lucky for me, there is JSON Schema. More to the point,

Here is what that looks like for GitHub Actions workflows as just one example.

  1. Open your Most Painful YAML and notice a small, innocuous label at the bottom:

    GitHub Actions syntax error

    It is actually a button — click it!

    TipIf you don't see this, check your settings.
  2. Start typing the type of thing at hand and see if a schema is available:

    GitHub Actions syntax error
  3. Visit the Schema Mappings dialog to add custom schemas and fine-tune your configuration:

    GitHub Actions syntax error

    Note how I told IDEA to match all files in .github/workflows to the appropriate schema.

While by no means perfect — especially if the published schema does not quite match what you need, or is written badly — there are some immediate benefits. Wrong indentation after copy-pasting? Highlighted:

GitHub Actions syntax error

Not the most obvious error message — thanks, everything-goes YAML syntax! — but at least we know something is wrong! We even get syntax completion and, if the schema contains it, inline documentation:

GitHub Actions syntax error

Very cool! If anyone ever asks me why they should create schemas for their interface, this here is one very concrete value I will point to.

CautionIn case you hadn't noticed: I do not like YAML. It is a time-sink without end. Whoever decided that whitespace should be part of any formal syntax needs to be …​ given a stern talking-to. And here it's even worse than, say, for Python, since almost any way to indent is valid YAML and means something! But the structure needs to be just right for the consumer to accept it …​
ToolJSON SchemaIntellij IDEAProgramming
Comment & Share on Twitter 

Logging in Go With Zap

Targeted Docker Inspection