---
seo:
    title: "Validating FinSpec"
    description: "Validate FinSpec JSON documents against the FinSpec schema using editor linting, CLI tools and CI/CD pipelines."
llm_context: "Practical guide to validating a .json FinSpec document against schema.json (JSON Schema Draft-07) via VS Code linting, command-line validators and automated CI checks."
category: "guide"
related:
    - "/finspec/guides/json_schema"
    - "/finspec/reference"
    - "/finspec"
---

## Validating FinSpec Documents

FinSpec documents are just JSON, which means you can validate them with any standard [JSON Schema](https://json-schema.org/) 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](https://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](https://validator.hyperjump.io/):** 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`](https://github.com/neilpa/yajsv)                     | Downloadable binary, no runtime needed. Zero language dependencies                      |
| Python   | [`check-jsonschema`](https://check-jsonschema.readthedocs.io/) | Install using `pip install check-jsonschema`. Clear error messages, actively maintained |
| NodeJS   | [`ajv-cli`](https://github.com/ajv-validator/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`](https://pypi.org/project/jsonschema/)                                    | Ensure you have the latest version for 2020-12 support.                       |
| JavaScript/TypeScript | [`ajv`](https://ajv.js.org/)                                                            | The core library used by the CLI tool above.                                  |
| Java                  | [`networknt/json-schema-validator`](https://github.com/networknt/json-schema-validator) |                                                                               |
| Go                    | [`santhosh-tekuri/jsonschema`](https://github.com/santhosh-tekuri/jsonschema)           |                                                                               |
| C#                    | [`JsonSchema.Net`](https://json-everything.net/schema)                                  |                                                                               |
| C++                   | [`Valijson`](https://github.com/tristanpenman/valijson)                                 | Designed to be used _on top_ of other popular JSON parsers such as RapidJSON. |
