How to Validate JSON: Methods, Tools & Best Practices

// JavaScript — JSON.parse with error location
function validateJsonSyntax(text: string): { valid: boolean; error?: string } {
  try {
    JSON.parse(text)
    return { valid: true }
  } catch (e) {
    // JSON.parse errors include position info in modern engines
    return {
      valid: false,
      error: (e as SyntaxError).message,
      // e.g. "Unexpected token ',' at position 42"
    }
  }
}

// Python — json.loads with line/column position
import json

def validate_json_syntax(text: str) -> tuple[bool, str | None]:
    try:
        json.loads(text)
        return True, None
    except json.JSONDecodeError as e:
        # JSONDecodeError includes line, col, and pos attributes
        return False, f"Line {e.lineno}, col {e.colno}: {e.msg}"

# CLI — jq for scripts
# jq . file.json > /dev/null && echo "Valid" || echo "Invalid"

# CLI — Python one-liner
# python3 -m json.tool file.json > /dev/null && echo "Valid"

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api.example.com/schemas/user.json",
  "type": "object",
  "title": "User",
  "description": "User account object returned by /users/{id}",
  "required": ["id", "email", "createdAt", "role"],
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID v4 user identifier"
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 254
    },
    "displayName": {
      "type": ["string", "null"],
      "minLength": 1,
      "maxLength": 100
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 datetime"
    },
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"],
      "description": "Access control role"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "tags": {
      "type": "array",
      "items": { "type": "string", "maxLength": 50 },
      "uniqueItems": true,
      "maxItems": 20
    },
    "address": {
      "type": "object",
      "required": ["country"],
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" },
        "country": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "description": "ISO 3166-1 alpha-2 country code"
        }
      }
    }
  }
}

import Ajv, { type JSONSchemaType } from 'ajv'
import addFormats from 'ajv-formats'

const ajv = new Ajv({
  allErrors: true,       // collect all errors, not just the first
  strict: true,          // throw on unknown keywords (catches schema typos)
  coerceTypes: false,    // NEVER set to true in APIs — silently changes input data
})
addFormats(ajv)          // adds format: "email", "date-time", "uri", "uuid", etc.

// Define TypeScript interface and JSON Schema together
interface User {
  id: string
  email: string
  role: 'admin' | 'editor' | 'viewer'
  age?: number
}

const userSchema: JSONSchemaType<User> = {
  type: 'object',
  properties: {
    id: { type: 'string', format: 'uuid' },
    email: { type: 'string', format: 'email' },
    role: { type: 'string', enum: ['admin', 'editor', 'viewer'] },
    age: { type: 'number', nullable: true, minimum: 0, maximum: 150 },
  },
  required: ['id', 'email', 'role'],
  additionalProperties: false,
}

// Compile once at startup — reuse the validate function for all requests
const validateUser = ajv.compile(userSchema)

// In your Express/Fastify route handler
function handleUserCreate(body: unknown): User {
  if (!validateUser(body)) {
    const errors = validateUser.errors!.map(e =>
      `${e.instancePath || '(root)'}: ${e.message}`
    )
    throw new ValidationError('Invalid user payload', errors)
  }
  // body is now typed as User — TypeScript knows the shape
  return body
}

// Example error output (allErrors: true):
// ["/email: must match format "email"",
//  "/role: must be equal to one of the allowed values",
//  "/id: must match format "uuid""]

const ajv = new Ajv({ allErrors: true })
addFormats(ajv)

// Define reusable schema components
ajv.addSchema({
  $id: 'https://api.example.com/schemas/address.json',
  type: 'object',
  properties: {
    street: { type: 'string' },
    city: { type: 'string' },
    country: { type: 'string', pattern: '^[A-Z]{2}$' },
    postalCode: { type: 'string' },
  },
  required: ['city', 'country'],
})

// Reference in another schema
const orderSchema = {
  type: 'object',
  properties: {
    id: { type: 'string' },
    shippingAddress: { $ref: 'https://api.example.com/schemas/address.json' },
    billingAddress:  { $ref: 'https://api.example.com/schemas/address.json' },
  },
  required: ['id', 'shippingAddress'],
}

const validateOrder = ajv.compile(orderSchema)

import { z } from 'zod'

// Define schema — also serves as the TypeScript type definition
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email().max(254),
  displayName: z.string().min(1).max(100).nullable().optional(),
  role: z.enum(['admin', 'editor', 'viewer']),
  age: z.number().int().min(0).max(150).optional(),
  createdAt: z.string().datetime(),
  tags: z.array(z.string().max(50)).max(20).default([]),
  address: z.object({
    street: z.string().optional(),
    city: z.string(),
    country: z.string().regex(/^[A-Z]{2}$/, 'Must be ISO 3166-1 alpha-2'),
  }).optional(),
})

