Stop a missing amount becoming zero by storing two things: a nullable amount and an explicit extraction state. Reserve numeric 0 for a readable zero in the source. Store blank, unreadable and ambiguous amounts as null, preserve their evidence, and block downstream defaults that silently replace them with zero.
The proposed workflow below applies to extracted invoices, expense forms and other financial documents. It prepares records for human review, not payment approval or tax conclusions. The key decision is what the document actually supports, not what number would make the form look complete.
1. Define what each amount state means
Use separate states because “no readable amount” and “an amount of zero” answer different questions.
For this proposed design, use numeric, numeric_zero, blank, unreadable and ambiguous. A numeric state means the relevant field contains one readable, non-zero amount. Numeric zero means it explicitly contains a readable zero. Blank means the field is visible but empty. Unreadable means marks are present but cannot be read reliably. Ambiguous means there is more than one plausible interpretation or conflicting candidate.
Do not classify an absent page or an extraction failure as blank. If the relevant field cannot be located, keep its value null and record a document-level issue such as field_not_located. If the processing request fails, retain a processing error rather than manufacturing field results.
Agree these definitions with the finance reviewer and developer before configuring document processing. For each field, specify the label, expected document area and whether absence is permitted. “Invoice total” and “amount already paid” need separate definitions even when both contain rand values.
2. Make the schema allow missing evidence
Require the amount key, but allow its value to be null. A required key does not have to contain a number.
The proposed field record should contain field_name, state, amount, currency, raw_text, source_ref, issue_reason and review_status. Require every key so that missing values are explicit. Allow null where the source supplies no defensible value. Set state to a fixed list of permitted labels.
Source: OpenAI’s Structured Outputs documentation describes schema-constrained responses and shows nullable fields. That supports the output structure, not the truth of the extracted amount. A schema-valid zero can still be unsupported by the document.
Use application validation for the relationships between fields. For example, numeric_zero must pair with amount: 0; blank must pair with amount: null. Reject mismatches rather than repairing them into zero.
Keep currency separately nullable. Do not assume ZAR just because the recipient is a South African business. A known document convention may justify a currency mapping, but record that rule and have a suitable person approve it.
3. Preserve the source before normalising numbers
Keep the original document reference and field location so a reviewer can inspect the extraction without searching the whole file.
A useful proposed source reference contains the document identifier, version, page and field region. Keep the raw text beside the normalised amount. For a blank field, retain its visible region even though there is no text. For unreadable handwriting, retain the image region and any partial transcription without presenting the transcription as an established amount.
Source: Google’s Document AI overview describes extracting text and layout and returning structured document information. These capabilities can supply inputs to an evidence-preserving workflow; the state rules here remain an application design.
Normalise only after interpreting the field. A hypothetical source reading R 1 250,00 might become 1250.00 under an approved format rule. A dash, crossed-out figure or word such as “nil” needs an agreed interpretation, not a general punctuation-cleaning rule.
Limit access to stored documents and field crops. Retention, permissions and security controls need appropriate human judgement, especially when forms also contain bank details or personal information.
4. Stop zero defaults at every downstream boundary
Carry the state alongside the amount through storage, interfaces and exports. Protecting only the extraction prompt leaves other conversion points unchecked.
Inspect the database column, import mapping, spreadsheet formulas, API payloads and screen controls. Remove proposed mappings such as “if empty, use zero” from the amount path. Avoid checks based only on whether a value is truthy: numeric zero needs to survive as a legitimate value.
In the review screen, display Blank, Unreadable or Ambiguous rather than R0.00 for unresolved fields. Let reviewers open the source region directly. Keep the amount input empty until a supported number is recorded.
If a destination cannot accept null, hold the record in a staging queue. Do not change the meaning of the data to satisfy its interface. An export can carry a separate status column, but the receiving team must agree how to interpret it.
For proposed summaries, report confirmed totals together with unresolved record counts. A sum of readable amounts is not a complete financial total while relevant fields remain unresolved. Make that limitation visible instead of hiding it inside a formula.
5. Use this reusable amount-state contract
Apply one written contract to extraction, validation and reviewer handling so each layer uses the same meanings.
Proposed amount-state contract
| State | Amount | Required evidence | Proposed next step |
|---|---|---|---|
numeric |
Non-zero number | Raw text and field location | Validate format and field match |
numeric_zero |
0 |
Explicit readable zero and location | Validate that zero belongs to this field |
blank |
null |
Visible empty field location | Ask reviewer whether completion is required |
unreadable |
null |
Field image reference and reading problem | Request clearer evidence or manual review |
ambiguous |
null |
Candidate readings and their locations | Reviewer resolves the conflict |
Proposed validation checklist
- Require
field_name,state,amount,currency,raw_text,source_ref,issue_reasonandreview_status. - Reject state/value combinations that contradict the table.
- Keep unknown currency null; do not infer it from the business address alone.
- Keep calculations separate from source-extracted amounts.
- Record missing fields and processing failures as explicit issues, not zeros.
- Hold unresolved records before financial use.
- Log reviewer identity, reason, evidence reference and any corrected value.
- Check that screens, database writes and exports preserve null and zero distinctly.
Completion check: An unresolved field remains null throughout the workflow; a supported zero remains zero; a reviewer can retrieve the evidence for either result.
Assign ownership of this contract to someone who can resolve field meanings, not just change code. When a form layout changes, review its field mappings and examples before extending the workflow. Version the contract so older records retain the interpretation used when they were processed.
6. Route exceptions without inventing amounts
Send uncertain amounts to a review queue with a specific reason and a clear action. “Low confidence” alone does not tell a reviewer what to do.
For a blank required amount, request completion or supporting evidence. For an unreadable amount, request a clearer scan. For conflicting figures, show every candidate and its location. For a missing field, first check whether the wrong document type or an incomplete upload caused the problem.
The reviewer should retain the extracted record and add a correction or resolution alongside it. Record whether the resolution came from the original image, a replacement document or another authorised source. Do not overwrite the original evidence trail.
Source: OpenAI’s function-calling guide explains that the application executes code after a model requests a tool call. Put validation and review controls in that application boundary. A request to save an amount is not permission to bypass them.
For this workflow, ordinary routing may be enough. The AI agents versus automation comparison is useful when deciding whether flexible tool use is necessary. Neither approach should turn an uncertain extraction into automatic financial approval.
7. Evaluate state errors, not just number accuracy
Evaluate whether the complete path preserves meaning, including rejected records and exports. A structurally valid response is only one checkpoint.
Prepare a labelled evaluation set containing readable amounts, explicit zeros, blanks, faint writing, crossed-out entries, missing pages, repeated labels and conflicting copies. Have a knowledgeable reviewer establish the expected state and evidence for each case. Keep difficult examples separate so easy printed amounts do not hide failures.
Measure false-zero conversions specifically: cases where a blank, unreadable or ambiguous field arrives as numeric zero. Also count incorrect blank classifications, lost source references and reviewer corrections. Test the stored record and exported output, not only the model response.
A proposed release gate is no false-zero conversions in the agreed evaluation set, with every unresolved field retaining retrievable evidence. That is a limited acceptance rule, not proof that future errors cannot occur. Continue sampling records and pause the affected path when unsupported zeros appear.
If tool-based exception handling is needed, the custom AI agents workflow resource can inform the design. The custom AI agent glossary entry provides terminology, but adding an agent is not a substitute for validating the amount contract.
Worked walkthrough: readable, blank and conflicting amounts
The expected outcome is a supported value or an explicit unresolved state. All documents and amounts in this walkthrough are hypothetical.
Normal case: An expense form shows R 840.00 in its reimbursement field. The extractor returns numeric, amount: 840.00, currency: ZAR, the raw text and the field location. The validator checks that the text belongs to reimbursement rather than another nearby amount. The record is prepared for the normal human finance review, not payment.
Explicit zero: Another form clearly shows R 0.00 under the same label. It returns numeric_zero with amount: 0. The interface displays the zero and allows the reviewer to inspect its source.
Missing case: A third form has an empty reimbursement box. It returns blank and amount: null. The reviewer asks for completion if that field is required. The export keeps it unresolved instead of supplying 0.00.
Conflicting duplicate case: Two uploaded copies carry the same hypothetical form reference. One shows R 840.00; the other shows R 890.00, with no clear version authority. Retain both source records, flag the business-level amount as ambiguous and leave that resolved amount null. A reviewer identifies the authoritative copy or requests confirmation. Do not select the newer upload merely because it arrived last.
Frequently asked questions
Can we calculate a missing total from readable line items?
You can propose a separate calculated value, but it must not replace the missing extracted total. Store the calculation, its inputs and its derivation separately while keeping the source field null. A finance reviewer must decide whether the calculation is appropriate, including any tax, rounding or adjustment implications. A plausible calculation is not evidence that the document contained that total.
Should a dash or “N/A” become numeric zero?
Not by default. A dash might indicate no entry, not applicable or a deliberate zero, depending on the form convention. Preserve the raw mark and leave the amount null until an approved interpretation applies. If a team proposes mapping particular symbols to zero, document the exact forms and fields covered, obtain appropriate human agreement and evaluate examples before using the mapping.
What if our finance system requires an amount on every row?
Keep unresolved rows outside that import until the value is supported or the receiving system can preserve an unresolved status. Use a staging queue and issue report rather than a zero placeholder in the monetary column. Ask the system owner to confirm the import behaviour. Do not invent an amount simply to pass a required-field check or make a batch balance.
Decide whether the workflow is ready
Proceed only when a blank can travel from document to review screen and export without becoming zero. Confirm that a real zero survives unchanged and that reviewers can retrieve the source for both outcomes.
If your business needs help designing these checks within a wider AI automation workflow, get in touch to discuss the fields, receiving systems and human review boundaries. Any potential reduction in misleading financial fields should be evaluated against your own documents and integration path.