An aviation schema for every flight

Introduction

Contrail is a proposal to provide lexicons to describe flight segments. A contrail record merely asserts that a particular flight existed, additional optional fields exist to provide context. For instance, a user's connection to a particular flight (i.e. as a passenger or pilot) is entirely optional. In fact, the only mandatory field required is createdAt. This is the most important property of the schema and everything else follows from it.

An absent field means the value is unknown or does not apply. It never means zero, empty, or none, and the schema defines no placeholder values. A record describing a flight where only the date and the tail number are known is as valid as one with every field populated. Tools that require complete data should enforce that requirement themselves, since the schema cannot do so without excluding general aviation, where most of the commercial fields have no meaning.

The relationship field is the one exception to this rule. When it is absent, no claim is being made about the author's involvement, rather than the claim being unknown. A record created from ADS-B data about another operator's aircraft simply omits it.

Records for every kind of flying

Contrail is intended to describe any kind of flying. Scheduled airline service and general aviation are the most familiar examples, and they sit at roughly opposite ends of how much structured information a flight carries, but they are not the limits of the schema. Cargo, charter, business aviation, air ambulance, law enforcement, government, military and flight training operations all use the same record type.

The difference between them is only which fields happen to apply. A cargo flight has an operator and a flight number but no seat or cabin. A police helicopter may have nothing beyond a registration, an aircraft type, and a takeoff and landing time. Both are complete records, and so are the two below.

{
  "$type": "com.airplaneian.contrail.temp.flight",
  "createdAt": "2026-07-25T09:14:00-07:00",
  "date": "2025-07-13",
  "origin": { "iata": "SFO", "terminal": "INTL", "gate": "A2" },
  "destination": { "iata": "LHR", "terminal": "3" },
  "operator": "VIR",
  "flightNumber": "20",
  "marketingAirline": "DAL",
  "marketingFlightNumber": "5964",
  "registration": "GVBOW",
  "aircraftType": "Boeing 787-9",
  "actualGateDeparture": "2025-07-13T15:57:00-07:00",
  "actualTakeoff":       "2025-07-13T16:25:00-07:00",
  "actualLanding":       "2025-07-14T10:14:00+01:00",
  "actualGateArrival":   "2025-07-14T10:23:00+01:00",
  "relationship": "passenger",
  "seat": "46K",
  "status": "normal",
  "source": "flighty",
  "sourceId": "bef37d51-2876-433b-bffd-95c81f8fe569"
}

{
  "$type": "com.airplaneian.contrail.temp.flight",
  "createdAt": "2026-07-25T09:14:00-07:00",
  "date": "2026-07-19",
  "origin": {
    "name": "Twin Oaks Airpark",
    "faaLid": "7S3",
    "geo": { "latitude": "45.42361", "longitude": "-122.94028" }
  },
  "destination": {
    "name": "Twin Oaks Airpark",
    "faaLid": "7S3",
    "geo": { "latitude": "45.42361", "longitude": "-122.94028" }
  },
  "registration": "N12345",
  "icao24": "a1b2c3",
  "icaoTypeDesignator": "PA18",
  "aircraftType": "Piper PA-18 Super Cub",
  "actualTakeoff": "2026-07-19T10:12:00-07:00",
  "actualLanding": "2026-07-19T10:58:00-07:00",
  "relationship": "pic",
  "source": "manual"
}

Note that the origin and destination in the general aviation example are the same place. Local flights are ordinary and the schema treats them as such.

Identifying flights across repositories

Because a record describes the flight rather than the author, several people aboard the same aircraft may each write a record for it. None of these is canonical, and Contrail treats that duplication as expected. It does not attempt to define a global flight identifier, because no authority exists to issue one.

This does mean readers need some way to recognise two repositories describing the same flight, so the identifying fields carry more weight here than they would in a personal logbook. Write them consistently wherever they are known.

The operator field takes the ICAO designator of whoever actually flew the aircraft, and is not restricted to airlines: UAL for an airline, FDX for a cargo carrier, RCH for a military air mobility flight. It is the ICAO designator rather than the IATA code (UA) because IATA codes are reassigned between carriers over time, which makes a historical record tagged with one ambiguous. Operators with no designator at all, which is most of general aviation, go in operatorName instead. Registrations are written in uppercase with no hyphens, so that G-VBOW and GVBOW do not describe two different aircraft.