// Infer the TypeScript type from the schema — no duplication
type User = z.infer<typeof UserSchema>
// type User = {
//   id: string;
//   email: string;
//   displayName?: string | null;
//   role: "admin" | "editor" | "viewer";
//   age?: number;
//   ...
// }

// Validation — throws ZodError with full path on failure
function validateAndParseUser(input: unknown): User {
  return UserSchema.parse(input)
  // Throws: ZodError with array of issues, each with path and message
}

// Safe parse — returns success/error result instead of throwing
function safeValidate(input: unknown) {
  const result = UserSchema.safeParse(input)
  if (!result.success) {
    const errors = result.error.issues.map(i =>
      `${i.path.join('.')}: ${i.message}`
    )
    return { valid: false, errors }
  }
  return { valid: true, data: result.data }
}

// Partial schemas for PATCH endpoints
const UserPatchSchema = UserSchema.partial()
// All fields become optional — correct for PATCH

// Pick subset for response shapes
const UserPublicSchema = UserSchema.pick({ id: true, displayName: true, role: true })
type UserPublic = z.infer<typeof UserPublicSchema>

import json
import jsonschema
from jsonschema import validate, ValidationError, Draft202012Validator

# Define the schema (JSON Schema draft 2020-12)
USER_SCHEMA = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "required": ["id", "email", "role"],
    "additionalProperties": False,
    "properties": {
        "id": {"type": "string", "format": "uuid"},
        "email": {"type": "string", "format": "email", "maxLength": 254},
        "role": {"type": "string", "enum": ["admin", "editor", "viewer"]},
        "age": {"type": "integer", "minimum": 0, "maximum": 150},
    },
}

def validate_user(data: dict) -> list[str]:
    """Returns list of validation errors (empty list = valid)."""
    validator = Draft202012Validator(USER_SCHEMA)
    errors = sorted(validator.iter_errors(data), key=lambda e: e.path)
    return [
        f"{'.' .join(str(p) for p in e.absolute_path) or '(root)'}: {e.message}"
        for e in errors
    ]

# Usage
user_json = '{"id": "not-a-uuid", "email": "invalid", "role": "superuser"}'
data = json.loads(user_json)
errors = validate_user(data)
# [
#   "(root): Additional properties are not allowed",
#   "email: 'invalid' is not a 'email'",
#   "id: 'not-a-uuid' is not a 'uuid'",
#   "role: 'superuser' is not one of ['admin', 'editor', 'viewer']"
# ]

# ── fastjsonschema: 3-20x faster for high-frequency validation ──
import fastjsonschema

# Compile schema once at startup
validate_user_fast = fastjsonschema.compile(USER_SCHEMA)

# Validate (raises fastjsonschema.JsonSchemaValueException on failure)
try:
    validate_user_fast(data)
except fastjsonschema.JsonSchemaValueException as e:
    print(e.message)  # first error only (unlike jsonschema.iter_errors)

import express from 'express'
import Ajv from 'ajv'
import addFormats from 'ajv-formats'
import type { JSONSchemaType } from 'ajv'

const ajv = new Ajv({ allErrors: true })
addFormats(ajv)

// Generic validation middleware factory
function validateBody<T>(schema: JSONSchemaType<T>) {
  const validate = ajv.compile(schema)

  return (req: express.Request, res: express.Response, next: express.NextFunction) => {
    if (!validate(req.body)) {
      return res.status(400).json({
        error: 'Validation failed',
        details: validate.errors!.map(e => ({
          field: e.instancePath || '(root)',
          message: e.message,
        })),
      })
    }
    next()
  }
}

// Usage
interface CreateUserBody {
  email: string
  role: 'admin' | 'editor' | 'viewer'
}

const createUserSchema: JSONSchemaType<CreateUserBody> = {
  type: 'object',
  required: ['email', 'role'],
  properties: {
    email: { type: 'string', format: 'email' },
    role: { type: 'string', enum: ['admin', 'editor', 'viewer'] },
  },
  additionalProperties: false,
}

app.post('/users', validateBody(createUserSchema), (req, res) => {
  // req.body is validated — safe to use
  const { email, role } = req.body as CreateUserBody
  // ...
})

# .github/workflows/validate-json.yml
name: Validate JSON

on:
  pull_request:
    paths: ['**/*.json', '!node_modules/**']

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

      - name: Validate JSON syntax (all .json files)
        run: |
          find . -name "*.json"             -not -path "*/node_modules/*"             -not -path "*/.git/*"             -print0 | xargs -0 -I{} sh -c             'python3 -m json.tool {} > /dev/null && echo "OK: {}" || (echo "FAIL: {}" && exit 1)'

      - name: Validate package.json structure with AJV
        run: npx ajv validate -s .schemas/package-schema.json -d package.json

      - name: Validate API response fixtures
        run: |
          for fixture in tests/fixtures/*.json; do
            npx ajv validate -s schemas/api-response.json -d "$fixture"
          done