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
$refissues.
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:
bashpip 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. |