Airports and landing sites

Every place in a record uses the same definition, whether it is an origin, a destination or a diversion, and all of its fields are optional. That is what lets one shape describe both a major international airport and a grass strip.

Three identifier fields exist because no single system covers everything. ICAO location indicators are globally unique and are not reassigned, so prefer icao where a place has one. IATA codes are reassigned between airports over time and are absent for the great majority of general aviation fields. Many United States airfields have an FAA Location Identifier and no ICAO indicator at all, which is why faaLid is its own field rather than something written into icao.

Never derive one identifier from another. A wrong code is worse than an absent one, and readers reconciling records match on whatever the fields actually contain. Sites that no identifier system covers, including private strips and off-airport landings, use name and geo instead.

Terminal and gate live here too. They describe how a particular flight was handled at a place rather than a property of the place itself, which is why they belong to the record and not to any airport dataset.

Working with surveillance data

The aircraft and operator fields are shaped to take ADS-B data without losing anything. A surveillance feed supplies a Mode S address, a registration, an ICAO type designator, a human-readable type description and a callsign, and each of those has a field of its own.

The callsign is written verbatim into callsign and is never decomposed on the way in. UAL38 and FDX5608 split cleanly into an operator and a flight number, so an importer can fill those as well. A general aviation aircraft transmits its registration, and a state aircraft may transmit a bare word such as LEGACY. Anything that cannot be split with certainty stays in callsign alone.

Surveillance datasets usually expose a single combined owner-or-operator field, and in practice its contents are the registrant rather than the operator. Much of the fleet is registered to trusts and single-purpose holding companies, so a Pilatus PC-12 comes back registered to a trust company and a Cessna 172 to an LLC named after its own tail number. That value belongs in registeredOwner. Military and state aircraft usually have no entry at all.

Grouping flights into trips

A second record type, com.airplaneian.contrail.temp.trip, groups flights that belonged to one journey. It is a record of its own rather than a field on the flight, so that a flight record stays a standalone assertion. Deleting a trip orphans nothing, and a flight written by someone with no interest in trips is unaffected.

The reference points one way only, from the trip to its flights. Nothing in the protocol keeps two directions consistent, so a flight carries no trip reference and there is no pair of fields that can disagree with each other.

Flights are referenced by plain AT-URI rather than by com.atproto.repo.strongRef. A strong reference pins exact record content, which is right for a like or a repost, but flight records are expected to be corrected in place as better data arrives and every correction would break a pinned reference. The tradeoff is that a reference may dangle if a flight is later deleted, and readers must tolerate that rather than treat it as an error.

A trip references only flight records its own author wrote, and makes no claim about anyone else's repository. The importer below derives trips from booking references, which are read in the browser and never written into a record, because a booking reference can be used to retrieve a reservation.

What Contrail leaves out

Duration, distance, and great circle mileage are all derivable from the times and places already present in a record. Storing them would guarantee that records written by different tools eventually disagree with each other.

Airport names, coordinates, and elevations are reference data about the world rather than assertions by the author, so they do not belong in a personal repository. The one exception is place.geo, which exists for landing sites that no identifier system covers.

Times and time zones

Contrail defines eight timestamps, following the standard out, off, on and in convention, each with a scheduled and an actual variant. All of them are optional. A general aviation record will often carry only a takeoff and a landing.

Every timestamp is written with an explicit UTC offset and no fractional seconds. The Lexicon specification notes two round tripping ambiguities for datetimes, one involving lost precision and one involving trailing fractional second zeros, and a fixed convention avoids both.

Flighty importer demo

The demo below imports a Flighty CSV export into your repository as Contrail records. It runs entirely in this page. Your file is parsed in the browser and is never uploaded, because there is no server to upload it to.

Definitions

The following schemas are published to did:plc:5jsivedaksbcc4n2epiegflk and resolve by NSID.

These are currently published under a temp namespace while the shape settles. Published lexicon constraints can never be loosened afterwards, so the stable names will not be claimed until real data has been through them.