Validate JSON Resume from GitHub Actions

JSON resume is an open standard for machine (and human) readable CVs. It lets you represent your CV in the JSON format inside a .json file, and provides a fairly complete schema for validating its content. This makes it easy for you to focus on the contents of your CV instead of worrying about formatting. Additionally, putting your CV in a plaintext file lends itself well to version control (eg. git).

In this guide, we'll describe how you can validate the contents of your CV file (assumed in this guide to be cv.json) against the JSON resume schema, and enable continuous integration for this validation in Github Actions.

Prerequisites

This guide assumes that your CV is checked in to a Git repository that is hosted on Github. The name of the CV file generally does not matter; for the remainder of this article we'll assume the file name to be cv.json.

Workflow on Local Development

On your local machine, the validation can be done using the txtcv CLI. The first step is to install the CLI via Homebrew.

$ brew install txtcv/tap/txtcv

Once brew is done installing the CLI, you can validate any file using the validate command.

$ txtcv validate --filename cv.json
cv.json is valid

If the contents of the file are valid, the CLI will print out a message accordingly and exit with a status code of 0. If the file contains an errors, the CLI will tell you exactly what is wrong.

Workflow on Github Actions

The workflow on Github Actions is very similar to the one on the local machine.

We need to instruct Github Actions to install the CLI using brew and then run the CLI's validate command. Luckily, Homebrew is available on the runner machines that Github hosts, which makes the whole workflow definition even more concise.

Here's a sample workflow definition that you can copy and paste:

name: Validate CV

on:
  push:
    branches:
      - main

jobs:
  validate:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install txtcv CLI
        run: brew install txtcv/tap/txtcv

      - name: Validate JSON Resume
        run: txtcv validate --filename cv.json

Alternatively, we've provided a public workflow definition under https://github.com/txtcv/actions-validate for validating CV files, that performs the same steps as the ones shown in the previous YAML file. The advantage is that your workflow will have less steps. Here's a sample workflow definition using the action available from the txtcv/actions-validate repository:

name: Validate CV

on:
  push:
    branches:
      - main

jobs:
  validate:
    uses: txtcv/actions-validate@main
    with:
      cv_path: cv.json

As mentioned earlier, txtcv validate exits non-zero on schema errors, in which case this workflow definition would make the CI red. Feel free to adjust the workflow definition as per your specific requirements.

Conclusion

In the sections above, we described a fast and lightweight way to validate JSON resume backed CV files, both in local development as well as in Github Actions, using the txtcv CLI. We hope that this guide was helpful!