An aviation schema for every flight

When this record was written, as distinct from when the flight happened. The only required field. Write it with an explicit UTC offset and no fractional seconds, for example '2026-07-24T18:22:05-07:00' or '2026-07-25T01:22:05Z'.

Fractional seconds are omitted throughout this schema because trailing zeroes in a fractional part round-trip ambiguously and lose precision inconsistently between implementations; a fixed convention avoids both problems.

Calendar date of departure at the origin, as 'YYYY-MM-DD'.

Present as its own field rather than derived from the timestamps because it forms one third of the commercial identity key, alongside 'operator' and 'flightNumber', and because deriving it from an instant requires knowing the origin's local offset, which a reader may not have.

Where both this and a departure timestamp are written they must agree. Write it consistently, since cross-repository matching depends on it.

Where the flight departed. May equal 'destination': local flights that return to their departure point, such as circuits, sightseeing, or training sorties, are ordinary and must not be treated as an error.

Where the flight arrived, or where it was intended to arrive if it was cancelled. If the flight diverted, this remains the intended destination and the actual landing place goes in 'diversionAirport'.

Short identifier for the tool or dataset that produced this record, for example 'flighty', 'manual', or 'adsb'. Together with 'sourceId' this lets a tool find the records it wrote previously and update them in place instead of creating duplicates on a re-import.

It also records provenance: the same record shape carries a first-hand passenger entry and a machine-harvested observation, and 'source' is what distinguishes them.

The identifier the tool named in 'source' uses for this flight, in that tool's own namespace, typically an opaque key from an export.

Deliberately stored in the record body rather than encoded into the record key, so that a record can be corrected without changing its identity: deriving keys from content would turn a corrected flight number into a new record instead of an update.

Meaningful only in combination with 'source', and carries no meaning to readers who do not know that tool.

The flight identification the aircraft transmitted, written exactly as received, uppercase with no padding or spaces.

This is the primary flight identifier available from ADS-B and other surveillance sources, and it must not be decomposed on the way in: 'UAL38' splits cleanly into an operator and a flight number, but a general aviation aircraft transmits its registration, and state or military aircraft commonly transmit something with no civil structure at all, such as 'LEGACY' or 'KLH71'.

Write this field verbatim and populate 'operator' and 'flightNumber' as well only when the split is unambiguous. Absent for sources that never see a callsign, such as a passenger's own booking history.

ICAO designator of the agency that actually operated the flight, three letters, uppercase. Not restricted to airlines: 'UAL' for an airline, 'FDX' for a cargo carrier, 'RCH' for a military air mobility flight.

ICAO rather than IATA because IATA codes are recycled between carriers, so a historical record tagged with one is ambiguous. Absent for most general aviation, where no designator exists; use 'operatorName' in that case.

Part of the commercial identity key alongside 'date' and 'flightNumber', so write it consistently where it is known, since cross-repository matching depends on it.

Free-text name of the agency that operated the flight, for operators that have no ICAO designator: flight schools, charter and air taxi businesses, law enforcement and government units, private owners flying their own aircraft.

Not normalised and not reliable for matching, in the same way that 'aircraftType' complements 'icaoTypeDesignator'. Do not restate here the name of an operator whose designator is already in 'operator'. Note that this is who flew the aircraft, which is frequently not who owns it.

The operating agency's flight number, as a string rather than an integer. Alphabetic suffixes are in real use, some sources emit malformed values, and a numeric type could never be loosened later without breaking every existing record.

Write the digits alone without the operator designator prefix. Part of the commercial identity key, so write it consistently, since cross-repository matching depends on it.

Absent for flights that have no flight number, which is most of general aviation and much state and military flying.

ICAO designator of the airline that sold the flight, when it differs from 'operator'. This one is deliberately named for airlines, because codeshare marketing is an airline arrangement and has no counterpart in other kinds of operation.

