GitHub Actions for Automated JSON Formatting and Validation

If you want GitHub to block broken or badly formatted JSON before merge, the best default is a small workflow that runs on pull requests, watches only JSON-related files, and fails fast when a file is malformed or does not match your formatting rules. That gives contributors immediate feedback and keeps bad JSON out of main.

The important distinction is that "JSON validation" can mean three different things: syntax validation, formatting enforcement, and schema validation. Most repositories need the first two. Repositories with machine-read configuration or content files often need the third as well.

What To Automate

• Syntax validation: catches broken commas, quotes, or trailing characters. A formatter such as Prettier will fail on invalid JSON, so many teams get this for free.
• Formatting enforcement: keeps indentation, spacing, and line wrapping consistent so reviews focus on content instead of whitespace noise.
• Schema validation: checks required keys, value types, enums, and other structural rules that a parser or formatter does not understand.

If you only add one workflow, start with formatting plus parse validation. That covers the common search intent behind "JSON validation in GitHub Actions" without adding much maintenance overhead.

Recommended Baseline Workflow

In 2026, the cleanest default is still to keep Prettier in your repository, run it in check mode on pull requests, and scope the workflow with paths so it only runs when JSON-related files change. Older jsonlint plus diff pipelines can work, but they are usually more brittle than a single formatter check.

name: JSON checks

on:
  pull_request:
    branches: [main]
    paths:
      - "**/*.json"
      - ".prettierrc*"
      - ".prettierignore"
      - "package.json"
      - "package-lock.json"
  push:
    branches: [main]
    paths:
      - "**/*.json"
      - ".prettierrc*"
      - ".prettierignore"
      - "package.json"
      - "package-lock.json"

permissions:
  contents: read

jobs:
  json-check:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Check JSON formatting and syntax
        run: npx prettier --check "**/*.json"

This assumes Prettier is already in devDependencies. In CI, prettier --check gives you both signals most teams want: invalid JSON fails the step and valid JSON that does not match your formatting rules also fails . A clean pull request passes without bot commits or write access .

Pin the Node major version your repository already uses. The 24 above is only an example of a current major. If your repo is pinned to a different version, or uses pnpm or yarn, match that instead of copying the sample blindly.

When Syntax Validation Is Not Enough

A formatter only tells you whether the JSON parses and whether it is styled correctly. It does not tell you whether your file has the keys or value types your application expects. If your repository depends on config files, content bundles, or deployment manifests, add a schema validation step after installation.

- name: Validate JSON against a schema
  run: |
    npx ajv-cli validate       -s schema/config.schema.json       -d "config/**/*.json"       --all-errors

This is what catches missing keys, invalid enum values, or the wrong data type for a field. Use it when "valid JSON" is not the same thing as "usable JSON" in your application.

Pull Request Enforcement and Auto-Fix

For most teams, check-only workflows are the better default. They work cleanly with branch protection, keep permissions minimal, and make the contributor fix the file in the same branch that introduced the change. If the check fails on a pull request, require that status check before merge.

If you want the action to rewrite files and commit them back, switch to prettier --write, grant contents: write, and commit only when the working tree changed. Keep that pattern for trusted branches or internal repositories. For fork-based pull requests, read-only validation is usually simpler and safer.

Common Failures and Fixes

• The workflow never starts: If you use both branch filters and paths filters, both conditions must match. A JSON-only workflow will not run when a pull request changes only Markdown or TypeScript.
• Prettier says a file is wrong even though it parses: That is expected. Parsing and formatting are different checks. Run prettier --write locally, then commit the formatted result.
• You want reproducible CI: Keep Prettier pinned in devDependencies and commit your lockfile. That avoids downloading a floating formatter version on every run.
• Your cache behavior changed after updating setup-node: actions/setup-node@v6 can automatically enable npm caching when your package.json declares npm as the package manager. If you do not want that behavior, set package-manager-cache: false.
• You only want to validate part of the repo: Narrow both the workflow paths filter and the CLI glob, for example config/**/*.json or content/**/*.json.
• The repo contains generated JSON: Exclude generated directories with .prettierignore so CI does not fail on files no human is expected to edit.

Best Practices

• Run the job on pull requests and on pushes to your protected branch so bad JSON cannot slip through.
• Use read-only permissions unless the workflow truly needs to push changes back to the repository.
• Prefer one obvious formatter workflow over a chain of ad hoc shell commands. It is easier for contributors to debug.
• Add schema validation only where structure matters. Not every JSON file deserves the overhead of maintaining a schema.

Conclusion

If your goal is reliable JSON validation in GitHub Actions, start with a small Prettier check scoped to JSON files, then add schema validation only for structured config or content. That setup is simple, current, and easy to enforce with pull request status checks.