Workflows gets an updated JSON Schema

If you use Workflows, you’ve been crafting your Workflows definitions in YAML (or JSON). You’re probably painfully aware of the limited support you get in your IDE with syntax validation or auto-completion with these YAML definitions. This was due to Workflow's schema being out of date, as I covered in my previous post last year.

I’m happy to report that our team recently updated the Workflows schema with the latest syntax. With a new schema, you get a much improved syntax validation and auto-completion of Workflows definition files in your favorite IDE. 

Let’s take a look at the details. 

Workflows schema

JSON Schema Store is a popular repository for JSON schemas. Various editors and IDEs have direct support for schemas hosted on SchemaStore.org. Workflows also has its schema hosted on Schema Store:

• Hosted: https://json.schemastore.org/workflows.json

• Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/workflows.json

This schema has recently been updated with the newest syntax of Workflows such as parallel, for, try, except, and more. 

A schema is only useful if you use it to validate your configuration files. Let’s take a look at how to take advantage of the schema in Visual Studio Code (VS Code) and IntelliJ.

Using Workflows schema in VS Code

You can use the Workflows schema in a few different ways in VS Code, depending on your preferred setup.

If you prefer to use pure VS Code, you can make it use JSON schemas to understand the shape of JSON files with settings explained here. I won’t go into details on how to set this up, as I prefer using extensions for more support. 

If you’re already using Cloud Code for VS Code for Google Cloud, you already have JSON Schema Store support out of the box. There’s no special setup or settings to figure out . All you need is to create a workflows.yaml file. As you start typing your workflow definition, you can hit Control + Space (on Mac OS) to get auto-completion suggestions and main is coming from the Workflows Schema:

Note: Make sure the workflows.yaml file is in a workspace or a folder to get the schema validation. 

Another option is to install the YAML Language Support extension by Red Hat. This extension not only adds YAML support to Visual Studio Code, it also looks to JSON Schema Store to validate the YAML files. Once you have the extension installed, create a workflows.yaml file and you start seeing a link to Workflows schema at the top:

You can also click on the schema to see the full schema in Visual Studio Code:

Using Workflows schema in IntelliJ

IntelliJ is another IDE that has pretty good JSON Schema support. You can again use Cloud Code for IntelliJ to get out of the box support for JSON Schema but if you prefer to use pure IntelliJ, go to Preferences and add the Workflows Schema with its URL and a file pattern:

Now, IntelliJ will interpret any file with *workflows.yaml pattern as a Workflows file.  As an example, here’s a my-workflows.yaml file that gets auto-complete help:

Improvements in syntax validation and auto-completion

Once you have your workflow definition validated in your IDE with the schema, you get pretty good syntax validation and auto-completion support.  

For example, you can see valid values for a call:

You get warnings, if you mistype something:

Or if you forgot a required property:

You get inline documentation:

You get minimum, maximum and duplicate checking in arrays:

Getting workflow definitions right is not easy but you can now get pretty good help from your IDE with the JSON Schema support. Try editing our Workflows samples in our documentation and see if the new and improved JSON Schema helps. If you run into issues with the schema, open issues in our workflows-samples repository. As always, feel free to reach out to me on Twitter @meteatamel for any questions or feedback.