Skip to main content

Field Matching

Field matching is how Talonic maps each field you add to a schema template against the Field Registry. Exact name matches are applied instantly, while semantic and composite matches appear as suggestions for your confirmation. If no match is found, the field is marked Unmapped and you should provide a manual extraction instruction so the AI knows how to extract that value from your documents.

Match types

ParameterTypeDescription
ExactautoField name directly matches a canonical registry field.
SemanticAIAI finds an equivalent field with a different name.
CompositeAIMultiple registry fields combine to derive this field.
UnmappedmanualNo match found — needs manual extraction instructions.

The matching engine uses a three-band resolution process under the hood. First, it checks for an exact name match against canonical registry field names and their synonyms. If no exact match is found, it computes embedding similarity between your field name and every registry field, surfacing semantic matches above a 0.5 confidence threshold. Matches above 0.8 are auto-accepted; those between 0.5 and 0.8 require your confirmation.

Matched fields inherit the registry's AI-synthesized master instruction, which tells extraction exactly how to locate and extract that value from documents. This is why matching matters — a well-matched field leverages all the intelligence the system has built up from processing your document corpus. Unmapped fields rely solely on your manual instruction, so they may need a few correction cycles before reaching the same accuracy.

You can trigger a Rematch on all fields at any time from the template editor. This is useful after the registry has grown — fields that were previously unmapped may now find matches as new extractions contribute to the registry. For best results, use descriptive field names that reflect the actual data (e.g., contract_start_date rather than field_1).

List fields in the Field Registry
# ?maturity=core|proven|candidate (the legacy ?tier=1|2|3 is still accepted)
curl -s "https://api.talonic.com/v1/fields?maturity=core&limit=20" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "data": [
#     {
#       "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
#       "canonical_name": "invoice_number",
#       "display_name": "Invoice Number",
#       "data_type": "string",
#       "tier": 1,
#       "maturity": "core",
#       "cluster_name": "invoice_number",
#       "occurrence_count": 342,
#       "master_instruction": "Extract the unique invoice identifier..."
#     }
#   ],
#   "pagination": { "total": 156, "limit": 20, "has_more": true, "next_cursor": "ZDFhMmIzYzR8..." }
# }

Rematching is particularly useful after bulk document ingestion. When a large batch of new documents introduces previously unseen fields into the registry, running a Rematch on your templates can upgrade unmapped fields to exact or semantic matches without any manual configuration. The template editor summarizes how many fields changed status, so you can quickly assess whether the rematch had a meaningful impact on your template coverage. Browsing the registry over the API (above) helps you choose field names that will match: naming your template field after an existing canonical name guarantees an exact match.

Field matching is read-only against the registry — it never creates new registry entries. If no match exists, the field stays unmapped until you provide a manual instruction or new documents introduce the field into the registry.

Field matching is easiest when you know what the registry holds. Open Registry in the sidebar to browse the Field Registry: each row shows a field's Status (Core, Proven, or Candidate), how often and in how many documents it occurs, and which Specs already use it. Selecting a field opens an inspector with its meaning, the source evidence behind it, where it is used, and related fields. Naming your template field after a Core field's canonical name is the most reliable way to get an exact match.

Frequently asked questions

How does field matching work in Talonic schemas?+
Schema fields are matched to the registry using a three-band resolution process. First, exact name matching against canonical names and synonyms. Then, embedding similarity for semantic matches (auto-accept above 0.8, confirm between 0.5 and 0.8). Four match types result: Exact (direct name match), Semantic (AI finds equivalent field), Composite (multiple fields combine), and Unmapped (no match, needs manual instructions).
What happens when a field is unmapped?+
Unmapped fields have no registry match and do not inherit a master extraction instruction. They require manual extraction instructions to guide the AI on how to extract the value from documents. Write clear, specific instructions describing where in the document to look and what formatting to expect for best results.
Can I re-run field matching after adding more documents?+
Yes. Use the Rematch button in the template editor to re-run matching against the current registry. Fields that were previously unmapped may find new matches as your registry grows through processing additional documents. For best results, use descriptive field names that reflect the actual data rather than generic labels.
What confidence threshold determines automatic vs manual matching?+
Matches above 0.8 confidence are auto-accepted — these are near-certain semantic equivalents. Matches between 0.5 and 0.8 appear as suggestions requiring your confirmation before they are applied. Matches below 0.5 are rejected and the field is classified as unmapped. You can adjust individual match decisions from the template editor at any time.
Which registry fields make the best match targets?+
Core and Proven fields. They recur across many documents, so their master instructions have been refined on real data and their values resolve reliably. Candidate fields can still match, but they are newer or rarer, so expect to review their output more closely.
Does a rematch change fields that are already matched?+
A rematch re-evaluates your template fields against the current registry, so a previously unmapped field can gain a match after new documents have been processed. The template editor summarizes how many fields changed status so you can check the effect before relying on it.

Related

Field Registry
Schema Features Reference
Semantic Clusters