Skip to main content

JSON extraction

Reads the submitted document and extracts its data into a JSON with the format you define: an invoice's number and date, a supplier's details, the lines of a table, and so on. Wired to the JSON output, it turns the pipeline into an extraction portfolio, which returns that JSON instead of an annotated document.

A minimal extraction portfolio is wired like this:

Document to annotate → JSON extraction → JSON output

A Page filter can sit before the node, for example to read the first page only. A Switch can route each document type (invoice, purchase order…) to an extraction node with its own format.

Ports​

  • Input (left, content type): the document. A single incoming edge.
  • Output (right, JSON type): connects only to the JSON output.

Configuration​

  • AI model: the model that reads the document. Models with structured output (OpenAI, Anthropic, Gemini, recent Ollama, most OpenAI-compatible servers such as LM Studio) give the most reliable results. For image reading, pick a model that reads images (see below).
  • Document reading:
    • Extracted text: the text produced by the document parser. Works with every model and is the cheapest.
    • Page images: each page is sent as an image to a vision model. Better on complex tables, multi-column layouts, scans and photos (accepted formats: PDF and JPG, PNG, TIFF, BMP images).
    • Text + images: the text and the image of each page. The image prevails for structure (tables, columns), the text for the exact spelling of identifiers and amounts.
  • Guidance: what to identify and extract, and how. For example the expected document type, special cases (« ignore subtotal lines ») or which value to keep when there are several (« use the due date »).
  • JSON format: the fields to fill, edited in the builder (Edit the JSON format button).

The JSON format builder​

Each field has:

  • a name, which becomes the JSON key (letters, digits and _, no leading digit);
  • a type: Text, Number, Integer, Yes / no, Date, Choice (list of allowed values), Group (fields bundled together) or List (one element per occurrence);
  • a description, required. It is what tells the model what to look for, where, and in which form, e.g. « Invoice number, top right (e.g. F-2024-001) »;
  • a Required box: when the field is not found, the result is flagged non-conforming.

The Table of lines button directly creates a list whose elements are groups of fields, for example an invoice line with its label, quantity and amount.

The preview on the right shows a sample output and the matching JSON Schema. The format can be exported as a JSON Schema, and an existing JSON Schema can be imported (objects, arrays, simple types, dates, enumerations, descriptions, required fields, $defs references). Whatever is not carried over is reported after the import.

Advanced settings​

  • Page splitting:
    • Automatic (default): the document goes in a single call when it fits the model's context window, otherwise it is processed in successive page windows;
    • Whole document in one call;
    • Always by page windows.
  • Pages per window: cap on the number of pages sent together. When empty, the window size is computed from the model's context window (Admin → AI models). For image reading, at most 8 pages per call.
  • Correction passes (default 2): how many times a non-conforming JSON is sent back to the model with the list of deviations. 0 disables correction. Each pass is billed.
  • Numbers and dates: settles normalisation ambiguities. « 1,234 » is 1.234 in French and 1234 in English; « 03/04/2024 » is April 3rd in French and March 4th in English.
  • Image size (image reading): longest side of the pages sent, 1568 px by default.

How the JSON is guaranteed​

  1. Provider structured output. The format is passed to the model as an enforced schema: constrained decoding with Ollama, strict mode with OpenAI and compatible servers, tool calling with Anthropic. If the provider refuses that mode, the node falls back to a text instruction and extracts the first JSON object of the answer.
  2. Normalisation. « 1 234,56 € » becomes 1234.56, « 14/03/2024 » becomes 2024-03-14, « Yes » becomes true, a choice value is brought back to its exact case. Unknown keys are removed and missing keys added (null, empty list).
  3. Check and correction. The result is validated against the format. On a deviation (wrong type, empty required field, unreadable date…), the deviations are sent back to the model, which corrects them, within the correction-pass limit.
  4. Verdict. Whatever still deviates is returned as is with valid: false and the list of deviations, rather than failing silently.

Multi-page documents​

When the document does not fit in one call, it is read in consecutive page windows. Each window receives what was already extracted: the values already found, and for each list its number of elements and its last element. A table cut by a page break therefore continues without duplicates. The results are then merged:

  • a simple field keeps the first value found. A different value found later is reported as a conflict;
  • lists are concatenated in page order. Only a line repeated where two windows meet is removed;
  • required fields are checked on the merged result.

When the model's answer is too long and gets truncated, the window is split in two and read again.

Interceptors and image reading​

Interceptors only filter text: data cannot be masked on a page image. When reading Page images or Text + images:

  • interceptors run on each page's text layer; a page without text (scan, photo) is OCR'd for this check only;
  • if a masking interceptor fires, the job is blocked and no image is sent. A blocking interceptor blocks as usual;
  • if a page cannot be read for this check, the job is blocked too.

When reading Extracted text, interceptors mask the text as they do for an agent.

Limits​

  • Image reading applies to PDFs and images. A Word, PowerPoint, Excel or OpenDocument file is read from its extracted text, with a warning in the logs.
  • When reading images, the Page filter counts physical pages, blank pages included.
  • A Switch classifies the document from its text: on a scan or a photo without text, it takes the default route.