How to write a taxonomy for invoice extraction

What is a taxonomy in document extraction?

It is the schema for what you want back. In jextract a taxonomy has a name and a list of fields, and every field has four required parts: an id, a name, a description and a type. Fields can also carry options (for enums), hints and a required flag.

Which field types are there?

The type decides how candidates are cut out of the page and how the chosen span is normalised. A narrower type means fewer, cleaner candidates.

How should I write the description?

The description is the question the model answers, so write it as one plain sentence that separates this field from its neighbours. An invoice has several dates and several amounts; the description is how the right one gets chosen.

• Say whose it is. "The company issuing the invoice (the seller)" and "The company or person being billed (the buyer)" keep supplier and customer apart.
• Say which one. "The final amount payable including tax" is a different field from "The sum of line items before tax and discounts".
• Say when it can be missing. "The buyer's purchase order reference, if any" tells the model that "none" is a fair answer.

What are hints for?

Hints are the words that usually label the value in real documents. "Invoice number" is printed as "Invoice no", "Invoice #" or "Receipt number" depending on the supplier. Listing those helps the field find its line when the document uses different wording from your field name.

What does a working invoice taxonomy look like?

This is a shortened version of the built-in invoice preset. Send it as the taxonomy form field, or pass taxonomy=invoice to use the full twelve-field preset.

{
  "name": "Invoice",
  "fields": [
    { "id": "invoice_number", "name": "Invoice number", "type": "id",
      "description": "The supplier's unique identifier for this invoice",
      "hints": ["invoice no", "invoice #", "receipt number"] },
    { "id": "invoice_date", "name": "Invoice date", "type": "date",
      "description": "The date the invoice was issued",
      "hints": ["date", "issued"] },
    { "id": "supplier_name", "name": "Supplier name", "type": "string",
      "description": "The company issuing the invoice (the seller)",
      "hints": ["from", "vendor", "seller"] },
    { "id": "total", "name": "Total due", "type": "money",
      "description": "The final amount payable including tax",
      "hints": ["total", "amount due", "balance due"] },
    { "id": "currency", "name": "Currency", "type": "enum",
      "options": ["USD", "EUR", "GBP", "INR", "SGD", "other"],
      "description": "The currency the invoice is denominated in" }
  ]
}

What are the common mistakes?

• Using string for everything. A total typed as money is chosen from the amounts on the page; typed as string it competes with every phrase in the chunk.
• Two fields with near-identical descriptions. If you cannot say how they differ in a sentence, the model cannot either.
• Expecting a table. Line items are rows, and this method returns one span per field. Ask for the totals, not the rows.
• Leaving out "other" in an enum. Without it the model has to force a document into one of your options.

How do I check that a taxonomy is working?

Run it on a few real documents in the app and look at the candidates for any field that comes back wrong or with low confidence. If the right value is not among the candidates, the type or the hints need to change. If it is there but lost, the description is not separating it from the others.