RFC-002 — Mission JSON schema: events array, field canonicalisation

Status · Closed · superseded by ADR-020 TA anchor · §contracts/mission-record · §contracts/mission-index-entry Closes into · ADR-020 (canonical mission JSON schema) Why this was an RFC · The events array for CAPCOM mode had no prior implementation and its shape needed deliberation. Field name canonicalisation (abbreviated prototype names vs readable canonical names) was a one-time decision that affects every mission JSON file.

Closure note (April 2026)

This RFC closed early — at Slice 2 entry rather than the originally scheduled Slice 4 gate — to lock the schema before any of the 28 mission JSON files were written. The three open questions were resolved in ADR-020:

1. events is required in mission overlays.
2. No threshold field on warning events in v1.
3. data_quality is an enum (good | partial | reconstructed).

The canonical field names from this RFC's "Proposed approach" were adopted as-is. The original deliberation below is preserved as historical context.

The question

Two open questions in the mission JSON schema:

1. The events array — CAPCOM mode needs a scripted mission timeline. The shape, time unit, required fields, and type vocabulary are undecided.
2. Field canonicalisation — prototype field names were informal (dep, arr, tof, dv). Production should be deliberate.

Use cases

• CAPCOM event ticker: "T+15d · MID-COURSE 1" as mission progresses
• type: "warning" events trigger anomaly monitor
• Event markers on the fly screen timeline scrubber
• Data contributors adding events without reading code

Goals

• Events are human-readable and human-editable in raw JSON
• Time unit is unambiguous
• Schema is forward-compatible — new optional fields don't break existing missions
• Field names are readable in context without spaceflight domain knowledge

Constraints

From TA: the data client returns JSON as-is. No schema validation library. Validation is a future CI step.

Proposed approach

Events array:

"events": [
  { "met": 0,   "label": "LAUNCH",       "note": "Falcon Heavy lifts off.", "type": "nominal" },
  { "met": 0.4, "label": "TMI BURN",     "note": "3.61 km/s delta-v.",      "type": "nominal" },
  { "met": 259, "label": "MARS FLYBY",   "note": "300 km closest approach.","type": "nominal" },
  { "met": 509, "label": "EARTH RETURN", "note": "Splashdown nominal.",      "type": "nominal" }
]

met in days from departure. type vocabulary: nominal (teal), info (blue), warning (amber — triggers anomaly monitor).

Field renames:

Current	Proposed	Reason
dep	departure_date	Unambiguous
arr	arrival_date	Unambiguous
tof	transit_days	Self-documenting unit
dv	delta_v	Consistent with physics notation
j2000	Remove	Computable from dates

Fields kept as-is: id, name, agency, dest, status, year, type, sector, color, first, description, data_quality, credit, links.

Alternatives considered

MET in seconds — SI; confusing for humans. "met: 22377600" is 259 days. Rejected.

Keep abbreviated names — dep, arr, tof are familiar to spaceflight readers. Full names win on clarity for non-specialists editing JSON. Rejected.

Strict type enum enforced at load time — requires a validation library. Deferred to CI checklist.

Trade-offs

Renaming 28 mission files is a one-time cost at Slice 2. Low cost; high long-term clarity.

Open questions

1. Should events be optional or required-but-empty for missions without CAPCOM data?
2. Should warning events carry a threshold field, or is anomaly detection purely in code?
3. Is data_quality an enum (good, partial, reconstructed) or free text?

Closing evidence

Schema exercised by three mission types in the fly screen: a Mars mission with full events, a Moon mission with minimal events, and a planned mission. Available at Slice 4 gate.

How this closes

One ADR: canonical mission JSON schema (field names, events array shape, type vocabulary).