LLM Output Validator: JSON Schema + Repair Hints

Validate LLM or tool-call JSON output against a JSON Schema (draft-07 or 2020-12) and get back machine-readable error paths plus a concrete, actionable repair hint for every single error — not just AJV's raw "must be integer" message, but something like "At /age: change the value to type 'integer' (currently string, value '30'). If this looks like a stringified number/boolean, running with 'normalize': true may fix it automatically." Optionally also get deterministic, information-preserving normalization ("42" → 42, whitespace trimmed) with every applied change logged, and a fully repaired document when every error in it was fixable this way. 100% deterministic, pure computation — no network calls, no LLM calls, no scraping.

When should an AI agent use this?

• "My agent just called a tool and I need to check the JSON response matches the tool's expected schema before passing it downstream."
• "Validate this batch of 50 LLM-generated JSON records against our internal data schema and tell me exactly which ones are broken and why."
• "I got {\"age\": \"30\"} back from a model but my schema wants age as an integer — can this be fixed automatically without another LLM call?"
• "Give me a structured list of schema violations (with instancePath and schemaPath) I can feed straight back into a retry prompt."
• "Check whether this OpenAI/Anthropic tool-call argument JSON actually satisfies my function's parameter schema."
• "I want an audit trail of every value my pipeline silently coerced, not a black box."

What this Actor does

