Validating FinSpec Documents

FinSpec documents are just JSON, which means you can validate them with any standard JSON Schema tool. This page walks through several ways to check a .json file against the FinSpec schema (schema.json), from inline editor feedback to automated CI/CD checks.

All examples below assume:

  • You have a local copy of the schema file — e.g. schema/finspec-5.2.schema.json — somewhere in your project or repo. (The schema targets JSON Schema Draft-07.)
  • Your FinSpec document lives alongside it, e.g. my-api.finspec.json.

Pick one approach or layer all of them to give a rock-solid validation layer.

Real-time Linting

VS Code

VS Code has built-in JSON Schema support, so no extension is required. The best way to wire it up is to use workspace settings based on a file or folder name like the example below. This keeps the FinSpec files clean and works for the whole team working on the repo.

json
// .vscode/settings.json
{
    "json.schemas": [
        {
            "fileMatch": ["*.finspec.json", "finspec/**/*.json"],
            "url": "./schema/finspec-5.2.schema.json"
        }
    ]
}

Other IDEs

While VS Code has built-in JSON Schema support, other IDEs may need a bit more help, and so an IDE-agnostic way of making this work is to simply add a $schema key to the top of the file. While this is more portable and should trigger real-time validation in most modern IDEs, it does require that people remember to add this $schema entry for all files to trigger it.

json
{
  "$schema": "./schema/finspec-5.2.schema.json",
  "finspec": "5.2",
  ...
}

Online Validators & Playgrounds

If you prefer to use interactive validators, then check out these free resources:

  • JSONSchema.dev: A modern playground that supports the 2020-12 draft. Paste our schema and your test data to see instant validation results.
  • Hyperjump Validator: One of the most spec-compliant validators available online, perfect for debugging complex $ref issues.

Command-line validation

On-Demand

For ad hoc checks or those who prefer the terminal, a wide variety of standalone, open-source CLI validators are available. Here are just a few; feel free to experiment with others:

Language CLI Tool Notes
Go yajsv Downloadable binary, no runtime needed. Zero language dependencies
Python check-jsonschema Install using pip install check-jsonschema. Clear error messages, actively maintained
NodeJS ajv-cli Very fast, widely used, but can also be quite strict

Any of these can return a non-zero exit code on failure, and so they can be easily integrated into a script as required.

Git pre-commit hook

To save remembering to run the CLI validation for each change, however, an even better approach is to script validation into your git pre-commit hook to ensure it is always run before checking in code.

bash
#!/usr/bin/env bash
# .githooks/pre-commit or ./git/hooks/pre-commit
set -eo pipefail

files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.finspec\.json$' || true)
[ -z "$files" ] && exit 0

for f in $files; do
  echo "Validating $f..."
  yajsv -s schema/finspec-5.2.schema.json "$f"
done

Each developer enables it once per clone:

bash
# Path may be ./git/hooks or .githooks, depending on operating system
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks

Using yajsv here (rather than check-jsonschema) is deliberate: it’s a single static binary, so the hook works even on a machine with no Python installed. If your team already standardises on Python or Node tooling, swap in check-jsonschema or ajv-cli instead — just be aware that this then becomes a hard requirement for anyone running the hook.

CI/CD Pipeline

Once a commit is made, you should add validation to your CI/CD pipeline as the final gate, to catch anything committed with --no-verify, or from contributors who haven’t set up hooks.

GitHub Actions

yaml
# .github/workflows/validate-finspec.yml
name: Validate FinSpec

on:
    pull_request:
    push:
        branches: [main]

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

            - name: Install validator
              run: pip install check-jsonschema

            - name: Validate FinSpec documents
              run: |
                  find . -name "*.finspec.json" -print0 | \
                    xargs -0 -n1 check-jsonschema --schemafile schema/finspec-5.2.schema.json

GitLab CI

yaml
# .gitlab-ci.yml
validate-finspec:
    stage: test
    image: python:3.12-slim
    script:
        - pip install check-jsonschema
        - find . -name "*.finspec.json" -print0 | xargs -0 -n1 check-jsonschema --schemafile schema/finspec-5.2.schema.json
    rules:
        - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
        - if: '$CI_COMMIT_BRANCH == "main"'

Generic (any CI provider)

Because the validation itself is just a CLI call, the underlying step is portable to any CI system (Jenkins, CircleCI, Azure DevOps, Bitbucket Pipelines, etc.) — just run this as a build step:

bash
pip install check-jsonschema
find . -name "*.finspec.json" -print0 | \
  xargs -0 -n1 check-jsonschema --schemafile schema/finspec-5.2.schema.json

This fails the build (non-zero exit) if any file is invalid, and validates every FinSpec file in the repo, not just one.

Open-Source Libraries

A wide variety of JSON schema validation libraries are available online. Here is a curated list to get you started:

Language Library Notes
Python jsonschema Ensure you have the latest version for 2020-12 support.
JavaScript/TypeScript ajv The core library used by the CLI tool above.
Java networknt/json-schema-validator
Go santhosh-tekuri/jsonschema
C# JsonSchema.Net
C++ Valijson Designed to be used on top of other popular JSON parsers such as RapidJSON.