Absent means either that there was no codeshare or that it is unknown. Do not put the marketing carrier in 'operator'; the distinction is what lets two records describing one physical flight be recognised as such.

Flight number under which the flight was sold, when it differs from 'flightNumber'. A string, for the same reasons.

Registration or tail number of the airframe, for example 'N12345' or 'GVBOW'. Write it uppercase with no hyphens, spaces, or other separators, so that 'G-VBOW' and 'GVBOW' do not become two different aircraft to a reader.

This normalisation matters because registration is one of the few fields by which general aviation records can be matched across repositories. Military and state aircraft carry identifiers in this field too, in whatever form their operator uses, such as 'MM62209' or 'FAC1215'.

Note that registrations are reassigned to different airframes over time, so 'icao24' is the more durable airframe identifier where it is known.

Free-text name of the party the airframe is registered to, as the civil registry records it.

This is deliberately separate from 'operator' and 'operatorName', because the registrant is frequently not the operator: a large share of the fleet is registered to trusts, banks, or single-purpose holding companies, such as 'WILMINGTON TRUST CO TRUSTEE' or a limited company named after the tail number.

Surveillance datasets usually expose a single combined owner-or-operator field, and its contents are the registrant, so it belongs here rather than in 'operator'. Absent for aircraft with no public registry entry, which includes most military aircraft.

Free-text description of the aircraft type as the source expressed it, for example 'Boeing 737-800' or 'Piper PA-18 Super Cub'.

Present because most sources supply a name rather than a designator, and discarding it in favour of an empty 'icaoTypeDesignator' would lose real information. Not normalised and not reliable for matching, so use 'icaoTypeDesignator' for that.

Do not derive one field from the other, because a guessed designator is worse than an absent one and several distinct designators share a single marketing name.

ICAO aircraft type designator, for example 'B77W' or 'C172'. Write it only when the source actually supplies a designator, not when it has been inferred from a marketing name.

The airframe's 24-bit ICAO address as six lowercase hexadecimal characters, for example 'a1b2c3'. Stable per airframe and the primary identity field for general aviation, where there is no flight number to match on.

Together with an actual departure time it forms the general aviation identity key; write both consistently, since cross-repository matching depends on them.

Scheduled time the aircraft left the gate or parking position, the 'out' time. Write it with an explicit UTC offset and no fractional seconds. The eight time fields form the standard out, off, on and in set.

All of them are optional, so a record knowing only a takeoff time is valid, and general aviation records will usually omit the gate times entirely.

Actual time the aircraft left the gate or parking position, the 'out' time. Explicit UTC offset, no fractional seconds. The interval between this and 'actualGateArrival' is block time, which is not stored because it is derivable.

Scheduled wheels-off time, the 'off' time. Explicit UTC offset, no fractional seconds.

Actual wheels-off time, the 'off' time. Explicit UTC offset, no fractional seconds. Together with 'icao24' this forms the general aviation identity key, and it is usually the most reliably known time for a flight with no gate operations.

Scheduled wheels-on time, the 'on' time. Explicit UTC offset, no fractional seconds.

Actual wheels-on time, the 'on' time. Explicit UTC offset, no fractional seconds. The interval between this and 'actualTakeoff' is flight time, which is not stored because it is derivable.

Scheduled time the aircraft reached the gate or parking position, the 'in' time. Explicit UTC offset, no fractional seconds.

Actual time the aircraft reached the gate or parking position, the 'in' time. Explicit UTC offset, no fractional seconds.

The author's connection to this flight. Unlike every other field in this record, absent here does not mean unknown: it means no claim of any relationship is being made. A record written from ADS-B data about someone else's flight simply omits it.

An open string rather than a closed set, so that relationships nobody anticipated can be expressed without a schema change, and readers must tolerate values outside the known list.

Note that omitting this field does not make a record private, because the presence of flight records in a repository discloses the author's connection to those flights regardless of what the records claim.

