Entity Resolution Data Contracts: 7 Rules Before Matching Begins (2026)

TL;DR: An entity-resolution data contract should define field meaning, identifier scope, original and normalised values, null and deletion semantics, event identity, compatible change and quality ownership. It does not force every source into one shape. It gives the resolution layer enough stable meaning to compare deliberately, reproduce a match and reject unsafe input instead of silently guessing.

Test your matching configuration on a controlled data extract. Book a Demo · Try Tilores Studio (Free).

On this page

1. What must an entity-resolution data contract contain?
2. What are the seven rules?
3. A compact contract for identity data
4. Enforce the contract at three boundaries
5. How does the contract preserve meaning through matching?
6. How does a data contract meet the Tilores boundary?
7. FAQ
8. Sources

What must an entity-resolution data contract contain?

A useful contract answers the questions a matcher cannot. Does customer_id identify a person globally, an account inside one source or a relationship that can be recycled? Does an empty address mean unknown, deleted or unchanged? Is a timestamp the moment a fact was observed, written or exported? Two sources can use identical column names while answering different questions. Without those semantics, exact matching can be precisely wrong.

The contract should be readable by source owners, identity engineers and downstream consumers. Machine-readable schema helps enforce shape, but prose examples and named owners establish meaning. The Open Data Contract Standard covers structure, semantics, quality, ownership and server details. Entity resolution adds a particular emphasis on identifier scope, change events and the provenance of values used to infer identity.

Do not treat the contract as a one-off intake document. It is a versioned interface between independently changing systems. A source team may add fields, redefine a status, alter character handling or move from snapshots to events. Each change can affect candidate generation and entity membership even if the pipeline still runs. Contract compatibility therefore includes behavioural tests, not just a parser accepting the new payload.

What are the seven rules?

1. Define business meaning before format. Describe what each identity field represents, when it is captured and which real-world object it belongs to. Include positive and negative examples. A syntactically valid name field can still contain a company, household label or free-text note that should not enter person matching.
2. Scope every identifier. State the issuing system, namespace, uniqueness boundary, lifecycle and whether a value can be reused. Composite keys must list their components. Never assume an ID is global merely because it looks stable inside one export.
3. Retain originals and specify normalisation. Keep source values unchanged for audit and debugging. Define the separate transformations used for comparison, including locale, transliteration, punctuation, address parsing and telephone country context. Version transformations because a new normaliser can change candidates without a new matching rule.
4. Make null, deletion and absence distinct. Say whether an omitted field means unchanged, unknown, not collected, not applicable or intentionally removed. Define tombstones and source-record deletion. Collapsing these states can erase good evidence or preserve data a source intended to withdraw.
5. Give every event an identity and time model. Include event ID, source, type, schema version, subject and observation or effective time. CloudEvents offers a vendor-neutral core vocabulary. Add idempotency and ordering expectations so retries do not create duplicate records or apply old facts after new ones.
6. Version change compatibly. Classify additive, deprecating and breaking changes. Reserve removed identifiers or field numbers where the serialization requires it, as the Protocol Buffers guidance recommends. Test old producers with new consumers and new producers with the supported old consumers before rollout.
7. Name quality ownership and stop conditions. Assign owners for semantics, production and identity interpretation. Define measurable completeness, validity and freshness expectations by source, plus the condition that pauses ingestion or routes records to repair. A warning nobody owns is not a control.

The contract controls meaning and change before a record enters candidate generation or matching.

A compact contract for identity data

The minimum fields below are not a universal schema. They are a review surface. A team should be able to point from each contract statement to a test, an owner and a known failure behaviour. That trace is what turns documentation into an operational boundary.

Contract area	Question to settle	Unsafe default
Field semantics	What real-world fact does the field represent?	Infer meaning from its name or data type.
Identifier scope	Where and for how long is the value unique?	Treat every source ID as a person ID.
Normalisation	Which persisted transformation enters each matcher?	Overwrite originals or change transformations silently.
Update semantics	How are unknown, unchanged, removed and deleted represented?	Map every missing value to null.
Event model	How are retries, order and effective time handled?	Use arrival time as truth and accept duplicate effects.
Compatibility	Which producer and consumer versions interoperate?	Call every additive field harmless without a test.
Ownership	Who resolves semantic and quality incidents?	Send unowned warnings while ingestion continues.

