Designing a Reliable OCR JSON Schema for Text, Fields, Confidence, and Provenance

Overview

OCR APIs and SDKs often return different response formats. One may emphasize a complete text string, another may return page geometry and word-level confidence, while a document AI API may add semantic fields such as invoice totals or receipt dates. Passing these responses directly into business systems creates unnecessary coupling to a vendor and makes later quality checks difficult.

A normalized OCR JSON schema creates a stable boundary between recognition and automation. Your application can retain the original response for audit or troubleshooting while mapping the useful parts into an internal structure. Databases, review queues, search indexes, validation services, and accounting systems can then consume the same predictable format even if the OCR provider changes.

The schema should answer five practical questions:

• What was recognized? Store document text at page, block, line, and word levels where available.
• Where was it found? Preserve page numbers, bounding boxes, polygons, coordinate systems, and reading order.
• How reliable is it? Keep confidence scores for the document, fields, lines, and words without treating them as absolute truth.
• What does it mean? Represent extracted fields such as invoice numbers, totals, dates, names, or tax amounts separately from raw text.
• What happened afterward? Record source, processing time, model or provider metadata, corrections, validation results, and schema version.

For implementation context, pair this design with a production-ready OCR API pipeline in Python and decide early whether your workflow needs searchable text, layout preservation, or table extraction. The right output depends on the document use case, not only on the OCR engine.

Template structure

The following template is intentionally provider-neutral. It uses a top-level document object, an array of pages, optional semantic fields, and a provenance section. Coordinates are represented as normalized values between 0 and 1 in this example, but pixel coordinates can be used if the coordinate system is explicitly declared.

