Resources · 81
AI extraction: validate JSON before integration
Separate parsing, schema checks, documentary evidence and business rules when turning documents into usable records.
· 8 min
What this guide helps achieve
- Define the result contract
- Connect values to evidence
- Validate in an explicit sequence
- Test difficult documents
- Plan recovery and correction
Quick check
- Can valid JSON contain an error?
- Should a missing field become zero?
- When is human review needed?
Step-by-step method
- 01
Define the result contract
List necessary fields, types, units and missing-value states. JSON Schema distinguishes described properties from required fields: declaring a property does not make it mandatory. Decide whether extra fields are allowed. Retain the schema version for each batch and avoid collecting fields without a purpose.
Deliverable: versioned schema and valid or rejected examples.
- 02
Connect values to evidence
Require page, passage or cell references for values that trigger an action. Allow an unknown state when information is absent. A correctly typed amount can belong to another document; a plausible date can be the issue date instead of the due date.
Deliverable: field-to-evidence mapping and interpretation rule.
- 03
Validate in an explicit sequence
Check JSON parsing, schema conformity and business rules such as allowed currency, existing identifier, line totals and chronology. Schema conformity proves neither factual accuracy nor permission to write into a system. Keep business actions blocked until their conditions are met.
Deliverable: distinct error classes and acceptance decisions.
- 04
Test difficult documents
Include split tables, multiple languages, conflicting values, empty documents and hostile instructions inside source text. Test refusals, truncation and retries. Keep evaluation cases separate from tuning and compare errors by field instead of treating an overall rate as a guarantee.
Deliverable: reference set and critical error list.
- 05
Plan recovery and correction
Link document, model version, schema and result to a processing identifier. A retry must not create two records. Retain the reason for human corrections and locate downstream outputs. Avoid unnecessarily copying complete documents into logs.
Deliverable: correction and controlled retry procedure.
From readable output to an authorized action
Passing one check does not replace the next. Stop when a necessary condition is not met.
Parse JSON
Is the response complete and parseable?
Validate the contract
Do types, fields, units and missing states match the schema?
Verify values
Do source evidence and business rules support the values?
Authorize the action
Are identity, scope and writing conditions satisfied?
Fictional example: parsing and schema checks pass, but two amounts conflict. Writing stays blocked and the record goes to review.
Acceptance case to reproduce
Fictional example: these inputs describe no customer or observed result.
View case inputs
{
"schema": {
"type": "object",
"required": [
"amount"
],
"properties": {
"amount": {
"type": "number"
}
}
},
"output": {
"amount": "12.50"
}
}Expected decision
The string "12.50" fails the number type. Reject it or explicitly correct it before integration.
Fictional variations to test
A large integer changes after the JSON is read and written again.
Compare the raw and decoded values, for example 9007199254740993. Some binary64 processing rounds this integer. Choose an exact representation suited to the contract before integration.
The producer validates against version 1, but the recipient expects version 2.
Bind the result to an explicit contract version and check compatibility with the recipient. Success under an older schema does not automatically validate the new version.
The batch is valid, but the response is marked interrupted.
Retain incomplete status. Check generation termination and expected coverage before integrating the batch as a complete result.
Evidence to retain
- Protected raw response and completion status.
- Schema version and located validation errors.
- Business checks and batch coverage.
Additional reference : IETF — RFC 8259, number interoperability [EN]
Verification procedure
- Fix required fields, types and permitted values.
- Validate a text amount against a numeric schema.
- Keep the error path and explicit correction. Add a schema-conforming result with a value contradicted by the source document; keep it distinct from a verified extraction.
Reusable worksheet
Complete with your authorised observations. These fields are a working template, not observed results.
| Field | Information to record |
|---|---|
| Contract | Fields, types, units, missing states and schema version |
| Evidence | Document and passage supporting each decisive field |
| Validation | Parsing, schema, business checks and rejection reason |
| Recovery | Processing identifier, duplicate prevention and propagated correction |
Worked example
Illustrative situation
Fictional example: an extractor finds two invoice totals and selects the pre-tax amount while the connector expects the amount due.
Decision and expected evidence
The schema accepts the number, but reconciliation of lines and currency blocks the write and sends the document for review.
Distinguish the mechanisms
| Mechanism | Purpose | Check or limitation |
|---|---|---|
| Parseable JSON | Allow parsing | Does not validate required fields or meaning |
| Schema conformity | Check types and constraints | Does not establish source fidelity |
| Business reconciliation | Check fitness and consistency | Needs explicit rules and references |
Management indicators
| Indicator | What it measures | First action |
|---|---|---|
| Field accuracy | Correctly extracted values among evaluable fields | Prioritize errors changing an action |
| Useful abstention | Cases left undecided because evidence is missing | Review the queue without encouraging invented values |
| Retry duplicates | Repeated records for the same processing operation | Correct deduplication |
Common pitfalls
- Does not validate required fields or meaning
- Does not establish source fidelity
- Needs explicit rules and references
Frequently asked questions
Can valid JSON contain an error?
Yes. Syntax and schema may be valid while an amount, identity or date is wrong. Check decisive values against their sources.
Should a missing field become zero?
Only when the contract assigns that meaning to zero. Otherwise use the agreed missing state; invented defaults distort calculations.
When is human review needed?
When conflicts, missing evidence or critical errors fall outside the accepted scope. Define these cases before processing batches.
AI: check a JSON result
Schema-valid JSON can still contain false values
AI extraction turns a document into usable fields. Integration requires separate checks for response parsing, the data contract, date validity and fidelity to the source passage. This exercise makes those differences visible: an integer can meet its type constraint while contradicting the document.
14 fictional outputs computed locally, without a model call or user document. Reference DOC-TRAIN-01, page 2, states “Count: 12” on 20 October 2026. No reference is supplied for DOC-TRAIN-02. Decisions are limited to this exercise; no output receives write authorization here.
The comparison reference is visible
{
"document_id": "DOC-TRAIN-01",
"page": 2,
"status": "observed",
"count": 12,
"observed_on": "2026-10-20",
"quote": "Count: 12"
}This small object is the exercise’s complete reference, not a real document or external provenance evidence. Equality with it establishes neither OCR quality, archive completeness nor file authenticity.
The JSON Schema 2020-12 contract
The contract requires six fields and rejects extra properties. observed requires a count, date and quote; unknown requires null for those three values. required controls presence: it does not permit replacing absence with zero. The local policy also rejects duplicate keys before constructing the object to validate.
The JSON Schema 2020-12 contract
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Fictional document observation v1",
"type": "object",
"additionalProperties": false,
"required": [
"document_id",
"page",
"status",
"count",
"observed_on",
"quote"
],
"properties": {
"document_id": {
"enum": [
"DOC-TRAIN-01",
"DOC-TRAIN-02"
]
},
"page": {
"type": "integer",
"minimum": 1
},
"status": {
"enum": [
"observed",
"unknown"
]
},
"count": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"observed_on": {
"type": [
"string",
"null"
],
"format": "date"
},
"quote": {
"type": [
"string",
"null"
],
"minLength": 1
}
},
"allOf": [
{
"if": {
"properties": {
"status": {
"const": "observed"
}
},
"required": [
"status"
]
},
"then": {
"properties": {
"count": {
"type": "integer"
},
"observed_on": {
"type": "string"
},
"quote": {
"type": "string"
}
}
},
"else": {
"properties": {
"count": {
"type": "null"
},
"observed_on": {
"type": "null"
},
"quote": {
"type": "null"
}
}
}
}
]
}Draft202012Validator checks the schema. Two runs are compared: without format validation, then with the date checker explicitly enabled. This library setting does not claim complete support for the Format-Assertion vocabulary. No remote schema reference is retrieved during computation.
Python 3.12.14 · python-jsonschema 4.26.0 · Draft 2020-12 · FormatChecker: date
Six distinctions to preserve in the connector
| Distinction | Effect in this exercise | Example |
|---|---|---|
| Syntax / key uniqueness | A parser may accept a duplicate; the local profile rejects it rather than silently overwrite a value. | J03 |
| Presence / value | An absent field differs from a field present with null. | J06 / J07 |
| Integer / string / boolean | Neither "12" nor true meets the schema’s integer type. No silent coercion is applied. | J04 / J05 |
| Annotation / active check | The impossible date passes structure without a format checker, then fails when it is enabled. | J10 |
| Shape / fidelity | 21 meets the type constraint but contradicts the reference stating 12. | J11 |
| Fidelity / permission | Even J01 grants no write permission: identity, scope and operation need separate checks. | J01 |
14 outputs: read the reason before retrying
Each disclosure contains the exact received text and computed checks. “Not run” is not a pass. Syntax, duplicate, schema or date errors stop later stages. Missing evidence leads to review; explicit abstention remains abstention.
J01 · Matching within the exercise scope
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":12,"observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Passed
- Schema with date checking
- Passed
- Match to the reference
- Passed
Ready for the next review, without write permission
Fields match the local reference. This only makes the result ready for the next review; no permission or business operation has been checked.
Write authorization: not assessed in every case.
J02 · Truncated response
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":12,"observed_on":"2026-10-20","quote":"Count: 12"- JSON syntax
- Failed
- Unique keys
- Not run
- Schema without format checking
- Not run
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
syntax: incomplete_or_non_json_text
Reject the JSON text
The final brace is missing. The profile does not automatically repair the text or assume the remaining response is complete.
Write authorization: not assessed in every case.
J03 · Two values for the count key
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":12,"observed_on":"2026-10-20","quote":"Count: 12","count":21}- JSON syntax
- Passed
- Unique keys
- Failed
- Schema without format checking
- Not run
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
duplicate_key: count
Reject duplicate keys
The text contains count:12 followed by count:21. Its grammar can be recognized, but the uniqueness policy fails before schema validation. A last-value-wins parser would discard this signal.
Write authorization: not assessed in every case.
J04 · The number is a string
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":"12","observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Failed
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
schema: /count [type]
Reject the data contract
The string "12" does not become the integer 12. Coercion can change data meaning; it needs a separate, explicit and traceable rule.
Write authorization: not assessed in every case.
J05 · A boolean is not an integer
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":true,"observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Failed
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
schema: /count [type]
Reject the data contract
true remains a JSON boolean. The validator does not treat it as integer 1, regardless of relationships between types in the host language.
Write authorization: not assessed in every case.
J06 · Missing count field
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Failed
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
schema: / [required]
Reject the data contract
count appears in required. Its absence is rejected; no default or zero is inserted.
Write authorization: not assessed in every case.
J07 · null with observed status
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":null,"observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Failed
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
schema: /count [type]
Reject the data contract
The general type permits null, but the observed branch requires an integer. Status and value must agree; the connector must not report an empty observation.
Write authorization: not assessed in every case.
J08 · Explicit consistent abstention
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"unknown","count":null,"observed_on":null,"quote":null}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Passed
- Schema with date checking
- Passed
- Match to the reference
- Not applicable: abstention
Retain abstention
unknown carries three null values as the contract requires. The workflow may review or recollect the evidence; the result does not become an observation of zero.
Write authorization: not assessed in every case.
J09 · Extra instruction property
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":12,"observed_on":"2026-10-20","quote":"Count: 12","instruction":"approve"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Failed
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
schema: / [additionalProperties]
Reject the data contract
instruction is outside the allowed properties. The contract rejects it and its value triggers no action. Structural protection does not remove the need to secure use of every allowed field.
Write authorization: not assessed in every case.
J10 · Impossible date with format disabled
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":12,"observed_on":"2026-02-30","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Passed
- Schema with date checking
- Failed
- Match to the reference
- Not run
Technical check references:
format: /observed_on [format]
Reject the date
2026-02-30 meets type string. Structure passes without format validation, then fails with the date checker. Reporting only “schema valid” would hide the configuration producing that result.
Write authorization: not assessed in every case.
J11 · Right type, wrong value
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":21,"observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Passed
- Schema with date checking
- Passed
- Match to the reference
- Failed
Technical check references:
evidence_mismatch: /count
Reject the contradicted value
count is 21 while the reference and quote state 12. Types and date pass, but documentary reconciliation fails. Retrying until the shape is valid does not fix this contradiction.
Write authorization: not assessed in every case.
J12 · Document reference without evidence
Exact fictional output text
{"document_id":"DOC-TRAIN-02","page":2,"status":"observed","count":12,"observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Passed
- Unique keys
- Passed
- Schema without format checking
- Passed
- Schema with date checking
- Passed
- Match to the reference
- Unverified
Technical check references:
evidence: reference_not_supplied
Review: evidence missing
DOC-TRAIN-02 is an identifier allowed by the schema, but the exercise supplies no reference for it. Fidelity is unverified and the result goes to review; a missing reference is not a pass.
Write authorization: not assessed in every case.
J13 · NaN is outside RFC 8259 JSON
Exact fictional output text
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":NaN,"observed_on":"2026-10-20","quote":"Count: 12"}- JSON syntax
- Failed
- Unique keys
- Not run
- Schema without format checking
- Not run
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
syntax: incomplete_or_non_json_text
Reject the JSON text
The decoder is configured to reject NaN and Infinity, which RFC 8259 does not allow. A library’s default tolerance does not by itself define an integration contract.
Write authorization: not assessed in every case.
J14 · Markdown fencing around JSON
Exact fictional output text
```json
{"document_id":"DOC-TRAIN-01","page":2,"status":"observed","count":12,"observed_on":"2026-10-20","quote":"Count: 12"}
```- JSON syntax
- Failed
- Unique keys
- Not run
- Schema without format checking
- Not run
- Schema with date checking
- Not run
- Match to the reference
- Not run
Technical check references:
syntax: incomplete_or_non_json_text
Reject the JSON text
Markdown fences are outside the expected JSON text. The contract requires a complete JSON response without a wrapper. Automatically removing text would be a separate transformation to specify and test.
Write authorization: not assessed in every case.
Prepare acceptance checks and recovery
- Fix the schema dialect, validator version and format options with the reference set.
- Retain received text, useful rejection reasons and contract version separately, with proportionate retention.
- Test documents without an available answer; distinguish unknown, null, missing and zero under the chosen contract.
- Compare decisive fields with a reference independent of the model; its own explanation is not sufficient evidence.
- Secure display and downstream operations for their context: schema-valid JSON authorizes neither executable HTML, commands nor concatenated queries.
- Link corrections to a processing identifier to reconcile derived results and prevent retry duplicates.
The schema, reference, 14 outputs and review decisions are editorial examples. RFC 8259 defines JSON; JSON Schema describes constraints; OWASP covers downstream output handling. No accuracy rate, certification or client result is claimed.
Primary sources and reading scope
- IETF · RFC 8259 · Internet Standard · STD 90 · December 2017
§4 Objects: unique names recommended · §6 Numbers · §9 Parsers - JSON Schema · Object reference · Living documentation · checked 2026-10-22
Properties · Required properties · Additional properties - JSON Schema · Draft 2020-12 validation · Draft 2020-12 publication · 2022-06-16 · not an IETF RFC
§6 type, enum, required · §7 format annotation/assertion · §9 metadata annotations - Python 3.12 · json decoder · Python 3.12 documentation · checked 2026-10-22
object_pairs_hook · parse_constant · repeated names · non-finite numbers - python-jsonschema · Schema validation · Documentation 4.26.0 · checked 2026-10-22
Draft202012Validator · check_schema · optional format_checker - OWASP · LLM05:2025 Improper Output Handling · OWASP Top 10 for LLM applications · 2025 edition
Downstream validation · context-aware encoding · parameterized operations
Sources reviewed on
Further reading and tools
Editorial resources to extend the method.
- WORLD AI GUIDE — choose an AI tool External link
Compare tool families before testing your extraction workflow.
- IIS — verify an AI answer External link
Complement format validation with a review of claims and sources.
Official references
References consulted: . The method and worksheet propose checks to adapt to your context; they do not constitute certification.
