Schemas

A schema has two jobs in DeepRead:

1. Extraction: tells DeepRead what structured data to extract from a document.
2. Optimization: serves as the starting point for the optimizer to produce an optimized schema blueprint for your document type.

If you don’t provide a schema (or a blueprint), DeepRead returns the document as Markdown with tables and layout blocks, plus bounding boxes when you send include_markers=true.

Where schemas are used in the API

Schemas are applied when you call POST /v1/process:

• Pass schema to extract structured fields (in addition to OCR)
• Or pass blueprint_id to use an optimizer-produced schema blueprint (mutually exclusive with schema)

1) Schemas tell DeepRead what to extract

At a minimum, a schema is:

• Root: {"type":"object"}
• Fields: properties where each field has a type and (ideally) a description

Here’s a minimal example:

{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": "string",
      "description": "Invoice number, usually labeled 'Invoice #' near the top"
    },
    "total_amount": {
      "type": "number",
      "description": "Final amount due (not subtotal), often labeled 'Amount Due'"
    }
  }
}

What matters most: description

DeepRead uses your field description as the primary extraction guidance. Good descriptions include:

• Common labels (“Amount Due”, “Total”)
• Location hints (“top-right summary box”)
• Disambiguation (“not subtotal”)

datapoint_prompt - optimizer output

If present, DeepRead will prefer datapoint_prompt over description for extraction guidance. This is typically generated by the optimizer.

Output shape - result

For schema-based extraction, each field comes back in the extraction.fields list with quality metadata so you can decide what needs review:

{
  "extraction": {
    "fields": [
      {
        "key": "total_amount",
        "value": 1250.0,
        "needs_review": false,
        "location": { "page": 1 }
      }
    ]
  }
}

See Handling Results for patterns on consuming these results and building webhook handlers.

Optional: validation and flagging uncertain result

DeepRead supports a set of validation rules that can set needs_review=true when values look suspicious. Example:

{
  "properties": {
    "invoice_number": {
      "type": "string",
      "validation": {
        "type": "pattern",
        "regex": "^INV-[0-9]{5}$",
        "message": "Must match format INV-12345"
      }
    }
  }
}

2) Schemas are used by the Optimizer

The optimizer uses your schema (plus training docs + ground truth) to rewrite field guidance into more reliable prompts (usually as datapoint_prompt) and produce a reusable blueprint you can pass to /v1/process via blueprint_id.

See Using the Optimizer for the workflow.