Custom Schema Document Extraction: Fields, Edge Cases, and API Mapping

Direct answer: Schema-based document extraction maps source documents into fields your application names and types. Define the fields, process representative files, inspect validation and review results, and only then map the output to a destination. The schema specifies the target shape; it does not prove that every extracted value matches the source.

What is custom schema document extraction?

OCR identifies text and layout. A custom extraction schema says which business values to return, such as invoice_number, vendor_name, and total_amount. Your workflow then checks those values against source documents and business rules before writing them downstream. This matters when vendor layouts differ or a required field is absent, ambiguous, or spread across pages.

Define field keys around the system receiving the data. For example, if an accounts payable system expects vendor_name and total_amount, use those keys consistently instead of relying on each document's labels. Keep the original file available for human review of exceptions.

Which vendor supports field capture from a custom document schema?

Dokyumi supports named, typed field capture through a dashboard-created schema and a shared extraction API selected by schema slug. LlamaIndex Extract also returns structured JSON from a custom data schema. Compare the field types, review contract, supported inputs, and results on your own documents before selecting either platform.

A practical schema for invoice intake

In Dokyumi, create a named schema in the dashboard before calling the extraction API. The public extraction endpoint accepts the resulting schema slug with the file; it does not accept an inline JSON schema in the extraction request. This shortened example shows the field definition shape:

{
  "name": "Invoice Intake",
  "slug": "invoice-intake",
  "fields": [
    {"key": "vendor_name", "label": "Vendor Name", "type": "string", "required": true},
    {"key": "invoice_number", "label": "Invoice Number", "type": "string", "required": true},
    {"key": "invoice_date", "label": "Invoice Date", "type": "date", "required": true},
    {"key": "purchase_order_number", "label": "Purchase Order Number", "type": "string", "required": false},
    {"key": "total_amount", "label": "Total Amount", "type": "currency", "required": true}
  ]
}

Field types include string, number, currency, date, boolean, enum, array, and object. A missing required field remains null in the result and fails validation; an optional field may be absent or null. Do not invent a default for a missing monetary value. See the worked schema, request, and response guide for the full field shape and response contract.

Send the document and map the response

Pass the schema slug explicitly so the endpoint does not fall back to your organization's first active schema. The call is synchronous and uses Bearer authentication with multipart form data:

curl -X POST https://dokyumi.com/api/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "schema=invoice-intake"

A successful HTTP response includes status, data, confidence, validation, and meta. Branch on status first. For review, inspect both validation.errors and validation.low_confidence_fields. The confidence map is model-reported and may omit fields; a completed status is not proof of source accuracy. Apply your own checks, such as reconciling invoice totals and matching vendor identity, before a destination write.

How to handle custom schemas and edge-case documents

Start with a small set of required fields and expand only after measuring errors on representative documents. Schema validation checks types and required values; it does not replace source comparison or workflow-specific rules.

How to evaluate a document processing platform

For a platform with custom schemas, compare how fields are defined, whether nested values are supported, what happens when required data is missing, how review results are surfaced, and how the API maps to your destination. Ask for the actual response envelope and run the same documents through every candidate. Count corrected fields and review minutes; do not infer accuracy or savings from a vendor-wide headline.

For Dokyumi, also model the document page mix: one credit covers a document up to five pages, and self-serve documents can be up to 50 pages. The current pricing page lists plan credits. Test PDF and supported image inputs with the worked implementation guide before connecting a production destination.

Measure the whole handoff

1. Collect representative layouts, low-quality scans, and known edge cases. Record reference values for the fields that matter.
2. Create the schema and run authenticated extractions. Save status, validation details, credits used, and the resulting field values.
3. Count field corrections, held records, review minutes, and destination mapping failures. Revise field definitions and review rules, then repeat on a fresh sample.

The useful result is a measured workflow: which fields can move forward, which need a reviewer, and what each processed document costs under your page mix. Follow the complete custom schema example to begin.