Core concepts
Observations, conflicts and provenance
Canonical rows are derived from observations by policy — never hand-edited. A correction is just another observation from a source ranked to win.
An observation is what one source said about one entity at one time: {source, type, external_id, observed_at, confidence, data}. Observations are never updated and never deleted; they are the evidence the canonical model is derived from, and every payload is kept raw before anything parses it.
Who wins a field
When two sources describe the same field of the same entity, authority rank decides; recency breaks ties within a rank; the source’s own confidence breaks what remains. A public source’s kickoff time never overwrites the host’s push — but its field number fills a gap the host left empty.
| Rank | Source class | Example |
|---|---|---|
| 1 | Authoritative push | The host platform's feed |
| 2 | Partner API | A platform we poll |
| 3 | Host feed | iCal or CSV the club publishes |
| 4 | Owner correction | A club admin marks a game cancelled |
| 5 | Public source | Schedules published openly across the long tail |
| 6 | Crowd | A parent reports a score |
Provenance is part of the API
Every canonical field stores the observation that won it: the source, when it was observed, and at what confidence. Consumers see it on every fixture. Cancellations and postponements never delete — status changes, an event fires, and delta sync catches anyone who missed it.