Field Registry

The Field Registry is Talonic's knowledge graph of every canonical field discovered across your documents. As documents are processed, AI discovers fields and resolves them into unified registry entries, so the platform grows smarter with every document: each new document contributes to a shared understanding of field names, data types, and extraction patterns that benefits all future processing.

Open Registry in the sidebar. The page opens on the Field Registry tab, which lists every canonical field in your organization with its maturity status, its evidence across documents, and where it is used downstream. Selecting a row opens the field inspector beside the table, so you can read what a field means and where it came from without leaving the list.

The Summary Strip

A summary strip sits above the table. It shows Total fields and the count at each maturity level: Core, Proven and Candidates. Each level carries a short legend: Core fields occur regularly across documents, Proven fields have been seen across multiple documents, and Candidate fields are still rare. When some documents have extracted values that are not yet bound to canonical fields, the strip also shows an unresolved count, which is the number of documents still waiting for binding. A falling unresolved count is the simplest sign that the registry is keeping up with new documents.

Table Columns and Filters

• Field: the field's display name, with grouped fields folded under their concept. Expand a concept row to see the fields grouped under it.
• Status: the maturity pill (Core, Proven or Candidate), plus a "needs review" marker when the field has an open registry decision.
• Occurrences and Documents: how many times the field was read and in how many distinct documents. A field with no reads yet shows "No evidence yet".
• Used by: how many Specs carry the field, or "Not used yet" when no Spec references it.

Use the search box to filter by name and the status filter to narrow the table to one maturity level. Export CSV downloads the current list for offline analysis. The list and Field Graph views share the same data: the graph is a view mode over the same registry, not a separate store.

Review Registry

The Review registry button opens the merge review, where you check how equivalent field names were merged into one canonical field. The AI Librarian proposes these merges. Its Applied tab lists merges that were applied automatically, and any of them can be Split back apart if two names really mean different things. The Uncertain tab lists pairs the Librarian could not settle, each with its evidence (agreement rate, shared documents, name distance), for you to Accept or Reject. Run AI Librarian starts a fresh pass. On a large registry the run can take a few minutes, and the concepts refresh when it finishes.

The Field Inspector

Select any field to open its inspector. The inspector answers five questions in order: what the field is, where it came from, what it relates to, where it is used, and whether it can be trusted. Each section maps to one of those questions, so a reviewer can confirm a field's definition and evidence in one place before relying on it in a Spec.

• Meaning: a one- or two-sentence description of what the field means. When none is defined yet, the section says so.
• Canonicalization: the variants. These are the other names the field was found under, each with its occurrence count and the name it resolves to.
• Evidence: occurrence and document counts, plus source excerpts with confidence. Each excerpt opens the source document at the exact location.
• Related fields: the concept the field belongs to, fields grouped under the same concept, and similar fields.
• Used in / Used by: the Specs and data products that carry the field.
• Status and review: the maturity level and any open review decision. Change history lists promotions, demotions, merges and renames.

The registry grows automatically as documents are processed. During extraction, AI discovers fields from each document and resolves them against existing registry entries using three-band matching (exact name match, cluster member match, then semantic embedding similarity). New fields that don't match anything create a Candidate entry. Frequently occurring fields are promoted to higher maturity levels, so the registry naturally converges on a stable set of canonical fields over time.

Each registry entry tracks its occurrence count (how many documents contain this field), data type (string, number, date, etc.), synonyms (alternate names discovered across documents), and master instruction (an AI-synthesized extraction directive).

The registry is the foundation for several downstream features. Jobs use registry fields to pre-fill schema values via lookup cascades before resorting to LLM extraction. Semantic clusters group related registry fields together. Generated schemas are auto-built from registry fields that appear in a given document type. Understanding the registry is key to understanding how Talonic reduces extraction cost and improves accuracy over time.

Each registry field maintains two separate embedding vectors: one optimized for resolution matching (based on the canonical name and synonyms) and one for graph visualization (based on name, type, and instruction). This dual-embedding approach ensures that each concern uses the most appropriate representation. The resolution embedding is what powers the three-band matching during document processing, while the visualization embedding drives the Field Graph clustering view.

Browsing the Registry via API

The Field Registry is also readable through the REST API, allowing you to build custom dashboards, export field data for analysis, or integrate registry information into external tools. Use GET /v1/fields to list registry entries with search, maturity (core, proven or candidate) and cluster_id filters. The legacy numeric tier parameter (1 to 3) is still accepted. Use GET /v1/fields/{id} to retrieve a single field along with its 20 most recent occurrences. For agents and integrations that cache vocabulary, the field contract endpoints add GET /v1/fields/resolve?name= (resolve a name to the live concept), GET /v1/fields/{id}/card, GET /v1/fields/{id}/values and GET /v1/fields/{id}/history. Registry changes are published as events: field.graduated, field.promoted, field.demoted, field.merged and field.renamed.

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

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "canonical_name": "vendor_name",
      "display_name": "Vendor Name",
      "data_type": "string",
      "tier": 1,
      "maturity": "core",
      "cluster_name": "vendor_name",
      "occurrence_count": 312,
      "master_instruction": "Extract the supplier's legal entity name from the document header...",
      "created_at": "2026-04-25T14:30:00.000Z"
    }
  ],
  "pagination": { "total": 3, "limit": 20, "has_more": false, "next_cursor": null }
}

curl https://api.talonic.com/v1/fields/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Batch resolution and promotion evaluation run automatically as documents are processed: after each batch resolution run, the platform resolves unresolved field occurrences against the registry and evaluates whether any Candidate fields qualify for promotion to Proven. You do not need to schedule anything; the registry stays current on its own as new documents arrive.

Monitoring Registry Health

A registry health snapshot is available over the public API at GET /v1/registry/health. It returns maturity and admission counts, the singleton and weak-name rates, occurrence and recent-resolution stats, the deterministic transfer hit rate (the share of cells filled with no AI call), and coherence and atomicity metrics. This is the same view the in-app registry dashboard reads, and it is read-only: it exposes no lifecycle or cleanup actions. Teams poll it to track how the knowledge graph matures. A rising transfer hit rate means more extraction resolves for free, while a rising singleton or weak-name rate is an early signal that naming or clustering needs attention.

curl https://api.talonic.com/v1/registry/health \
  -H "Authorization: Bearer $TALONIC_API_KEY"

The Organization Ontology Overlay

The registry learns field names bottom-up from your documents, but you can also seed it top-down with an organization ontology — a versioned overlay of your own document types and field concepts that augments the built-in Talonic ontology. You author the doctypes and fields specific to your domain, anchor each doctype to a Talonic type, and publish. Publishing projects your authored fields into the registry as pinned canonical rows (protected from cleanup) and adds your custom doctypes to the classifier on an organization axis that runs alongside the always-on Talonic axis. The overlay is additive: an empty or unpublished ontology leaves capture and classification identical to the Talonic-only path, so adopting it never regresses existing extractions. The full lifecycle — create, import, update, publish, unpublish, delete, and embedding-assisted mapping to Talonic types — is available over the API under /v1/customer-ontologies.