openparser@1 schema

openparser@1 ParsedDocument graph

OpenParser parse routes and @openparser/adapters return one ParsedDocument graph. Swap Paddle, Mistral, Azure Document Intelligence, Google Document AI, or AWS Textract without rewriting extractors, citation logic, or eval harnesses downstream.

Read schema docsRead adapter docs
Zod + TypeScript types5 provider adaptersHosted API uses same shape
ParsedDocument, openparser@1sample
{
  "output_format": "openparser@1",
  "document_id": "doc_3f9a2c",
  "provenance": {
    "provider": "paddle",
    "model": "paddleocr-vl-1.6"
  },
  "text": "Total due: $4,318.20",
  "markdown": "Total due: $4,318.20\n",
  "pages": [
    {
      "number": 1,
      "width": 1700,
      "height": 2200,
      "unit": "pixel",
      "element_ids": [
        "elem-total"
      ],
      "reading_order": [
        "elem-total"
      ]
    }
  ],
  "elements": [
    {
      "id": "elem-total",
      "kind": "text",
      "role": "paragraph",
      "text": "Total due: $4,318.20",
      "spans": [
        {
          "start": 0,
          "end": 20
        }
      ],
      "locations": [
        {
          "page_number": 1,
          "bbox": {
            "left": 14,
            "top": 53,
            "right": 146,
            "bottom": 123
          }
        }
      ],
      "confidence": {
        "score": 0.98,
        "scope": "recognition",
        "calibrated": false
      }
    }
  ],
  "relations": [],
  "text_annotations": [],
  "assets": []
}

OCR vendors return incompatible JSON

Every OCR provider returns a different JSON shape: Azure Document Intelligence, AWS Textract, Google Document AI, Mistral OCR, and Paddle each invent their own pages, lines, tables, and boxes.

If your pipeline parses those payloads directly, swapping engines means rewriting extractors, citation resolvers, and eval harnesses. openparser@1 is the normalization layer so consumers depend on one contract.

The hosted OpenParser API runs the same adapters server-side. Local adapters under @openparser/adapters emit the identical graph when you self-host OCR.

ParsedDocument fields from /parse

Top-level keys on a successful sync parse. Extraction wraps this graph under parsed_document and adds grounded citations that reference element IDs and source locations.

response200, sample
{
  "output_format": "openparser@1",
  "document_id": "doc_3f9a2c",
  "provenance": {
    "provider": "paddle",
    "model": "paddleocr-vl-1.6"
  },
  "text": "Total due: $4,318.20",
  "markdown": "Total due: $4,318.20\n",
  "pages": [
    {
      "number": 1,
      "width": 1700,
      "height": 2200,
      "unit": "pixel",
      "element_ids": [
        "elem-total"
      ],
      "reading_order": [
        "elem-total"
      ]
    }
  ],
  "elements": [
    {
      "id": "elem-total",
      "kind": "text",
      "role": "paragraph",
      "text": "Total due: $4,318.20",
      "spans": [
        {
          "start": 0,
          "end": 20
        }
      ],
      "locations": [
        {
          "page_number": 1,
          "bbox": {
            "left": 14,
            "top": 53,
            "right": 146,
            "bottom": 123
          }
        }
      ],
      "confidence": {
        "score": 0.98,
        "scope": "recognition",
        "calibrated": false
      }
    }
  ],
  "relations": [],
  "text_annotations": [],
  "assets": []
}
  • output_format
    "openparser@1"
    Version of the document graph contract.
  • document_id
    string
    Stable identifier for the parsed document.
  • provenance
    object
    Provider and model that produced the document.
  • text
    string
    Plain text in reading order. Text spans index into this field.
  • markdown
    string
    Best-effort markdown rendering of the document.
  • pages[]
    DocumentPage[]
    Page dimensions, coordinate units, element IDs, and reading order.
  • elements[]
    DocumentElement[]
    Text, tables, figures, and related semantic content.
  • elements[].id
    string
    Stable element ID used by extraction citations.
  • elements[].locations
    Geometry[]
    Source page numbers and geometry when available.
  • elements[].confidence
    Confidence?
    Scoped OCR confidence with calibration metadata, when supplied.
  • relations[]
    DocumentRelation[]
    Links such as containment, captions, and reading order.
  • text_annotations[]
    TextAnnotation[]
    Language and style metadata over text spans.
  • assets[]
    DocumentAsset[]
    Referenced page and figure image assets.

Normalize vendor JSON with @openparser/adapters

Install only the @openparser/adapters subpaths you need. Each adapter maps a vendor response into openparser@1 pages and elements.

  • Paddle HPS
    @openparser/adapters/paddle
    Normalize Paddle HPS responses into openparser@1.
  • Mistral OCR
    @openparser/adapters/mistral
    Normalize Mistral OCR responses into openparser@1.
  • Azure Document Intelligence
    @openparser/adapters/azure-document-intelligence
    Normalize Azure Document Intelligence responses into openparser@1.
  • Google Document AI
    @openparser/adapters/google-document-ai
    Normalize Google Document AI responses into openparser@1.
  • AWS Textract
    @openparser/adapters/aws-textract
    Normalize AWS Textract responses into openparser@1.

Install @openparser/schema and adapters

Schema and adapters are open source. Hosted parse still meters pages when you use the cloud API.

shell
npm install @openparser/schema @openparser/adapters
typescript
import { ParsedDocumentSchema } from "@openparser/schema";
import { mapLayoutResultsToParsedDocument } from "@openparser/adapters/paddle";

const doc = ParsedDocumentSchema.parse(apiResponse);

Full field docs live in the schema guide. Adapter guides are under adapter guides.

openparser@1 FAQ

Contract versioning, packages, adapters, and model switching.

What is openparser@1?

A versioned document-graph contract for OCR output: document_id, provenance, text, markdown, pages, elements, relations, text_annotations, and assets. Hosted parse responses and local adapters share this shape.

What does @openparser/schema provide?

Zod schemas and TypeScript types for ParsedDocument and related types. Use it to validate API responses, CLI stdout, or adapter output in your own services.

What does @openparser/adapters provide?

Per-provider normalizers under subpaths like @openparser/adapters/paddle and @openparser/adapters/aws-textract. Each adapter maps vendor JSON into openparser@1.

Do I need the adapters if I use the hosted API?

No. OpenParser runs the adapters server-side. Install them when you self-host OCR, run on-prem batch jobs, or need to normalize vendor responses before they hit your pipeline.

Which OCR providers have adapters today?

Paddle HPS, Mistral OCR, Azure Document Intelligence, Google Document AI, and AWS Textract. Each has a dedicated @openparser/adapters subpath.

Will the schema break when I switch OCR models?

Field names stay stable across models. Individual elements may differ in confidence or layout detail, but consumers keep reading the same graph shape.

Docs

Schema docs and adapter guides

Read @openparser/schema types and per-provider adapter docs. Validate local adapter output or hosted API responses with ParsedDocumentSchema.

Read schema docsView API routes