How to Validate Your Agent’s JSON Output Before Acting On It

The problem

Agents built around a model that’s asked to return structured JSON (“call this tool with these arguments”) will eventually get back something that isn’t quite right — malformed JSON, a missing field, a number sent as text. Code that trusts that output blindly fails in confusing ways, often several steps later, far from the actual cause.

Expected outcome

By the end of this guide you will have a small validator that checks a model’s JSON output against the shape you expect, before your agent acts on it, with a clear error naming exactly what’s wrong.

Requirements and costs

• Node.js (version 18 or newer).
• Cost: free. No dependencies.

Step-by-step implementation

1. Download the starter from the link below.
2. Describe the shape you expect as a plain object of field names to types:

   const shape = { action: "string", amount: "number" };

3. Validate the model’s raw text output before parsing it yourself anywhere else:

   const { validate } = require("./validate-output");
   const result = validate(modelRawText, shape);
   if (!result.ok) {
     // handle result.error -- ask the model again, log it, or fall back to a default
   } else {
     // result.value is a real object matching your shape, safe to use
   }

A real example

validate('{"action": "refund", "amount": 25}', shape)
  // { ok: true, value: { action: "refund", amount: 25 } }

validate('{action: refund}', shape)
  // { ok: false, error: "not valid JSON: Expected property name or '}'..." }

validate('{"action": "refund"}', shape)
  // { ok: false, error: "missing field(s): amount" }

validate('{"action": "refund", "amount": "25"}', shape)
  // { ok: false, error: "wrong type for: amount (expected number, got string)" }

Verification and troubleshooting

What we tested, on 5 October 2026 (record TNT-TEST-2026-10-05-007): 4 real cases against the same shape — a genuinely valid object (passed), malformed JSON (caught with a parse error), a missing field (caught by name), and a wrong type (caught by name, with both the expected and actual type shown). All 4 matched the expected result exactly.

Troubleshooting:

• A valid-looking value still fails. Check the type names match JavaScript’s own typeof results exactly — arrays need "array" in your shape, not "object" (the validator already special-cases this correctly, but make sure your shape description does too).
• You need nested object validation. This checks one flat level of fields; for nested shapes, validate the outer object first, then call validate() again on the nested value with its own shape.
• You want to allow extra, unexpected fields. This validator already does — it only checks the fields YOU listed in shape exist with the right type; it never rejects extra fields it wasn’t told about.

Limitations and alternatives

This checks presence and type, not value ranges or nested structures. For genuinely complex schemas, a real JSON Schema validator library is worth the dependency; for the common “does this have the fields I need, with roughly the right types” check, this needs nothing installed.

Free resources

The download contains the validator and a runnable demo covering all 4 cases above.

Download the JSON output validator (ZIP, 1 KB)

Is there a paid version?

Not yet. This is the complete method. TNT Review has sold nothing to date and has no checkout, so any price we discuss in future should be read as a hypothesis, not an offer.