VATSWIM API Field Mapping

FIXM + TFMS Alignment with vATCSCC Extensions

Version: 1.1
Date: 2026-01-16
Purpose: Comprehensive field mapping using FIXM as primary standard, TFMS for abbreviations, with vATCSCC extensions for VATSIM-specific fields.

Naming Conventions

1. Flight Identification

2. Aircraft Information

3. Airports & Locations

4. Route & Trajectory

5. Position & Track Data

6. Flight Times - OOOI

7. Flight Times - Estimated

8. Flight Times - Controlled (TMI)

9. Flight Times - A-CDM Milestones

10. Flight Times - Zone Detection (vATCSCC Extension)

11. Flight Status & Phase

12. TMI / ATFM Control Data

12.1 External Flow Management (ECFMP, NavCanada, VATPAC)

Provider-agnostic integration for external flow management systems. FIXM-aligned field mapping for global interoperability.

Flow Providers

Flow Events (FIXM: /flight/specialHandling)

Flow Event Participants (FIXM: /flight/flightIdentification)

Flow Measures (FIXM: /atfm/flowElement)

Measure Types (TFMS-aligned)

Flow Measure Filters (FIXM: /atfm/flowElement/filter)

Flight-Level Flow Data (adl_flight_tmi extension)

13. Metering & Sequencing (TBFM)

Core TBFM Fields (FIXM 4.3)

TBFM Extended Fields (vATCSCC)

Metering Status Values

SimTraffic Integration Flow

SimTraffic  ──(POST /ingest/metering)──►  SWIM  ──(GET /metering/{airport})──►  vNAS  ──►  CRC Datablock

SimTraffic provides:

• sequence_number - Arrival sequence (1 = next to land)
• scheduled_time_of_arrival - STA at runway threshold
• metering_time - STA at meter fix
• metering_delay - Minutes of assigned delay
• metering_frozen - Frozen flag
• arrival_stream - Corner post assignment

vNAS/CRC displays:

• Sequence number in datablock
• STA/ETA comparison (delay indicator)
• Frozen status

14. SimBrief Integration (vATCSCC Extension)

15. Data Source Timestamps (vATCSCC Extension)

16. Migration Summary

By Action Type

17. vATCSCC Extension XSD Namespace

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:vATCSCC="http://vatcscc.org/schema/1.0"
           xmlns:fx="http://www.fixm.aero/flight/4.3"
           targetNamespace="http://vatcscc.org/schema/1.0"
           elementFormDefault="qualified">

  <!-- VATSIM Pilot Identification -->
  <xs:complexType name="VatsimIdentificationType">
    <xs:sequence>
      <xs:element name="pilotCid" type="xs:positiveInteger"/>
      <xs:element name="pilotName" type="xs:string" minOccurs="0"/>
      <xs:element name="pilotRating" type="vATCSCC:PilotRatingType" minOccurs="0"/>
      <xs:element name="homeArtcc" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <!-- Airport Zone Detection -->
  <xs:complexType name="AirportZoneType">
    <xs:sequence>
      <xs:element name="currentAirportZone" type="vATCSCC:ZoneNameType" minOccurs="0"/>
      <xs:element name="currentZoneAirport" type="xs:string" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <!-- Zone Times -->
  <xs:complexType name="ZoneTimesType">
    <xs:sequence>
      <xs:element name="parkingLeftTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="taxiwayEnteredTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="holdEnteredTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="runwayEnteredTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="rotationTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="approachStartTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="thresholdTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="touchdownTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="rolloutEndTime" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="parkingEnteredTime" type="xs:dateTime" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <!-- SimBrief integration -->
  <xs:complexType name="SimbriefDataType">
    <xs:sequence>
      <xs:element name="ofpId" type="xs:string" minOccurs="0"/>
      <xs:element name="route" type="xs:string" minOccurs="0"/>
      <xs:element name="costIndex" type="xs:integer" minOccurs="0"/>
      <xs:element name="blockFuel" type="xs:decimal" minOccurs="0"/>
      <xs:element name="zeroFuelWeight" type="xs:decimal" minOccurs="0"/>
      <xs:element name="takeoffWeight" type="xs:decimal" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>

  <!-- Enumerations -->
  <xs:simpleType name="PilotRatingType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="NEW"/>
      <xs:enumeration value="PPL"/>
      <xs:enumeration value="IR"/>
      <xs:enumeration value="CMEL"/>
      <xs:enumeration value="ATPL"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="ZoneNameType">
    <xs:restriction base="xs:string">
      <xs:enumeration value="PARKING"/>
      <xs:enumeration value="TAXIWAY"/>
      <xs:enumeration value="HOLD"/>
      <xs:enumeration value="RUNWAY"/>
      <xs:enumeration value="AIRBORNE"/>
      <xs:enumeration value="APPROACH"/>
      <xs:enumeration value="FINAL"/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

18. API Response Example (Post-Migration)

{
  "gufi": "VAT-20260116-UAL123-KJFK-KLAX",
  "flight_key": "UAL123-KJFK-KLAX-20260116",
  "aircraft_identification": "UAL123",
  "pilot_cid": 1234567,
  "operator_icao": "UAL",
  "operator_name": "United Airlines",

  "aircraft_type": "B738",
  "other_aircraft_type": "B738",
  "wake_turbulence": "MEDIUM",
  "weight_class": "L",

  "departure_aerodrome": "KJFK",
  "arrival_aerodrome": "KLAX",
  "departure_airspace": "ZNY",
  "arrival_airspace": "ZLA",

  "route_text": "DEEZZ5 DEEZZ J60 PSB J584 BJARR ANJLL4",
  "cruising_level": 35000,
  "cruising_speed": 460,
  "total_flight_distance": 2475.3,

  "latitude": 39.8561,
  "longitude": -104.6737,
  "altitude": 35000,
  "ground_speed": 487,
  "track": 268,
  "percent_complete": 45.2,
  "current_airport_zone": null,

  "actual_off_block_time": "2026-01-16T14:30:00Z",
  "actual_time_of_departure": "2026-01-16T14:45:00Z",
  "estimated_time_of_arrival": "2026-01-16T19:15:00Z",

  "flight_status": "CRUISING",
  "is_active": true,
  "last_source": "VATSIM",

  "position_time": "2026-01-16T16:45:00Z",
  "updated_at": "2026-01-16T16:45:15Z"
}

11. Airport Taxi Reference Data (FAA ASPM Extension)

FIXM 4.3 does not define taxi time fields. VATSWIM extends the data model with airport taxi-out reference times using FAA ASPM terminology and methodology.

Endpoint: GET /reference/taxi-times, GET /reference/taxi-times/{airport}

Dimensional breakdown (single-airport detail):

Methodology: FAA ASPM p5-p15 average over 90-day rolling window. Airports with fewer than 50 observations receive a default of 600 seconds (10 minutes). Data sourced from VATSIM OOOI events (out_utc → off_utc delta). Refreshed daily at 02:00Z.

End of Field Mapping Document v1.2