{
  "schema_version": "1.0.0",
  "document": {
    "id": "doc_123",
    "source": {
      "file_name": "invoice-123.pdf",
      "media_type": "application/pdf",
      "page_count": 1,
      "language": ["en"]
    },
    "text": "Complete normalized document text",
    "confidence": 0.96,
    "pages": [
      {
        "page_number": 1,
        "width": 2550,
        "height": 3300,
        "unit": "pixel",
        "rotation": 0,
        "text": "Text recognized on this page",
        "confidence": 0.95,
        "blocks": [
          {
            "id": "block_1",
            "type": "paragraph",
            "text": "Invoice Number: INV-123",
            "reading_order": 1,
            "confidence": 0.98,
            "bounding_box": {
              "x": 0.10,
              "y": 0.12,
              "width": 0.35,
              "height": 0.03,
              "coordinate_system": "normalized"
            },
            "lines": [
              {
                "text": "Invoice Number: INV-123",
                "confidence": 0.98,
                "words": [
                  {
                    "text": "INV-123",
                    "confidence": 0.99,
                    "bounding_box": {
                      "x": 0.28,
                      "y": 0.12,
                      "width": 0.17,
                      "height": 0.03,
                      "coordinate_system": "normalized"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "fields": [
      {
        "name": "invoice_number",
        "value": "INV-123",
        "value_type": "string",
        "confidence": 0.99,
        "source": {
          "page_number": 1,
          "block_id": "block_1",
          "text": "INV-123"
        },
        "status": "extracted",
        "corrections": []
      }
    ]
  },
  "provenance": {
    "provider": "ocr-provider",
    "model": "provider-model",
    "request_id": "request_456",
    "processed_at": "2026-01-01T00:00:00Z",
    "original_response_ref": "storage://ocr/raw/request_456"
  },
  "validation": {
    "status": "needs_review",
    "rules": [],
    "errors": [],
    "warnings": []
  }
}

Not every application needs every level of detail. Word-level geometry is valuable for highlighting search results, redacting sensitive text, or resolving ambiguous fields, but it increases payload size. A simple archival workflow may need page text and page-level coordinates only. Keep the structure extensible, but do not add fields that your application cannot maintain or interpret.

Use consistent conventions throughout the schema:

• Use ISO 8601 timestamps with an explicit time zone.
• Use one confidence range, such as 0 to 1, and document whether the value comes from the OCR provider or your own calibration.
• Use stable identifiers for pages, blocks, fields, and source references.
• Keep raw OCR text separate from normalized or corrected text.
• Declare whether coordinates are pixels, points, percentages, or normalized values, and define the origin and axis direction.
• Represent missing values as null when the distinction between “not found” and an empty string matters.

How to customize

Start with the decisions your downstream system must make. For receipt OCR, fields might include merchant name, transaction date, subtotal, tax, total, currency, and line items. For an invoice OCR API, you may need supplier identity, invoice number, purchase order number, due date, tax identifiers, totals, and payment terms. A form data extraction workflow may require repeated sections, checkboxes, signatures, and field-level review status.

Define semantic fields as references to source text rather than isolated values. A field should include its extracted value, type, confidence, location, and source span. If a total is corrected by an employee, preserve the original value and add an event such as:

{
  "corrections": [
    {
      "original_value": "1O0.00",
      "corrected_value": "100.00",
      "reason": "character_confusion",
      "actor_type": "human_reviewer",
      "actor_id": "reviewer_42",
      "corrected_at": "2026-01-01T00:05:00Z"
    }
  ]
}

This distinction supports auditability. It also allows you to measure whether a problem originated in image quality, recognition, field mapping, normalization, or manual entry. Do not overwrite raw text merely because a later stage cleaned it. Store a normalized value alongside the raw value, for example a machine-readable date beside the exact date string printed on the document.

Confidence should guide review, not make the decision alone. A high-confidence value can still be semantically wrong if the wrong number was selected from a dense invoice. Combine confidence with validation rules, such as:

• Invoice totals should reconcile with subtotal, tax, discounts, and shipping where those fields are present.
• Dates should parse into an allowed format and fall within a reasonable business range.
• Currency codes should come from an accepted list or a controlled mapping.
• Required fields should be present before automatic posting or approval.
• Fields extracted from an identity document should retain their page and region references for review.

For privacy-sensitive documents, include references to retention and access controls in your system design, but avoid storing secrets or unnecessary personal data inside the OCR payload. The OCR privacy and compliance checklist and the guide to OCR data retention policies provide useful planning prompts.

Examples

Scanned PDF: Store each page independently so a user can locate a phrase and a processing job can retry only the failed page. Preserve rotation, dimensions, text blocks, and reading order. If tables matter, add a table object with rows, columns, cells, cell geometry, and cell confidence rather than flattening the table into an ambiguous text string. See the PDF OCR processing checklist for the distinctions between searchable text, layout, and table extraction.

Receipt: Keep line items as structured children of a receipt field or transaction object. Each item can contain description, quantity, unit price, discount, tax, and amount, with a source region for the complete row. This makes it possible to validate totals and send only approved values to an expense system. A practical field set is outlined in the receipt OCR data extraction guide.

Invoice: Separate header fields from line items and payment details. Link every normalized value to the page, block, or word that produced it. If multiple candidate invoice numbers or totals are found, use a candidates array instead of silently selecting one. Each candidate can include value, confidence, location, and a selection status such as selected, rejected, or unresolved.

Handwritten or multilingual document: Add language at the document, page, or block level because one document may contain more than one script. Record whether text direction is left-to-right, right-to-left, or mixed when that affects rendering. Handwriting confidence may not be directly comparable with printed-text confidence, so label the source and use workflow-specific review thresholds.

When mapping a provider response, retain a raw-response reference and create a deterministic transformation step. That mapping should translate provider-specific labels into your controlled vocabulary, convert coordinates into your chosen system, and preserve unmapped provider data for investigation rather than discarding it.

When to update

Review the schema whenever your document mix, OCR API, or downstream workflow changes. A new invoice layout may require additional fields or a different line-item model. Adding passports, identity cards, bank statements, or handwritten forms may require document-type metadata, language information, redaction markers, or more precise geometry. A provider migration may change confidence semantics, coordinate conventions, page indexing, or available model metadata.

Use semantic versioning for breaking changes. A new optional field can usually be a minor revision; renaming a required field, changing a value type, or altering coordinate meaning should be treated as a breaking revision. Maintain migration code for older records, document examples for each supported version, and test fixtures containing difficult cases such as rotated scans, low contrast, multi-page tables, duplicate totals, and mixed languages.

Make updates practical with a short maintenance cycle:

1. Review failed validations and manual corrections from production.
2. Identify whether the failure belongs to OCR, field mapping, normalization, or business rules.
3. Update the schema only when the new information has a stable downstream purpose.
4. Add a representative document and expected JSON result to your test set.
5. Run compatibility checks before changing consumers or database columns.
6. Record the schema version with every processed document.

A structured OCR result is most useful when it remains understandable months after ingestion. Keep raw evidence, semantic meaning, confidence, and provenance distinct; validate before automation; and make versioning part of the data model rather than an afterthought. Revisit this design whenever you add a document type, revise extraction fields, change vendors, or discover a review problem that the current output cannot explain.