← Back to Quick Start

Validate JSON Syntax and Structure

Parse JSON, detect syntax errors, and validate against JSON Schema — with detailed issue reports including path and severity.

What you'll learn

  • How to validate JSON syntax (is it parseable?) with a single API call
  • How to validate JSON against a JSON Schema for structural correctness
  • How to interpret validation issues with JSON Pointer paths and severity levels
  • How to use validation profiles for reusable schema configurations

Prerequisites

Step 1: Your first call

Validate a well-formed JSON payload:

curl -s -X POST /api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "json": "{\"name\": \"Alice\", \"age\": 30, \"active\": true}",
    "mode": "SYNTAX"
  }' | python3 -m json.tool

Expected response:

{
  "requestId": "d1e2f3a4-b5c6-...",
  "valid": true,
  "mode": "SYNTAX",
  "issueCount": 0,
  "issues": [],
  "processingTimeMs": 2
}

Step 2: Understanding the response

valid Boolean: true if the JSON passed all checks for the requested mode.
mode SYNTAX (parse only), SCHEMA (validate against JSON Schema), or FULL (both).
issues Array of validation issues, each with severity, path (JSON Pointer), message, and category.
issueCount Total number of issues found.

Step 3: Common use cases

Invalid JSON (syntax error)

curl -s -X POST /api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "json": "{\"name\": \"Alice\", \"age\": 30,}",
    "mode": "SYNTAX"
  }'
{
  "requestId": "a2b3c4d5-...",
  "valid": false,
  "mode": "SYNTAX",
  "issueCount": 1,
  "issues": [
    {
      "severity": "ERROR",
      "category": "SYNTAX",
      "path": null,
      "message": "Unexpected character '}' at position 28: trailing comma is not allowed",
      "line": 1,
      "column": 28
    }
  ],
  "processingTimeMs": 1
}

Schema validation

Validate JSON against a JSON Schema (inline):

curl -s -X POST /api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "json": "{\"name\": \"Alice\", \"email\": \"not-an-email\"}",
    "mode": "SCHEMA",
    "schema": {
      "type": "object",
      "required": ["name", "email", "age"],
      "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
      }
    }
  }'
{
  "valid": false,
  "mode": "SCHEMA",
  "issueCount": 2,
  "issues": [
    {
      "severity": "ERROR",
      "category": "SCHEMA",
      "path": "/email",
      "message": "\"not-an-email\" does not match format \"email\""
    },
    {
      "severity": "ERROR",
      "category": "SCHEMA",
      "path": "",
      "message": "Required property \"age\" is missing"
    }
  ],
  "processingTimeMs": 4
}

Using validation profiles

If you have pre-configured profiles on the server, reference them by name:

curl -s -X POST /api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "json": "{\"event\": \"click\", \"timestamp\": \"2026-03-26T10:00:00Z\"}",
    "mode": "SCHEMA",
    "profileName": "analytics-event"
  }'

List available profiles

curl -s /api/v1/validate/profiles \
  -H "X-API-Key: YOUR_API_KEY"
{
  "profiles": ["analytics-event", "user-registration", "webhook-payload"]
}

Step 4: Handling errors

Profile not found

curl -s -X POST /api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"json": "{}", "mode": "SCHEMA", "profileName": "nonexistent"}'
{
  "error": "PROFILE_NOT_FOUND",
  "message": "Validation profile 'nonexistent' does not exist",
  "status": 404
}

Missing JSON payload

{
  "error": "VALIDATION_ERROR",
  "message": "json: must not be blank",
  "status": 400
}

Rate limiting

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Retry after 1 second."
}

Step 5: Integration tips

Python webhook validator

import requests
import json

API_BASE = ""
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

WEBHOOK_SCHEMA = {
    "type": "object",
    "required": ["event", "timestamp", "data"],
    "properties": {
        "event": {"type": "string", "enum": ["created", "updated", "deleted"]},
        "timestamp": {"type": "string", "format": "date-time"},
        "data": {"type": "object"}
    }
}

def validate_webhook(payload_str):
    """Validate an incoming webhook payload against our schema."""
    resp = requests.post(
        f"{API_BASE}/api/v1/validate",
        json={
            "json": payload_str,
            "mode": "SCHEMA",
            "schema": WEBHOOK_SCHEMA
        },
        headers=HEADERS, verify=False
    )
    resp.raise_for_status()
    result = resp.json()

    if not result["valid"]:
        errors = [f"  {i['path']}: {i['message']}" for i in result["issues"]]
        raise ValueError(f"Invalid webhook:\n" + "\n".join(errors))
    return json.loads(payload_str)

# Usage
try:
    data = validate_webhook('{"event": "created", "timestamp": "2026-03-26T10:00:00Z", "data": {"id": 1}}')
    print(f"Valid webhook: {data['event']}")
except ValueError as e:
    print(e)

CI/CD configuration validation

Add JSON validation to your CI pipeline to catch configuration errors before deployment:

# In your CI script
CONFIG=$(cat config.json)
RESULT=$(curl -s -X POST /api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -d "{\"json\": $(echo "$CONFIG" | jq -Rs .), \"mode\": \"SCHEMA\", \"profileName\": \"app-config\"}")

if [ "$(echo $RESULT | jq -r .valid)" = "false" ]; then
  echo "Config validation failed:"
  echo $RESULT | jq '.issues[] | "  \(.path): \(.message)"'
  exit 1
fi

Next steps