Epic 1 · The timetable becomes data

Putco Payload v1

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.

Schema version
1
Content version
2024-07.v1
Payload size
2 405 bytes
sha256
2d42f8ea…47b49
Contents
3 places · 1 trip

The payload document

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.

payload-2024-07.v1.json schemaVersion 1
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.

What the diagram alone does not say

The manifest

A separate document, so a reader learns what is current — and whether it can parse it — without downloading the payload first.

manifest.json manifestSchemaVersion 1
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
    }

JSON to C#

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.

Payload/PayloadModel.cs unless noted
JSONC# typeNotes
payload rootPayloadDocumentSchema version distinct from content version
sourceSourceDescriptorNamed once, referenced by id everywhere else
licences[]LicenceCarries the unresolved C9 position as data
places[]PlaceEmitted in registry order
places[].coordinateCoordinate?Null until story 1.5; absence is counted, not silent
*.provenanceProvenanceOn every assertion — place, trip and scheduled departure
provenance.confidenceConfidenceClosed ladder, validated on construction
trips[]TripFeeder marker preserved as its own attribute
trips[].legs[]LegOrdered; length 1 at launch, readers must not assume it
legs[].scheduledScheduledLocal wall clock; the source carries no zone
manifest rootManifestDocumentPayload/Manifest.cs
current, superseded[]ManifestEntryPayload/Manifest.cs

Where the ids come from

Looked up, never computed
RegistryTypeNatural 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.

Not in v1 yet

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.

Ordered by the story that delivers it
StoryMissingWhy 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

One inconsistency to know about

gzippedBytes disagrees between the checked-in golden manifest and pipeline output. A compressed size is a property of the compressor, not of the payload:

  • gzip −1 → 776
  • gzip −6 → 710 (the fixture)
  • gzip −9 → 703
  • .NET Optimal → 687 (the pipeline)

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.