A mapping is a claim about equivalence
Two strings are not canonicalized merely because they are similar. The system makes a narrower claim: for a stated use, the source observation should be represented by one particular concept in the selected taxonomy.
Consider the NAICS description “custom software development for business clients.” It is close in topic to both software publishing and custom programming. NAICS classifies an establishment's primary economic activity, however. Building software to a client's specification supports 541511 · Custom Computer Programming Services; publishing a standard product supports a different concept.
541511513210The unit being classified, record context, taxonomy definitions, and distinctions required downstream all affect that equivalence claim.
source value + record context + taxonomy version → concept ID or ambiguousThe taxonomy defines the valid decision space
A list of short labels is rarely enough. Canonmap preserves source IDs and uses the definitions, aliases, exclusions, examples, and hierarchy that arrive with the taxonomy. Missing evidence remains visibly missing, and repeated display labels do not collapse distinct concepts.
When validated source phrases are available for a concept, Canonmap can represent that concept by the shared center of its official label and those accepted phrases. This is called an evidence centroid. It improves retrieval without rewriting the official label, changing the concept ID, or creating a field customers must edit. It is useful only when evaluation supports it and is not necessarily used by every build.
In the running NAICS example, accepted phrases about software made to a client's specification can strengthen the representation of custom programming, while phrases about publishing a standard product strengthen software publishing. The taxonomy boundary still defines the distinction; the richer representation helps retrieval see it.
Candidate retrieval makes a large vocabulary tractable
Canonmap first resolves exact identifiers and known aliases. It then uses semantic retrieval to rank a small set of plausible concepts from one frozen taxonomy version. For the software example, custom programming and neighboring software concepts can remain visible without asking a large model to inspect the entire taxonomy for every request.
Retrieval has its own failure boundary: if the appropriate concept is absent from the retained set, no later decision stage can select it. Candidate coverage is therefore evaluated separately from final mapping quality.
The decision stage can reject the candidate set
The nearest candidate is not automatically a valid answer. An input can be too general, outside the taxonomy, or missing the detail needed to distinguish close neighbors. Similarity helps retrieve candidates; it is not calibrated confidence.
Under the stable public policy, a calibrated probability of at least 0.50 returns match. A lower value returns ambiguous. If the input is merely “software company,” preserving that uncertainty is more honest than selecting publishing, custom development, or hosting without sufficient evidence.
Coverage is a measured consequence of the decision policy—not a requirement that every row receive a concept.
Evaluation measures what is accepted and what remains unresolved
A useful evaluation population includes direct descriptions, aliases, close siblings, rare concepts, malformed values, ambiguous inputs, and observations that do not belong to the taxonomy. A broad average can hide serious failures in uncommon branches.
Alternatives should be compared on the same frozen rows so improvements and regressions can be counted directly. In a qualified release study, rows used to choose a representation, tune a decision rule, or calibrate probabilities are separated from protected final evaluation rows.
The current public demonstration is more limited: the same generated rows support its provisional calibration and displayed automated-judge diagnostic. That makes the Performance page useful for a consistent build check, but not a protected final evaluation, customer-data accuracy estimate, or human-reviewed concept-ID benchmark. Independent reference data can be added when it exists.
Improvement is delivered as a new mapping build
Canonmap starts with the strongest transparent representation that does not require a learned model. That may be direct official-label retrieval or the more capable evidence centroid. A learned component is considered only when a small, taxonomy-specific tuning search and same-population evaluation show a material, stable improvement over that method.
Why fine-tuning is conditional
Fine-tuning can help, but it also requires representative training evidence, a protected evaluation, additional serving machinery, and ongoing version control. It is not a useful improvement if a richer concept representation already captures nearly all of the gain, or if the remaining benefit is narrow or unstable. Complexity must earn its place through paired error reduction rather than through model size or novelty.
If the incremental evidence is marginal, the simpler method remains. Evaluation does not publish anything by itself: promotion into the selected method and publication as the active build are separate decisions. Customers continue using the same response contract while a qualified release receives a new mapping_build identity.
Customers supply the taxonomy and source values. They are not asked to choose embedding providers, training objectives, model architecture, or similarity thresholds.
Important limitations
- Canonicalization cannot recover context that was never recorded.
- It cannot repair an incoherent taxonomy or silently invent a missing concept.
- It does not prove that two records identify the same real-world entity.
- It cannot make a biased or incomplete source dataset representative.
- Generated and automated-judge evidence does not guarantee performance on a customer's distribution.
- A calibrated ambiguity policy does not prove that every out-of-scope input will be rejected.
Some inputs should remain unresolved. The raw source value and mapping provenance must remain available because a canonical concept is an interpretation under a particular taxonomy and system version—not a replacement for the original observation.