Documentation

Overview

JSON Guardian is a high-performance REST API that solves critical problems in AI applications: LLMs frequently produce malformed or schema-violating JSON, causing production failures. This service provides:

• Validate - Verify JSON against schemas (JSON Schema Draft 7)
• Repair - Automatically fix common JSON syntax errors
• Enforce - Schema enforcement with smart type coercion
• Extract - Strip JSON from LLM prose/markdown output
• Partial - Complete streaming JSON for real-time UI
• Batch - Process up to 100 items with any operation

Base URL: https://api.jsonguardian.com

Quick Start

1. Health check

curl https://api.jsonguardian.com/health
# Output: OK

2. Validate JSON

curl -X POST https://api.jsonguardian.com/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"}
      },
      "required": ["name", "age"]
    },
    "data": "{\"name\": \"John\", \"age\": 30}"
  }'

3. Repair broken JSON

curl -X POST https://api.jsonguardian.com/api/v1/repair \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"data": "{\"name\": \"John\", \"age\": 30,}"}'

API Endpoints

Authentication

All API calls (except /health) require an API key in the header:

X-API-Key: your-api-key

Get your API key from the dashboard after signing up.

Validate

Check if JSON is valid and conforms to a JSON Schema (Draft 7).

POST /api/v1/validate
{
  "schema": { "type": "object", "required": ["name"] },
  "data": "{\"name\": \"John\"}"
}

// Response
{ "valid": true, "errors": [], "parsed_data": {"name": "John"} }

Repair

Fix common JSON syntax errors automatically.

What gets repaired

• Trailing commas: {"a": 1,} → {"a": 1}
• Missing closing braces
• Single quotes: {'a': 'b'} → {"a": "b"}
• Unquoted keys: {name: "John"} → {"name": "John"}
• Escape sequence issues

Enforce

Repair JSON + enforce schema with smart type coercion.

Type Coercion Examples

• "twenty-five" → 25 (integer fields)
• "yes"/"no" → true/false (boolean)
• "25 years old" → 25

POST /api/v1/enforce
{
  "schema": { "type": "object", "properties": { "age": {"type": "integer"} } },
  "data": "{\"age\": \"twenty-five\"}"
}

// Response
{ "success": true, "enforced": {"age": 25}, "changes_made": ["Coerced age..."] }

Extract

Strip JSON from LLM prose/markdown. Perfect for messy AI responses.

POST /api/v1/extract
{
  "data": "Sure! Here is the data: {\"name\": \"John\"} Hope that helps!"
}

// Response
{
  "success": true,
  "extracted": "{\"name\": \"John\"}",
  "extracted_data": {"name": "John"},
  "stripped": { "before": "Sure! Here is the data: ", "after": " Hope that helps!" }
}

Partial

Complete streaming/partial JSON. Essential for real-time UI during LLM streaming.

POST /api/v1/partial
{
  "data": "{\"user\": {\"name\": \"Joh"
}

// Response
{
  "success": true,
  "completed": "{\"user\": {\"name\": \"Joh\"}}",
  "completed_data": {"user": {"name": "Joh"}},
  "additions": ["\"", "}", "}"]
}

Batch

Process up to 100 items with ANY operation in a single request.

Supported Operations

• validate - Validate against schema
• repair - Fix malformed JSON
• enforce - Schema with type coercion
• extract - Extract from prose
• partial - Complete streaming JSON

POST /api/v1/batch
{
  "operation": "repair",
  "items": [
    {"data": "{\"a\": 1,}"},
    {"data": "{'b': 2}"}
  ]
}

// Response
{ "total": 2, "succeeded": 2, "failed": 0, "tokens_used": 2, "results": [...] }

Error Handling

API Key Tiers

Available tiers: free (10k/mo), starter (100k/mo), pro (1M/mo). Create keys from your dashboard or via the API.

TypeScript SDK

Install the official TypeScript/JavaScript client for Node.js 18+.

npm install @json-guardian/client

Quick example

import { JsonGuardian } from '@json-guardian/client';

const client = new JsonGuardian({ apiKey: process.env.JSON_GUARDIAN_API_KEY });

// Validate
const v = await client.validate({
  schema: { type: 'object', required: ['name'] },
  data: '{"name": "Alice"}',
});
console.log(v.valid); // true

// Repair
const r = await client.repair({ data: '{"a": 1,}' });
console.log(r.repaired_data); // { a: 1 }

// Enforce (type coercion)
const e = await client.enforce({
  schema: { type: 'object', properties: { age: { type: 'number' } } },
  data: '{"age": "twenty-five"}',
});
console.log(e.enforced); // { age: 25 }

// Extract JSON from LLM prose
const x = await client.extract({ data: 'Here: {"k":1} done' });
console.log(x.extracted_data); // { k: 1 }

// Complete partial/streaming JSON
const p = await client.partial({ data: '{"user": {"name": "Joh' });
console.log(p.completed_data); // { user: { name: "Joh" } }

// Batch (up to 100 items)
const b = await client.batch({
  operation: 'repair',
  items: [{ data: '{"a":1,}' }, { data: "{'b':2}" }],
});
console.log(b.succeeded); // 2

All methods

Full docs: npm package README

Python SDK

Install the official Python client (Python 3.8+).

pip install json-guardian

Quick example

from json_guardian import JsonGuardian
import os

client = JsonGuardian(api_key=os.getenv("JSON_GUARDIAN_API_KEY"))

# Validate
result = client.validate(
    schema={"type": "object", "required": ["name"]},
    data='{"name": "Alice"}',
)
print(result["valid"])  # True

# Repair
result = client.repair(data='{"a": 1,}')
print(result["repaired_data"])  # {"a": 1}

# Enforce
result = client.enforce(
    schema={"type": "object", "properties": {"age": {"type": "number"}}},
    data='{"age": "twenty-five"}',
)
print(result["enforced"])  # {"age": 25}

# Extract, Partial, Batch — same pattern
result = client.extract(data='Here: {"k":1} done')
result = client.partial(data='{"user": {"name": "Joh')
result = client.batch(operation="repair", items=[{"data": '{"a":1,}'}])

All methods

Full docs: PyPI package README

LangChain Integration

Use JSON Guardian as a LangChain output parser. Automatically extracts, validates, repairs, and enforces schemas on LLM outputs.

pip install langchain-json-guardian

Output Parser

from langchain_json_guardian import JsonGuardianOutputParser
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
    },
    "required": ["summary", "sentiment"],
}

parser = JsonGuardianOutputParser(json_schema=schema)
prompt = ChatPromptTemplate.from_messages([
    ("system", "Analyze the review. {format_instructions}"),
    ("human", "{review}"),
])
llm = ChatOpenAI(model="gpt-4")

chain = prompt | llm | parser
result = chain.invoke({
    "review": "Amazing product!",
    "format_instructions": parser.get_format_instructions(),
})
# result → {"summary": "...", "sentiment": "positive"}

Extract Parser (lightweight)

from langchain_json_guardian import JsonGuardianExtractParser

parser = JsonGuardianExtractParser()
chain = prompt | llm | parser
result = chain.invoke({"text": "Tell me about Alice"})
# Extracts the first JSON object from the LLM output