Skip to main content

Calculated Fields

Calculated fields let you derive new values from extracted fields directly in your schema.

Use this when:

  • You want deterministic totals (for example subtotal + tax).
  • You want validation-ready output without client-side math.
  • You want the same formula logic reused across jobs and configurations.

How It Works​

  1. Your schema includes normal extraction fields and calculated fields.
  2. During extraction, calculated fields are removed from the schema sent to the LLM.
  3. After extraction, formulas are evaluated and calculated fields are added to the result.

This means calculated fields are always computed from extracted output, not generated by the LLM.

Schema Format​

Each calculated field is a normal property with an x-docudevs extension:

{
  "type": "number",
  "x-docudevs": {
    "fieldType": "calculated",
    "dependsOn": ["net_amount", "vat_rate"],
    "formula": {
      "lang": "excel",
      "expression": "ROUND({net_amount} * (1 + {vat_rate}), 2)"
    }
  }
}

Full Example​

{
  "type": "object",
  "properties": {
    "net_amount": { "type": "number" },
    "vat_rate": { "type": "number" },
    "gross_amount": {
      "type": "number",
      "x-docudevs": {
        "fieldType": "calculated",
        "dependsOn": ["net_amount", "vat_rate"],
        "formula": {
          "lang": "excel",
          "expression": "ROUND({net_amount} * (1 + {vat_rate}), 2)"
        }
      }
    }
  },
  "required": ["net_amount", "vat_rate", "gross_amount"]
}

gross_amount can be included in required. It is automatically removed from the extraction schema before the LLM call and computed afterward.

Formula Syntax​

  • Reference fields with placeholders: {field_name}
  • Nested references are supported: {parent.child}
  • lang is currently excel

Supported operators:

  • Arithmetic: +, -, *, /, %, ^
  • Comparison: ==, !=, <>, >, >=, <, <=
  • Boolean: AND, OR, NOT

Supported functions:

  • ROUND(value, digits)
  • ABS(value)
  • IF(condition, when_true, when_false)
  • SUM(...)
  • MIN(...)
  • MAX(...)
  • AVERAGE(...)
  • AND(...)
  • OR(...)
  • NOT(value)
  • COALESCE(...)

Constants:

  • TRUE, FALSE, NULL

Dependency Behavior​

  • dependsOn should list fields used by the formula.
  • If a dependency is missing or empty, calculated field value becomes null.
  • Calculated fields can depend on other calculated fields.
  • If formula evaluation fails, the calculated field is set to null.

Finnish Autovero Example​

This example computes laskettu_verotusarvot_yhteensa from two extracted fields:

{
  "type": "object",
  "properties": {
    "ajoneuvon_perushinta": { "type": "number" },
    "varusteiden_verotusarvo": { "type": "number" },
    "verotusarvot_yhteensa": { "type": "number" },
    "laskettu_verotusarvot_yhteensa": {
      "type": "number",
      "x-docudevs": {
        "fieldType": "calculated",
        "dependsOn": ["ajoneuvon_perushinta", "varusteiden_verotusarvo"],
        "formula": {
          "lang": "excel",
          "expression": "ROUND({ajoneuvon_perushinta} + {varusteiden_verotusarvo}, 2)"
        }
      }
    }
  }
}

Using With SDK / API​

import json
from docudevs.docudevs_client import DocuDevsClient

client = DocuDevsClient(token="YOUR_API_KEY")

schema = {
    "type": "object",
    "properties": {
        "net_amount": {"type": "number"},
        "vat_rate": {"type": "number"},
        "gross_amount": {
            "type": "number",
            "x-docudevs": {
                "fieldType": "calculated",
                "dependsOn": ["net_amount", "vat_rate"],
                "formula": {
                    "lang": "excel",
                    "expression": "ROUND({net_amount} * (1 + {vat_rate}), 2)"
                }
            }
        }
    }
}

job_guid = await client.submit_and_process_document(
    document=open("invoice.pdf", "rb").read(),
    document_mime_type="application/pdf",
    prompt="Extract net amount and vat rate as numbers.",
    schema=json.dumps(schema),
)

result = await client.wait_until_ready(job_guid, result_format="json")
print(result["gross_amount"])