Enforce the contract at three boundaries

At producer build time, validate schema examples and compatibility. At ingestion time, validate payload shape, required semantic metadata, event identity and source-specific quality limits. At resolution time, assert that the fields and transformation versions expected by the active rules are present. These boundaries catch different defects. A payload can pass JSON schema and still be unfit for a matching rule because its identifier namespace is missing.

Choose a safe failure mode for each violation. Quarantine malformed records with a clear source-facing reason. Continue with optional fields only when the rule set has been tested for their absence. Stop a source when a required identifier suddenly collapses in completeness. The aim is not maximum rejection. It is to prevent an unannounced source change from re-partitioning entities while every pipeline dashboard remains green.

Contract metrics should be segmented by source and version. An overall 99 per cent completeness figure can hide one new producer sending an empty key field. Track the distribution of missingness and validity, schema-version adoption, late and duplicate events, and the number of records excluded from each matcher. Connect alerts to a named source owner and a documented recovery path.

How does the contract preserve meaning through matching?

A contract should keep field meaning, identifier namespace and change semantics close to the values they govern. Record both original and normalised forms so a matcher can compare consistently without erasing the source observation. When a producer changes a field, the contract version identifies whether the payload is compatible, must be quarantined or requires a migration.

Null, empty, absent and deleted are separate states. Collapsing them can create false agreement or preserve a value after the source withdrew it. The event identity, effective time and deletion rule therefore belong in the contract alongside schema type and format.

Contract evidence includes the producer, owner, version, validation result and safe-failure action. Attach that evidence to the ingested record and the resulting identity decision so a later correction can distinguish bad source meaning from a bad matching rule.

How does a data contract meet the Tilores boundary?

We model records as nodes and matching relationships as edges. Before submission, the adapter should validate the source contract and map accepted fields into the configured GraphQL schema. Our rules can then combine deterministic, fuzzy and probabilistic methods without having to guess what an identifier or missing value means.

We submit, search and query resolved data through GraphQL. That API boundary is also the right place to retain source identity, event identity and contract version while limiting each consumer to its authorised view. A rejected payload should keep a clear owner and retry condition rather than being silently coerced into the entity graph.

The end-to-end rollout guide covers the wider source onboarding sequence. For this contract, the proof is narrower: incompatible changes fail safely, accepted records remain reproducible, and an owner can trace any entity defect back to the precise source meaning and contract version involved.

Frequently asked questions

Must every source use the same schema?

No. Sources can keep different structures when their meaning and mapping are explicit. The contract makes those differences deliberate and testable before comparison.

Should normalisation happen upstream?

It can, but the identity system still needs the original value, transformation definition and version. Persisting both makes the exact matching input reproducible.

Who owns the contract?

Source owners own the meaning and production of their fields. The identity team owns cross-source interpretation and matching tests. A named joint escalation path handles ambiguity.

Is an added optional field always backward compatible?

Not necessarily. It may change transformation selection, candidate generation or consumer behaviour. Compatibility is an observed property established by tests, not a label inferred from syntax alone.

What should happen when a contract breaks?

Apply the documented stop, quarantine or degraded mode, notify the named owner and preserve affected events for controlled replay after correction. Do not silently coerce the payload into a guessed meaning.

Sources

1. Linux Foundation: Open Data Contract Standard. Machine-readable structure, semantics, quality, ownership and server expectations.
2. UK Government Data Quality Framework. Data quality ownership, communication and lifecycle controls.
3. Protocol Buffers: Programming Guide. Compatible schema evolution and reserving removed fields.
4. CloudEvents specification: JSON format. Required event identity, source, version and type attributes.
5. Tilores documentation: Rules Configuration. Product-specific rule, transformation, matcher and simulation behaviour.
6. Tilores documentation: Matcher Reference. Deterministic, fuzzy and probabilistic matcher mechanics.
7. Tilores documentation: API. GraphQL operations and the entity event stream.
8. Tilores: What an Entity Resolution Rollout Actually Looks Like in 2026. Internal context on labelled truth, parallel running and operational ownership.

Scope note: examples are implementation patterns. Teams should adapt retention, access and change controls to their own legal and operational requirements.