Field Maturity Levels

Field maturity organizes every field in the Field Registry into three levels based on how often the field appears across your documents: Core, Proven and Candidate. These levels were formerly called Canonical, Established and Provisional. Maturity is the platform's primary quality signal, because it tells you at a glance how well-understood and reliable a field is. It also affects extraction cost, since higher-maturity fields can often be resolved by lookup rather than an AI call.

Core fields are the most reliable and cost-efficient. During job runs, Core fields can often be resolved via lookup tables or registry transfer without any AI call, meaning they cost nothing to extract. These are fields like invoice_number, date, or total_amount that appear universally across document types and have well-understood extraction patterns. A registry field is a canonical field at every maturity level: "canonical" names the chosen form of a field name, while Core names the top maturity level.

Proven fields are promoted from Candidate after meeting frequency thresholds. Once promoted, these fields gain a synthesized master instruction and become eligible for lookup-based resolution. They are stable, production-ready fields that recur reliably within specific document types, even if they do not appear across every type the way Core fields do.

Candidate fields are newly discovered and may require a full model call to extract during job runs, making them the most expensive level. As more documents are processed and a Candidate field appears consistently, it is promoted automatically. You can also adjust a field's maturity manually from its inspector in the Field Registry if you know a field is stable enough to promote early, or demote one that was promoted too soon.

Promotion Thresholds

Promotion from Candidate to Proven requires meeting one of two thresholds: 5 occurrences (the field appears in at least 5 documents) or a 10% occurrence rate (the field appears in at least 10% of all documents in your workspace). Promotion is evaluated automatically after every batch resolution run, so fields graduate without manual intervention as your document corpus grows. Once promoted to Proven, a field gains a synthesized master instruction and becomes eligible for lookup-based resolution in job runs.

Filtering by Maturity via API

Query fields by maturity through the public API with GET /v1/fields and the maturity query parameter (core, proven or candidate). An unknown value is rejected with invalid_maturity. The legacy numeric tier parameter (1, 2 or 3) is still accepted for existing integrations, and responses keep the frozen numeric tier field. Filtering by level shows which fields are settled and which are still emerging, which helps you prioritize registry curation. Reviewing Candidate fields regularly, for example, catches misclassifications before they reach job results.

curl "https://api.talonic.com/v1/fields?maturity=candidate" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Legacy equivalent, still accepted:
# curl "https://api.talonic.com/v1/fields?tier=3" ...

{
  "data": [
    {
      "id": "b7c8d9e0-f1a2-3456-bcde-f01234567890",
      "canonical_name": "payment_terms",
      "display_name": "Payment Terms",
      "data_type": "string",
      "tier": 3,
      "maturity": "candidate",
      "cluster_name": "payment_terms",
      "occurrence_count": 7,
      "master_instruction": null,
      "created_at": "2026-05-02T09:15:00.000Z"
    }
  ],
  "pagination": { "total": 41, "limit": 20, "has_more": true, "next_cursor": "ZDFhMmIzYzR8..." }
}

Maturity moves are published as events, so a cached vocabulary can stay current without polling: field.graduated when a candidate is admitted, and field.promoted or field.demoted when a field changes level. See webhook events for payloads, and the field contract for the card and history reads that show a field's current maturity and its curation trail.

Manual maturity adjustments happen in the app, not over the API. Open the field in the Field Registry (under Registry in the sidebar) and use the manual maturity override when domain knowledge justifies an early promotion or a demotion. Promotion evaluation itself needs no manual trigger: after every batch resolution run, the platform checks all Candidate fields against the frequency thresholds (5 occurrences or a 10% occurrence rate) and promotes qualifying fields to Proven. Those fields then receive synthesized master instructions and become eligible for lookup-based resolution in later job runs.