Data Contracts, Validation, and Schema Changes
Explore how data contracts catch bad or changed data before it reaches a client's systems. Learn how to validate records at the boundary, quarantine rejected revisions, and handle schema versions that change meaning without changing shape. Understand how versioned interpretations keep replay predictable and what evidence makes a mapping change safe.
We'll cover the following...
- Does duration: 120 mean 2 hours or 120 hours?
- The worker, entry, and fields being mapped
- What makes an E41 update acceptable
- Where rejected revision 7 goes
- What changes when Time v2 arrives
- Which interpretation replay should use
- Evidence that makes a mapping change safe
- Practice: Deriving Fen Water’s contract from its own facts
Two records both say duration: 120; do they represent the same amount of work? For Bracken Services, answering requires the source version, units, and business meaning before any payroll write. A data contract makes those interpretations explicit so validation, mapping, and approved replay produce defensible results.
Does duration: 120 mean 2 hours or 120 hours?
Bracken’s Time source v1 and payroll staging use these field meanings:
{"system":"Time","schema_version":"v1","duration":120,"status":"APPROVED"}{"system":"Payroll staging","duration":120,"status":"PAID"}
The Time record describes 120 minutes eligible for export. The payroll record describes 120 hours with payment completed. Copying matching names would multiply worked time by 60 and falsely assert payment.
A safe mapping preserves business meaning through an explicit, versioned interpretation. Bracken’s integration stages approved time; it does not execute payments.
The worker, entry, and fields being mapped
A mapping contract specifies source and destination meanings, field-level authority, units, enumerations, reference mappings, and conflict policy. Bracken’s contract includes:
Worker crosswalk:
(B1, Time, W17)maps to(B1, Payroll, P804).Entry identity:
(B1, Time, E41)identifies the time entry.Project crosswalk: Source project
P9maps to payroll projectJ22.Time authority: Worked duration, project, approval, and entry revision.
Payroll authority: Payment status and payment references, which are read-only to this integration.
Scope identifiers by tenant and source system. Email and display names are descriptive and mutable; they cannot establish identity. An unresolved crosswalk or ownership conflict becomes an exception rather than a guessed match or overwrite.
As established earlier in this chapter, keep entity, operation, and attempt identities distinct; retries retain the operation identity.
Bracken chooses canonical contract c1 with tenant, entry identity, worker identity, source revision, duration_hours, project reference, cost center, and eligibility. A ...