Skip to main content

Preserve meaning across clients

These rules apply to new shared contracts and reviewed revisions. Existing formats keep their documented wire behavior until an explicit migration changes it.

Four layers, distinct responsibilities​

LayerOwnsMust preserve
SourceDecoded ARINC, sensor records, weather productsSource identity, original units, cycle, quality and provenance
DomainPlan intent, procedure semantics, navigation graph, airspace volumeStable qualified entities and occurrence relationships
Resolved runtimeSelected procedure geometry, evaluated trajectory, fused weatherInputs, policy revision, validity, completeness and dependency identity
PresentationMap features, labels, profiles, thinned tracksA link to accepted data and explicit display approximations

A displayed line is insufficient to reconstruct an editable route. A forecast aggregate is insufficient to reconstruct an observation. Persist the layer whose meaning the user edits.

Identity and ordering​

An entity can be visited many times. A fix ident needs qualification; a route occurrence needs its own ID even when two visits refer to the same fix. Array position is not durable identity. Document revisions, accepted results and gestures bind to the document commit they were created from. Define whether order is meaningful and whether duplicates are permitted.

Typed structs, JSON and shared objects​

Typed structs and JSON are complementary: structs describe the in-memory model; JSON is a wire representation. JSON itself defines values, objects and arrays, with no built-in object-identity or back-reference mechanism. Ordinary decoding does not automatically reconstruct a shared object graph.

For a shared graph, define entities once with stable, qualified IDs and represent relationships with explicit ID fields. Resolve those IDs through a registry after reading the document. Here is an illustrative design pattern:

{
"fixes": {
"example:FIXA": { "latitudeDeg": 32, "longitudeDeg": -99 }
},
"visits": [
{ "occurrenceId": "visit-1", "fixId": "example:FIXA" },
{ "occurrenceId": "visit-2", "fixId": "example:FIXA" }
]
}

Both visits reference the same navigation entity. They remain distinct occurrences for editing and timing. This pattern does not introduce fields into the existing planning wire contract; each family defines its own references and resolution rules. With value-type structs, a registry can supply values by ID without requiring shared mutable object identity. If a runtime needs actual shared instances, its resolver must deliberately intern those instances.

Graph contracts must specify unresolved-reference behavior, duplicate-ID rejection, forward references, permitted cycles, revision/cycle scope and loading limits. Use stable IDs for durable references; an array index can change after an edit. JSON Pointer identifies a location within a JSON document, but does not itself reconstruct shared instances. JSON Schema's $ref references schema definitions, not shared application objects.

Object references and numeric fidelity are separate concerns. Typed encoders and generic JSON adapters must preserve the owner's units, enums, absence semantics, numeric precision and version rules. Repeated encode/decode conversions can alter representations; do not infer compatibility because both sides accept JSON. For planning, retain the owner-produced sealed payloads and use native key generation and independent admission. Test typed and JSON paths against the same fixtures before advertising interchangeability, including boundary numbers and negative cases.

Quantities, geometry and time​

Every field contract names units and reference frame. WGS84 positions use named latitude and longitude fields where possible; geometry arrays explicitly declare longitude first. Pressure altitude, MSL, AGL and ellipsoid height are different quantities. Surface, unlimited and unknown bounds need explicit representations, not numeric guesses.

Declare time zone, precision and interval endpoints. Keep saved schedule time separate from effective execution/weather time. Weather run, issue, validity, ingestion and selection times answer different questions. Never replace all of them with timestamp.

Missing data and partial results​

Absence, null, unknown, unavailable, stale, invalid and unlimited are not interchangeable. Document each allowed state and the behavior expected of readers. An incomplete draft can still be saved. An unavailable calculation can coexist with usable current geometry. A gap in a measured track remains a gap; missing probability is not zero.

Versions and provenance​

Schema version, dataset cycle, model run, engine build, ABI version and document revision have separate purposes. Retain source provenance and explain every derived or selected field. A model enhancement records its use case, source mapping, compatibility impact and acceptance fixture. Native handles, credentials and host file paths are not portable fields.

Parsing and conformance​

Specify bounds, unknown-field policy, numeric precision, duplicate-key behavior and error semantics. Generated types only describe shape. They do not replace runtime validation or prove numerical compatibility. Planning hashes have native binary64 rules; use its owner, not a generic JSON stringify-and-hash implementation.

A model release includes valid and invalid fixtures, round-trip tests for real consumers, and a migration note. Use the contribution checklist before advertising another client as a supported writer.