AI invoice reader project · Chapter 3 of 12

The schema

By the end of this chapter you can describe an invoice as Python types with Pydantic (money as Decimal, a real date, limits on every number, fields that must be there even when they are empty), read JSON text into those types with one line per problem when it does not fit, and build the strict JSON schema that chapter 4 sends the model. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: From PDF to data
  • 3 tasks
  • Python
  • In the all labs plan

The first 2 chapters of AI invoice reader project are free. This one comes with the all labs plan.

Why you need this

Chapter 2 gives you an invoice's text. From chapter 4 on, a model reads that text and writes back what it found. Before you ask, you have to say exactly what you want back, and your code has to refuse anything else.

Rafiq's September mistakes show why each field needs a type, not just a name:

  • ₹18,400 typed as ₹14,800. Money has to be a number the code can add and compare to the paisa. A float cannot do that: three tins of sunflower oil at ₹2,160.10 come to 6480.299999999999 as floats.
  • A date typed month first. "08/10/2026" is 8 October to Rafiq and 10 August to a program from another country. A real date written 2026-10-08 has only one meaning.
  • A GSTIN typo that cost a tax credit. When an invoice prints no GSTIN, the reader must say so (null), not leave the field out: a missing field could also mean "forgot to look".

A dict from json.loads checks none of this: a quantity of 0, a total of "Rs. 36,595.12" and an extra key "verified": true all go straight in.

What you build: 3 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    schema.py: an invoice as Pydantic models

    In app/extract/schema.py give LineItem its five fields: description (str, at least 1 character), quantity (Decimal, more than 0), unit (str or None), rate and amount (Decimal, 0 or more). Give Invoice its ten: supplier_name (str, at least 1 character), supplier_gstin (str or None), invoice_number (str, at least 1 character), invoice_date (date), line_items (list of LineItem, at least 1), subtotal, cgst, sgst and igst (Decimal or None), total (Decimal, 0 or more). Every field is required: a nullable one is "X | None" with no default.

    The Check reads a good invoice (money must come back as Decimal, the date as a date) and sixteen bad ones that must all be refused: a quantity of 0, a negative rate or amount, empty text, a missing or extra key, no lines, 30 February, 08/10/2026, "Rs. 36,595.12" and others.

  2. Task 2

    schema.py: JSON text in, an Invoice or its problems out

    Write read_invoice_json(text): return Invoice.model_validate_json(text); when it raises ValidationError, raise InvoiceJsonError(problems) from None, problems being one string per error of e.errors(include_url=False): "<path>: <msg>", the path the error's loc parts joined with dots ("line_items.0.quantity"), or "invoice" when loc is empty.

    The Check reads good JSON, then a quantity of 0, JSON in a code fence, and a total of "lots" with an extra key, and compares your problems with its own.

  3. Task 3 · interview question

    Interview: schema.py, the strict response format

    Write response_format(): {"type": "json_schema", "json_schema": {"name": "invoice", "strict": True, "schema": Invoice.model_json_schema()}}.

    The Check compares it, then walks every object in the schema (the Invoice and the LineItem in $defs): each must say additionalProperties false and list every property in required. Then GET /invoices/schema.

    Kunal will ask: some suppliers print no GSTIN. Why is supplier_gstin still in the schema's required list?

What you will learn

  • Pydantic models: fields as annotated class attributes, checked when data comes in.
  • Decimal for money, and how Pydantic reads JSON numbers into it.
  • Field limits: gt, ge, min_length for text and for lists; nested models; extra="forbid".
  • Required, nullable, default: three different things, and why this schema uses no defaults.
  • Reading JSON text: model_validate_json, ValidationError, errors() and its loc.
  • JSON schema and strict: what model_json_schema() writes, and what a strict structured output demands.

More in From PDF to data

Build The schema yourself

DabbaDrop's kitchens get piles of supplier invoices, typed and messy. You build the pipeline that reads them, checks every number, and sends the doubtful ones to a person. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of AI invoice reader project are free. This one comes with the all labs plan.