Epic 1 · The timetable becomes data
The entity shape of payload-2024-07.v1.json as actually published, and the
records that emit it. The architecture spine holds the conceptual model for the whole
initiative; this is what schema version 1 contains, which is deliberately a subset.
One hand-picked trip carries the full envelope, so story 1.8 extends a pattern rather than
retrofitting one: route 0070-0088, shift 9159, Mon–Fri,
departing 16:15 from 4 Ways Mall to Emdeni via Emmarentia.
erDiagram
PAYLOAD ||--|| SOURCE : "describes itself by"
PAYLOAD ||--o{ LICENCE : carries
PAYLOAD ||--o{ PLACE : contains
PAYLOAD ||--o{ TRIP : contains
PLACE ||--o| COORDINATE : "has, or states absence"
PLACE ||--|| PROVENANCE : asserts
TRIP ||--|{ LEG : "ordered list of"
TRIP ||--|| PROVENANCE : asserts
LEG ||--|| SCHEDULED : departs
SCHEDULED ||--|| PROVENANCE : asserts
LEG }o--|| PLACE : "originPlaceId"
LEG }o--|| PLACE : "destinationPlaceId"
LEG }o--o{ PLACE : "viaPlaceIds"
LICENCE }o--|| SOURCE : "sourceId"
PROVENANCE }o--|| SOURCE : "sourceId"
PAYLOAD {
int schemaVersion "contract version"
string contentVersion "which timetable"
}
SOURCE {
string id PK "greater-soweto-timetable-2024-07"
string title
string kind "published-timetable"
string asOf "ISO-8601"
}
LICENCE {
string applies "what it governs"
string sourceId FK
string status "unsettled - C9 is open"
string note
}
PLACE {
string id PK "PL-NNNN, registry-minted"
string name
string_array aliases "inline in JSON"
object coordinate "null until story 1.5"
string coordinateStatus "absence is stated"
}
COORDINATE {
double latitude
double longitude
}
TRIP {
string id PK "TR-NNNN, registry-minted"
string routeCode "NNNN-NNNN verbatim"
string shiftNumber "never conflated"
string dayTypeCategory "recorded, not resolved"
bool isFeeder "never canonicalised away"
}
LEG {
int index "0-based, ordered"
string originPlaceId FK
string destinationPlaceId FK
string_array viaPlaceIds FK
}
SCHEDULED {
string departureLocalTime "HH:MM, no zone in source"
string timeZone "Africa/Johannesburg"
}
PROVENANCE {
string sourceId FK
string asOf
string confidence "closed ladder"
int sourceRow "trip only"
}
Scroll the panel sideways on a narrow screen. Relationship notation is Crow's foot:
|| exactly one, o| zero or one, |{ one or more,
o{ zero or more.
originPlaceId; it never embeds the place. That is what lets
a payload this small avoid repeating a place for every trip that touches it — and why ids
are load-bearing rather than cosmetic.
A separate document, so a reader learns what is current — and whether it can parse it — without downloading the payload first.
erDiagram
MANIFEST ||--|| CURRENT : names
MANIFEST ||--o{ SUPERSEDED : lists
CURRENT ||..|| PAYLOAD : "path and sha256 describe"
MANIFEST {
int manifestSchemaVersion
}
CURRENT {
string contentVersion
string path "payload-yyyy-mm.vN.json"
int payloadSchemaVersion "readable without parsing payload"
long bytes "measured from bytes written"
long gzippedBytes "compressor-specific"
string sha256 "measured from bytes written"
}
SUPERSEDED {
string contentVersion
string path
}
Every type is a sealed record. The confidence ladder is closed: a value off it
is refused in the Provenance constructor rather than written out.
| JSON | C# type | Notes |
|---|---|---|
| payload root | PayloadDocument | Schema version distinct from content version |
| source | SourceDescriptor | Named once, referenced by id everywhere else |
| licences[] | Licence | Carries the unresolved C9 position as data |
| places[] | Place | Emitted in registry order |
| places[].coordinate | Coordinate? | Null until story 1.5; absence is counted, not silent |
| *.provenance | Provenance | On every assertion — place, trip and scheduled departure |
| provenance.confidence | Confidence | Closed ladder, validated on construction |
| trips[] | Trip | Feeder marker preserved as its own attribute |
| trips[].legs[] | Leg | Ordered; length 1 at launch, readers must not assume it |
| legs[].scheduled | Scheduled | Local wall clock; the source carries no zone |
| manifest root | ManifestDocument | Payload/Manifest.cs |
| current, superseded[] | ManifestEntry | Payload/Manifest.cs |
| Registry | Type | Natural key |
|---|---|---|
| places.seed.registry.json | PlaceRegistry | Name, plus any recorded alias |
| trips.seed.registry.json | TripRegistry | routeCode, shiftNumber, originPlaceId, destinationPlaceId, dayTypeCategory, sequence |
The trip key excludes departure time on purpose: correcting a mistyped time changes an attribute and never re-keys the trip, so a rider report attached to it is never orphaned.
Schema version 1 is the tracer bullet's shape, not the finished contract. Adding any of these is a schema version change where a reader's accepted range would break, and a content version change otherwise — the two are separate so this stays decidable.
| Story | Missing | Why it matters |
|---|---|---|
| 1.6 | Day-type precedence table | dayTypeCategory is recorded, but nothing resolves the overlap between Mon–Fri, Mon–Thur and Friday |
| 1.6 | Public holidays + validity range | Without it there is no no-assertion-public-holiday outcome, and no way to say the list has expired |
| 1.7 | Corridor graph | viaPlaceIds exists, but nothing yet forms corridors from it |
| 1.8 | Payload-declared tunables | Get-ready 15 min, walk 10 min, the already-passed grace window, report lifetime and the rider-signal caps — no surface may invent these |
| 1.8 | Attribution and ODbL metadata | licences[] carries the C9 position but not OpenStreetMap attribution, which arrives with coordinates |
| epic 4 | Reports and stop confirmations | Never in this payload — the overlay is read-time and never mutates the base |
gzippedBytes disagrees between the checked-in golden manifest and pipeline
output. A compressed size is a property of the compressor, not of the payload:
So the manifest reports what it measured and the test recomputes it, rather than asserting
a literal. The payload's own bytes and sha256 are
asserted against the fixture, and match exactly. Settle this before any story asserts
whole-manifest equality.