Seat occupied, as a string, for example '14C', with row and position together, since the letter is not optional and the whole value is not a number. Only meaningful when 'relationship' indicates the author was aboard.

Cabin or class of service. An open string rather than an enumeration because carriers invent and rename cabins continually and any closed set would be obsolete within a year.

Write lower camel case, matching the known values below, so that records from different tools compare equal; readers must tolerate values outside the list.

How the flight concluded. Absent means unknown rather than normal, so write 'normal' explicitly when it is known that the flight operated as planned. An open string for consistency with the other classification fields here; readers must tolerate values outside the list.

Where the flight actually landed, when it did not land at 'destination'. Present only when 'status' is 'diverted'. 'destination' continues to hold the intended arrival point.

Free-text note about the flight. Everything written here is public and permanent once the record is published, and unlike the structured fields its contents cannot be reviewed by a tool for anything the author did not mean to disclose.

Tools writing records on a user's behalf should show note contents prominently before publishing. Do not use this field to carry structured data that belongs in a dedicated field, and do not use it for booking references or other credentials.

When this record was written, as distinct from when the trip happened. The only required field. Write it with an explicit UTC offset and no fractional seconds, for example '2026-07-25T18:22:05-07:00'.

Free-text name for the trip, for example 'Tokyo, spring 2026'. Optional, and as with any free text it is public and permanent once published.

The flights that made up this trip, in the order they were flown, as AT-URIs pointing at com.airplaneian.contrail.temp.flight records.

Plain AT-URIs rather than content-pinned strong references, because flight records are expected to be corrected in place as better data arrives, and a pinned reference would break on every such correction.

References may dangle if a flight is later deleted; readers must tolerate that rather than treat it as an error.

Short identifier for the tool that produced this record, for example 'flighty' or 'manual'. Same meaning as on a flight record: together with 'sourceId' it lets a tool update the trips it wrote previously instead of duplicating them on a re-import.

The identifier the tool named in 'source' uses for this trip, in that tool's own namespace. Note that a source's grouping key may be sensitive even when the resulting grouping is not.

A booking reference, for instance, is a credential that can be used to retrieve a reservation, and must not be written here. Derive an opaque identifier instead where the natural key cannot be published.

ICAO location indicator, four characters, uppercase. For example 'KOAK' for Oakland or 'EGLL' for Heathrow. Preferred over 'iata' for cross-repository matching because ICAO indicators are globally unique and are not reassigned.

Many small airfields have none; omit the field rather than guessing.

IATA location code, three characters, uppercase. For example 'OAK'. Absent for the great majority of general aviation fields.

Note that IATA codes are reassigned between airports over time, so a code alone does not identify a place across decades, and it should be paired with 'icao' or 'geo' where possible.

FAA Location Identifier, for United States airfields that have one. For example '1G5'. Many US public-use fields have an FAA LID and no ICAO indicator at all, which is why this is a separate field rather than a fallback written into 'icao'.

Free-text name of the place, for landing sites that no identifier system covers: grass strips, private fields, off-airport landings, water landings. Also useful as a human-readable label alongside a code.

Carries no matching guarantees, since two records may name the same field differently.

Coordinates of the place, for landing sites that no identifier system covers, or to disambiguate an ambiguous name. Note that the referenced def requires both latitude and longitude, expressed as decimal-degree strings referenced to WGS84.

See the community.lexicon.location documentation for the coordinate conventions. Do not write coordinates that were merely looked up from an identifier already present in this object, because that is reference data about the world rather than an assertion about this flight.

Terminal used by this particular flight at this place, as free text, since terminal naming is entirely carrier- and airport-specific ('3', 'B', 'Main', 'INTL').

This describes how this flight was handled rather than a property of the place itself, which is why it lives here rather than in any airport reference dataset.

Gate or stand used by this particular flight at this place, as free text ('C19', '44C', 'A2E'). As with 'terminal', this is a fact about this flight rather than about the place. Not applicable to most general aviation operations.