Technical guide
Source-aware data systems
A source-aware system preserves record origin, change history, freshness, and the evidence supporting each interface claim or request.
Ingestion is an evidence boundary
An ingestion path should identify the source, collection time, source record identity, visibility classification, and validation result. It should preserve the original evidence needed to trace a normalized record without exposing data beyond its intended audience.
Normalize without erasing provenance
Normalization gives downstream systems stable fields and types. It should retain source identifiers, mapping version, transformation result, and ambiguity notes so a clean interface does not hide disagreement or loss of meaning.
Model freshness and unknown state
Fresh, stale, unavailable, conflicting, and unknown are distinct states. A missing refresh or failed source should not become a fabricated current value. Interfaces need a way to return the state, not only a value.
Publish interface contracts
A contract states accepted input, returned fields, source meaning, error behavior, versioning, and whether the operation is read-only or consequential. Clear contracts let an SI layer cite and validate data instead of inferring hidden semantics.
- Stable record identity
- Freshness and source reference
- Declared error and unknown states
- Read or action boundary explicit
Example: inventory availability
A product-data interface should show the scope and age of an availability observation, preserve its record identity, and distinguish missing values from confirmed zero stock. A historical catalog record establishes its original observation; current purchase availability requires current source evidence. Source-aware interfaces preserve these distinctions through search, APIs, and operational review.