• Validates each document in documents against the JSON Schema in schema, using AJV — supports both draft-07 and 2020-12 (auto-detected from the schema's own $schema field; defaults to draft-07 when absent).
• Returns, per document: valid (boolean), errors[] with instancePath, schemaPath, keyword, message, and (when hints is on) a hint string that names the exact fix — not a restatement of the error.
• Optional deterministic normalization: safe, information-preserving coercions only (string→number/integer/boolean when the schema requires it and the value round-trips exactly, number/boolean→string, whitespace trimming) — logged per change in appliedTransforms[]. Never guesses: an ambiguous value (e.g. "007", "yes") is left untouched and its error stays in errors[].
• repairable + repairedData: a document is only reported as repairable: true (with a repairedData payload) when every single error in it was resolved by the deterministic normalization layer above — otherwise repairable: false and no repairedData, so you never get a partially-fixed document silently presented as "done".
• One flat, MCP-friendly JSON record per document in the dataset — easy for an AI agent to consume directly as a tool result.

Input

Field	Type	Description
documents	array of strings	One or more JSON documents to validate, each given as a JSON string (e.g. "{\"name\":\"Alice\",\"age\":30}"). A string that fails to parse as JSON is reported as a per-document error, not a run failure. Example: ["{\"name\": \"Alice\", \"age\": 30}"].
schema	object	The JSON Schema (draft-07 or 2020-12) every document must satisfy. Add "$schema": "https://json-schema.org/draft/2020-12/schema" to use 2020-12-only features; otherwise draft-07 is assumed.
hints	boolean	Generate a concrete repair hint per error. Default true.
normalize	boolean	Apply safe, deterministic type coercions and return normalizedData/appliedTransforms/repairedData. Default false.
maxErrorsPerDocument	integer	Caps how many error entries are returned per document (errorCount/truncated always reflect the real, uncapped total). Default 20, max 1000.

Output

One flat JSON record per validated document:

{
  "index": 1,
  "valid": false,
  "errors": [
    {
      "instancePath": "/age",
      "schemaPath": "#/properties/age/type",
      "keyword": "type",
      "message": "must be integer",
      "hint": "At /age: change the value to type \"integer\" (currently string, value \"25\"). If this looks like a stringified number/boolean, running with \"normalize\": true may fix it automatically."
    }
  ],
  "errorCount": 1,
  "truncated": false,
  "repairable": true,
  "normalizedData": { "name": "Bob", "age": 25, "email": "bob@example.com" },
  "appliedTransforms": [
    { "path": "/age", "from": "25", "to": 25, "reason": "coerced string to integer (schema requires numeric type at this path)" }
  ],
  "repairedData": { "name": "Bob", "age": 25, "email": "bob@example.com" }
}

A document that fails to parse as JSON in the first place:

{
  "index": 3,
  "valid": false,
  "errors": [
    {
      "instancePath": "",
      "schemaPath": "",
      "keyword": "json-parse",
      "message": "Unexpected token 'o', \"not valid json\" is not valid JSON",
      "hint": "This document string is not valid JSON — fix the JSON syntax (unescaped quotes, trailing commas, unquoted keys) before revalidating. No schema check could run."
    }
  ],
  "errorCount": 1,
  "truncated": false,
  "repairable": false,
  "parseError": "Unexpected token 'o', \"not valid json\" is not valid JSON"
}

Field	Description
index	0-based position of this document in the documents input array
valid	Whether the document satisfies schema
errors	Up to maxErrorsPerDocument errors, each with instancePath/schemaPath/keyword/message and (if hints: true) hint
errorCount	The REAL total error count, even if errors was capped
truncated	true if errorCount is larger than the returned errors array
repairable	true if the document is already valid, or if EVERY error in it was resolved by deterministic normalization
normalizedData	Only present when normalize: true — the document with safe coercions applied
appliedTransforms	Only present when normalize: true — every coercion that was applied, with path/from/to/reason
repairedData	Only present when normalize: true AND repairable: true AND the document was originally invalid
parseError	Only present if the input string itself was not valid JSON

Use cases

• Guard a function-calling / MCP pipeline: validate a model's tool-call arguments before executing the tool, and feed the hint strings straight back into a retry prompt instead of a raw AJV error dump.
• Batch-audit a dataset of LLM-generated JSON records against a target schema before ingesting them into a downstream system.
• Give an agent framework a single deterministic "validate + try to self-heal" step that never silently guesses at ambiguous data.
• Regression-test your own JSON Schema definitions against known-good/known-bad example payloads.
• Build an audit trail of exactly which values a pipeline coerced and why, instead of a black-box "it worked" or "it didn't".

Pricing

This Actor uses Apify's Pay-Per-Event (PPE) pricing model.

• Actor Start: $0.00005 (Apify default)
• document-validated: $0.0015 per document validated (charged once per document in documents, regardless of whether it was valid, invalid, or unparsable JSON)

See STOREINFO.md for the full pricing table and rationale.

Legal

This Actor performs pure computation on documents and a JSON Schema you supply directly as input — it does not scrape, crawl, or fetch any external data, and does not collect or store personal data beyond what you choose to submit as documents for the duration of the run's dataset. You remain fully responsible for the content of the documents you submit and for how you use the validation/normalization results downstream. Normalization is intentionally conservative (see "What this Actor does" above) — it never invents or reinterprets ambiguous values, so it will never silently change the meaning of your data.

FAQ

Does this call an LLM to figure out how to fix errors? No. Every hint and every normalization decision is deterministic, rule-based logic derived directly from AJV's error output and the schema's own declared types — no model call, no randomness, no network access at runtime.

What's the difference between normalizedData and repairedData? normalizedData is always the best-effort result of applying safe coercions, whether or not that fully fixes the document. repairedData is only present when normalization fixed every error — i.e. the document is now fully schema-valid. If even one error remains, you get repairable: false and no repairedData, so you never mistake a partial fix for a complete one.

Will normalize ever change a value in a way that could be wrong? No — by design. It only coerces a string to a number/boolean when the string round-trips exactly (e.g. "42" → 42, but NOT "007" or "1e3", which are rejected as ambiguous), only accepts the literal strings "true"/"false" for booleans (never "yes"/"1"), and only trims whitespace. Anything it's not fully sure about is left untouched.

Does this support $ref in my schema during normalization? Validation itself fully supports $ref (AJV resolves it natively). The normalization/repair layer does not resolve $ref in v1 — a subschema reached only through a $ref is passed through unchanged rather than guessed at. Validation errors in that subtree still appear in errors[] as normal; they're just not eligible for automatic repair yet.

What happens if my schema itself is invalid? Every document in that run is reported with a schema-invalid error explaining why, and none are charged — fix the schema and run again.

Why is documents an array of strings instead of an array of objects? Apify's input-schema format doesn't support array items that can be either an object or a string, so every document is provided as a JSON string (works equally well whether your data started as an object or as raw model output text) — see the Input table above for an example.

Keywords

json schema validator, llm output validation, function calling validator, tool call validation, mcp tool output check, structured output validator, json repair, schema conformance checker, ajv validator actor, agent output validation, self-healing json, deterministic json repair, draft-07 validator, 2020-12 json schema, llm guardrails, structured outputs verification

Changelog

0.1.0

• Initial release: draft-07 and 2020-12 JSON Schema validation via AJV, keyword-specific repair hints for every AJV error type, deterministic normalization layer with full transform logging, repairable/repairedData semantics.