All lessons T
Data Transformation intermediate 12 min

Validate a Payload Against the Shape You Expect

Use a schema check to separate syntax-valid JSON from contract-valid JSON.

Scenario

A payload parses cleanly, yet the API rejects it with 422 Unprocessable Entity. This is the gap between syntax and contract: {"active": "true"} is perfectly valid JSON and still wrong if the schema demands a boolean. String-typed booleans are among the most common contract bugs because form inputs, environment variables, and query strings all deliver "true" as text. Check the payload against a schema before anyone starts "fixing" backend code that was never broken.

Broken input

schema: required name:string, active:boolean
payload: {"name":"Ada","active":"true"}

Goal

Use JSON Schema Validator / Generator to test the payload against the expected types and surface the exact field and mismatch, instead of inferring it from a vague 422.

Tool sequence

  1. Open JSON Schema Validator / Generator.
  2. Enter the schema — write it out, or generate a starter schema from a known-good payload and tighten the types.
  3. Paste the failing payload and run validation.
  4. Read the error: active expects type boolean but got string. The quotes around true are the whole bug.
  5. Fix the producer to send "active": true (no quotes) and re-validate; if the payload came from a curl example, convert and inspect it with cURL to fetch / Axios to see where the value gets stringified.

Checkpoint output

✖ /active — expected boolean, received string

fixed payload:
{"name":"Ada","active":true}

Validation pins the failure to active being the string "true" instead of the boolean true — a one-character-class fix, found without touching backend code.

Common mistakes

  • Stopping at JSON syntax validation when the contract is the real gate — parse success proves nothing about types.
  • Letting generated schemas mark every field optional, so validation passes on payloads missing required data.
  • Changing API code before confirming which side of the contract drifted.
  • Testing only the happy-path payload; the schema earns its keep on edge cases like null, "", and 0.

Related tools and lessons