@yottagraph-app/data-model-skill 0.0.21 → 0.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/data-model-skill",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "description": "Data model skill documentation for AI agents - entity types, properties, and schemas from Lovelace fetch sources",
   "repository": {
     "type": "git",

package/skill/dotauthority/DATA_DICTIONARY.md

@@ -0,0 +1,140 @@
+# Data Dictionary: DOT Authority
+
+## Source Overview
+
+FMCSA Carrier Authority data from the "Carrier All With History" Socrata dataset (`6eyk-hxee`), published by the Federal Motor Carrier Safety Administration. Contains operating authority records for motor carriers, brokers, and freight forwarders, including docket numbers, authority statuses (common, contract, broker), insurance requirements, and business contact information.
+
+Bulk-refreshed periodically by FMCSA; no per-row timestamps. The streamer performs a single full download per run.
+
+| Pipeline | `Record.Source` |
+|----------|----------------|
+| Carrier Authority | `dotauthority` |
+
+This is a companion dataset to DOT Census (`dotcensus`), which covers company registration, fleet size, and safety ratings. Authority covers operating authority statuses and insurance/bond requirements. Both sources share the `usdot_number` strong ID, enabling entity merging across datasets.
+
+---
+
+## Entity Types
+
+### `organization`
+
+A motor carrier, broker, or freight forwarder registered with FMCSA.
+
+- Primary key: `usdot_number` (USDOT number assigned by FMCSA)
+- Entity resolver: named entity. Strong ID = `usdot_number`. Disambiguation via legal name and business address.
+- Entity name: DBA name if present (with legal name as the owner entity); otherwise the legal name.
+
+### `person`
+
+A named individual who is the legal owner of a carrier operating under a DBA name.
+
+- Only created when the carrier has a DBA name different from the legal name, and the legal name appears to be a person (not an organization).
+- Entity resolver: named entity. No strong ID.
+
+### `location`
+
+The business location of a carrier, derived from city, state, and country fields.
+
+- Entity resolver: named entity. No strong ID.
+- Entity name: formatted as "City, State" or "City, State, Country".
+
+---
+
+## Properties
+
+### Organization: Identity and Registration
+
+* `usdot_number`
+  * Definition: USDOT number uniquely identifying the registered motor carrier, broker, or shipper.
+  * Examples: `1234567`, `3456789`
+  * Derivation: `dot_number` field from the Socrata API. Carriers with DOT number `00000000` or empty are treated as not having a DOT number.
+
+* `dot_docket_number`
+  * Definition: FMCSA docket number (MC/FF/MX number) for the carrier's operating authority.
+  * Examples: `MC012892`, `MC599911`
+  * Derivation: `docket_number` field from the Socrata API.
+
+### Organization: Business Contact
+
+* `address`
+  * Definition: Formatted business street address of the carrier.
+  * Examples: `1200 SEABOARD DR, HIALEAH, FL 33010`
+  * Derivation: Composed from `bus_street_po`, `bus_city`, `bus_state_code`, `bus_zip_code`, and `bus_ctry_code` fields, formatted as "Street, City, State Zip".
+
+* `dot_phone_number`
+  * Definition: Primary business phone number of the carrier.
+  * Examples: `5551234567`
+  * Derivation: `bus_telno` field from the Socrata API.
+
+### Organization: Authority Status
+
+* `dot_common_authority_status`
+  * Definition: Status of the carrier's common carrier authority.
+  * Examples: `A (Active)`, `I (Inactive)`, `N (None)`
+  * Derivation: `common_stat` field. Single-letter code expanded to include the human-readable label.
+
+* `dot_contract_authority_status`
+  * Definition: Status of the carrier's contract carrier authority.
+  * Examples: `A (Active)`, `I (Inactive)`, `N (None)`
+  * Derivation: `contract_stat` field. Same code expansion as common authority.
+
+* `dot_broker_authority_status`
+  * Definition: Status of the carrier's broker authority.
+  * Examples: `A (Active)`, `I (Inactive)`, `N (None)`
+  * Derivation: `broker_stat` field. Same code expansion as common authority.
+
+* `dot_authority_type`
+  * Definition: Authority type flags indicating which categories the carrier is authorized for.
+  * Examples: `Property`, `Passenger`, `Household Goods`, `Property; Passenger`
+  * Derivation: Composed from five checkbox fields (`property_chk`, `passenger_chk`, `hhg_chk`, `private_auth_chk`, `enterprise_chk`). Values with `Y` are included, joined with `; `.
+
+### Organization: Insurance and Bonding
+
+* `dot_min_coverage_amount`
+  * Definition: Minimum insurance coverage amount required, in thousands of dollars.
+  * Examples: `00750`, `05000`
+  * Derivation: `min_cov_amount` field. Values of `00000` are suppressed.
+
+* `dot_cargo_insurance_required`
+  * Definition: Whether cargo insurance is required for this carrier.
+  * Examples: `1.0` (yes), `0.0` (no)
+  * Derivation: `cargo_req` field. `Y` → 1.0, `N` → 0.0. Other values are not emitted.
+  * Note: Stored as float per KG boolean convention.
+
+* `dot_bond_required`
+  * Definition: Whether a surety bond is required for this carrier.
+  * Examples: `1.0` (yes), `0.0` (no)
+  * Derivation: `bond_req` field. `Y` → 1.0, `N` → 0.0. Other values are not emitted.
+  * Note: Stored as float per KG boolean convention.
+
+* `dot_bipd_insurance_on_file`
+  * Definition: Bodily injury / property damage insurance filing amount on file.
+  * Examples: `01000`, `05000`
+  * Derivation: `bipd_file` field. Values of `00000` are suppressed.
+
+---
+
+## Entity Relationships Summary
+
+```
+organization ──[is_located_at]──→ location
+person       ──[doing_business_as]──→ organization
+organization ──[doing_business_as]──→ organization
+```
+
+The `doing_business_as` relationship is created when a carrier's legal name differs from its DBA name. The legal entity (person or organization, determined by name heuristics) is the subject; the DBA organization is the target. The DBA organization is also the primary record subject carrying all authority properties.
+
+The `is_located_at` relationship is created when both city and state are present. The target is a location entity named "City, State" (or "City, State, Country" if the country code is present).
+
+---
+
+## Source Fields Not Mapped
+
+The following Socrata fields are present in the API response but not currently mapped to KG properties:
+
+- `common_app_pend`, `contract_app_pend`, `broker_app_pend` -- application pending flags
+- `common_rev_pend`, `contract_rev_pend`, `broker_rev_pend` -- revocation pending flags
+- `cargo_file` -- cargo insurance filing amount
+- `bond_file` -- bond filing amount
+
+These were omitted as lower-priority. They could be added as future enhancements if needed for analysis.

package/skill/dotauthority/schema.yaml

@@ -0,0 +1,161 @@
+# Dataset schema for FMCSA Carrier Authority (All With History).
+#
+# Source: https://data.transportation.gov/Trucking-and-Motorcoaches/Carrier-All-With-History/6eyk-hxee
+# Bulk-refreshed periodically by FMCSA; no per-row timestamps.
+#
+# This schema describes motor carrier operating authority records including
+# docket information, authority statuses, insurance requirements, and
+# business contact information.
+name: "dotauthority"
+description: "FMCSA carrier operating authority data including docket numbers, authority statuses, insurance requirements, and business contact information from the Carrier All With History file"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "organization"
+    description: "A particular business, institution, or organization such as a corporation, university, government agency, or non-profit"
+    display_name: "Organization"
+    mergeability: not_mergeable
+    strong_id_properties: ["usdot_number"]
+    passive: true
+
+  - name: "person"
+    description: "A named individual such as a business owner, executive, or public figure"
+    display_name: "Person"
+    mergeability: not_mergeable
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    examples: ["New York City", "San Francisco", "North America", "Bakery Square"]
+    passive: true
+
+properties:
+  - name: "usdot_number"
+    type: string
+    description: "USDOT number assigned by FMCSA, uniquely identifying a registered motor carrier, broker, or shipper"
+    display_name: "USDOT Number"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_docket_number"
+    type: string
+    description: "FMCSA docket number (MC number) for operating authority"
+    display_name: "Docket Number"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["MC012892", "MC599911"]
+    passive: true
+
+  - name: "address"
+    type: string
+    description: "Physical street address of the entity"
+    display_name: "Address"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["1200 SEABOARD DR, HIALEAH, FL 33010"]
+    passive: true
+
+  - name: "dot_phone_number"
+    type: string
+    description: "Primary phone number of the carrier"
+    display_name: "Phone Number"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["5551234567"]
+    passive: true
+
+  - name: "dot_common_authority_status"
+    type: string
+    description: "Status of common carrier authority (A=Active, I=Inactive, N=None)"
+    display_name: "Common Authority Status"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["A (Active)", "I (Inactive)", "N (None)"]
+    passive: true
+
+  - name: "dot_contract_authority_status"
+    type: string
+    description: "Status of contract carrier authority (A=Active, I=Inactive, N=None)"
+    display_name: "Contract Authority Status"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["A (Active)", "I (Inactive)", "N (None)"]
+    passive: true
+
+  - name: "dot_broker_authority_status"
+    type: string
+    description: "Status of broker authority (A=Active, I=Inactive, N=None)"
+    display_name: "Broker Authority Status"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["A (Active)", "I (Inactive)", "N (None)"]
+    passive: true
+
+  - name: "dot_authority_type"
+    type: string
+    description: "Carrier authority type flags indicating property, passenger, household goods, private, or enterprise authorization"
+    display_name: "Authority Type"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["Property", "Passenger", "Household Goods", "Property; Passenger"]
+    passive: true
+
+  - name: "dot_min_coverage_amount"
+    type: string
+    description: "Minimum insurance coverage amount required (in thousands of dollars)"
+    display_name: "Minimum Coverage Amount"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["00750", "05000"]
+    passive: true
+
+  - name: "dot_cargo_insurance_required"
+    type: float
+    description: "Whether cargo insurance is required (1.0 = yes, 0.0 = no)"
+    display_name: "Cargo Insurance Required"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_bond_required"
+    type: float
+    description: "Whether a surety bond is required (1.0 = yes, 0.0 = no)"
+    display_name: "Bond Required"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    passive: true
+
+  - name: "dot_bipd_insurance_on_file"
+    type: string
+    description: "Bodily injury / property damage insurance filing amount"
+    display_name: "BIPD Insurance On File"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    examples: ["01000", "05000"]
+    passive: true
+
+relationships:
+  - name: "doing_business_as"
+    description: "A legal entity is doing business as (DBA) an organization"
+    display_name: "Doing Business As"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    target_flavors: ["organization"]
+    passive: true
+
+  - name: "is_located_at"
+    description: "An entity is located at, operates in, resides in, is headquartered in, was born in, visits, or died in a location"
+    display_name: "Located At"
+    mergeability: not_mergeable
+    domain_flavors: ["organization"]
+    target_flavors: ["location"]
+    passive: true

package/skill/faaregistry/DATA_DICTIONARY.md

@@ -0,0 +1,381 @@
+# Data Dictionary: FAA Aircraft Registry
+
+## Source Overview
+
+The FAA Releasable Aircraft Database is published by the Federal Aviation Administration, Civil Aviation Registry, Aircraft Registration Branch (AFS-750). It contains registration records for all U.S. civil aircraft, plus reference tables, deregistered aircraft, dealer certificates, document indices, and reserved N-numbers.
+
+The database is distributed as a single ZIP archive (~60MB) refreshed daily at 11:30 PM Central Time. It contains 7 comma-delimited `.txt` files. Field definitions are documented in [ardata.pdf](https://registry.faa.gov/database/ardata.pdf).
+
+Download URL: `https://registry.faa.gov/database/ReleasableAircraft.zip`
+
+The implementation joins ACFTREF.txt and ENGINE.txt as in-memory lookup tables into MASTER.txt rows, producing denormalized aircraft registration records. DEREG.txt uses a similar structure and is processed alongside MASTER.txt. DEALER.txt, DOCINDEX.txt, and RESERVED.txt are processed as separate entity types.
+
+| File | Record Count (approx) | Entity Type |
+|------|----------------------|-------------|
+| MASTER.txt | ~300,000+ | `aircraft` |
+| ACFTREF.txt | ~few thousand | Lookup table (joined into `aircraft`) |
+| ENGINE.txt | ~few thousand | Lookup table (joined into `aircraft`) |
+| DEREG.txt | ~300,000+ | `aircraft` (deregistered) |
+| DEALER.txt | ~few thousand | `organization` (aircraft dealers) |
+| DOCINDEX.txt | ~millions | `document` (aircraft document index) |
+| RESERVED.txt | ~tens of thousands | `aircraft` (reserved N-numbers) |
+
+| Pipeline | `Record.Source` |
+|----------|----------------|
+| All files | `faaregistry` |
+
+---
+
+## Entity Types
+
+### `aircraft`
+
+A U.S. civil aircraft identified by its FAA registration N-number. Includes active registrations (MASTER.txt), deregistered aircraft (DEREG.txt), and reserved N-numbers (RESERVED.txt).
+
+- Primary key: N-Number (e.g., `"12345"` for N12345)
+- Entity resolver: named entity. Strong ID = `n_number`. Mode S hex code as secondary identifier. Disambiguation via manufacturer, model, serial number, registrant name.
+
+### `organization`
+
+An aircraft dealer or manufacturer holding an FAA Dealer's Aircraft Registration Certificate.
+
+- Primary key: Certificate number (e.g., `"24-0001"`)
+- Entity resolver: named entity. Strong ID = `dealer_certificate_number`. Disambiguation via name, address.
+
+### `document`
+
+A document recorded with the FAA Aircraft Registry, indexed by collateral identification (usually the N-number).
+
+- Primary key: Document ID (12-character unique identifier)
+- Entity resolver: named entity. Strong ID = `faa_document_id`. Not mergeable.
+
+### `location`
+
+A geographic location derived from the registrant's address (city + state).
+
+- Primary key: city + state combination
+- Entity resolver: named entity. Disambiguation via city name, state code.
+
+---
+
+## Properties
+
+### Aircraft Properties (from MASTER.txt + ACFTREF.txt + ENGINE.txt joins)
+
+#### Identity and Registration
+
+* `n_number`
+  * Definition: FAA registration number assigned to the aircraft (without the "N" prefix).
+  * Examples: `"12345"`, `"789AB"`, `"5NJ"`
+  * Derivation: `N-NUMBER` field from MASTER.txt, positions 1-5.
+
+* `serial_number`
+  * Definition: Complete aircraft serial number assigned by the manufacturer.
+  * Examples: `"28-7990244"`, `"172S10245"`
+  * Derivation: `SERIAL NUMBER` field from MASTER.txt, positions 7-36.
+
+* `mode_s_code_hex`
+  * Definition: Aircraft Mode S transponder code in hexadecimal format (ICAO 24-bit address).
+  * Examples: `"A12345"`, `"ABCDEF"`
+  * Derivation: `MODE S CODE HEX` field from MASTER.txt, positions 602-611.
+  * Note: This corresponds to the `icaoAddress` property in the KG aircraft flavor schema.
+
+* `mode_s_code`
+  * Definition: Aircraft Mode S transponder code in octal format.
+  * Examples: `"50712345"`
+  * Derivation: `MODE S CODE` field from MASTER.txt, positions 257-264.
+
+* `unique_id`
+  * Definition: FAA-assigned unique identification number for the registration record.
+  * Examples: `"01234567"`
+  * Derivation: `UNIQUE ID` field from MASTER.txt, positions 541-548.
+
+#### Aircraft Details (joined from ACFTREF.txt)
+
+* `manufacturer_name`
+  * Definition: Name of the aircraft manufacturer.
+  * Examples: `"CESSNA"`, `"BOEING"`, `"PIPER"`, `"BEECH"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT MANUFACTURER NAME` (positions 9-38) via `AIRCRAFT MFR MODEL CODE` foreign key.
+
+* `model_name`
+  * Definition: Aircraft model and series name.
+  * Examples: `"172S"`, `"737-800"`, `"PA-28-181"`
+  * Derivation: Joined from ACFTREF.txt `MODEL NAME` (positions 40-59) via `AIRCRAFT MFR MODEL CODE` foreign key.
+
+* `aircraft_type`
+  * Definition: Type of aircraft.
+  * Examples: `"Fixed wing single engine"`, `"Rotorcraft"`, `"Balloon"`
+  * Derivation: `TYPE AIRCRAFT` field from MASTER.txt (position 249), decoded: 1=Glider, 2=Balloon, 3=Blimp/Dirigible, 4=Fixed wing single engine, 5=Fixed wing multi engine, 6=Rotorcraft, 7=Weight-shift-control, 8=Powered Parachute, 9=Gyroplane, H=Hybrid Lift, O=Other.
+
+* `engine_type`
+  * Definition: Type of engine installed.
+  * Examples: `"Reciprocating"`, `"Turbo-fan"`, `"Electric"`
+  * Derivation: `TYPE ENGINE` field from MASTER.txt (positions 251-252), decoded: 0=None, 1=Reciprocating, 2=Turbo-prop, 3=Turbo-shaft, 4=Turbo-jet, 5=Turbo-fan, 6=Ramjet, 7=2 Cycle, 8=4 Cycle, 9=Unknown, 10=Electric, 11=Rotary.
+
+* `year_manufactured`
+  * Definition: Year the aircraft was manufactured.
+  * Examples: `"1978"`, `"2023"`
+  * Derivation: `YEAR MFR` field from MASTER.txt, positions 52-55.
+
+* `number_of_engines`
+  * Definition: Number of engines on the aircraft.
+  * Examples: `"1"`, `"2"`, `"4"`
+  * Derivation: Joined from ACFTREF.txt `NUMBER OF ENGINES` (positions 70-71).
+
+* `number_of_seats`
+  * Definition: Maximum number of seats in the aircraft.
+  * Examples: `"4"`, `"189"`, `"12"`
+  * Derivation: Joined from ACFTREF.txt `NUMBER OF SEATS` (positions 73-75).
+
+* `aircraft_weight_class`
+  * Definition: Maximum gross takeoff weight class.
+  * Examples: `"Up to 12,499 lbs"`, `"12,500 - 19,999 lbs"`, `"20,000 and over"`, `"UAV up to 55 lbs"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT WEIGHT` (positions 77-83), decoded: 1=Up to 12,499, 2=12,500-19,999, 3=20,000 and over, 4=UAV up to 55.
+
+* `cruising_speed`
+  * Definition: Average cruising speed in miles per hour.
+  * Examples: `"124"`, `"530"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT CRUISING SPEED` (positions 85-88).
+  * Note: Not present on all records.
+
+* `aircraft_category`
+  * Definition: Land/sea/amphibian classification.
+  * Examples: `"Land"`, `"Sea"`, `"Amphibian"`
+  * Derivation: Joined from ACFTREF.txt `AIRCRAFT CATEGORY CODE` (position 66), decoded: 1=Land, 2=Sea, 3=Amphibian.
+
+* `builder_certification`
+  * Definition: Builder certification classification.
+  * Examples: `"Type Certificated"`, `"Not Type Certificated"`, `"Light Sport"`
+  * Derivation: Joined from ACFTREF.txt `BUILDER CERTIFICATION CODE` (position 68), decoded: 0=Type Certificated, 1=Not Type Certificated, 2=Light Sport.
+
+* `type_certificate_data_sheet`
+  * Definition: FAA Type Certificate Data Sheet reference.
+  * Derivation: Joined from ACFTREF.txt `TC DATA SHEET` (positions 90-105).
+
+* `type_certificate_holder`
+  * Definition: Name of the Type Certificate holder.
+  * Derivation: Joined from ACFTREF.txt `TC DATA HOLDER` (positions 107-157).
+
+#### Engine Details (joined from ENGINE.txt)
+
+* `engine_manufacturer`
+  * Definition: Name of the engine manufacturer.
+  * Examples: `"LYCOMING"`, `"CONT MOTOR"`, `"P&W"`
+  * Derivation: Joined from ENGINE.txt `ENGINE MANUFACTURER NAME` (positions 7-16) via `ENGINE MFR MODEL CODE` foreign key.
+
+* `engine_model`
+  * Definition: Engine model name.
+  * Examples: `"O-320-D2J"`, `"IO-540"`
+  * Derivation: Joined from ENGINE.txt `ENGINE MODEL NAME` (positions 18-30).
+
+* `engine_horsepower`
+  * Definition: Engine horsepower (for reciprocating, turbo-prop, turbo-shaft, 2-cycle, 4-cycle engines). Unit: HP.
+  * Examples: `"180"`, `"310"`
+  * Derivation: Joined from ENGINE.txt `ENGINE HORSEPOWER` (positions 35-39).
+  * Note: Only populated for engine types 1, 2, 3, 7, 8.
+
+* `engine_thrust`
+  * Definition: Engine thrust (for turbo-jet, turbo-fan, ramjet engines). Unit: pounds of thrust.
+  * Examples: `"27300"`, `"56000"`
+  * Derivation: Joined from ENGINE.txt `POUNDS OF THRUST` (positions 41-46).
+  * Note: Only populated for engine types 4, 5, 6.
+
+#### Registration Status
+
+* `registration_status`
+  * Definition: Current status of the aircraft registration.
+  * Examples: `"Valid Registration"`, `"Registration Expired"`, `"Sale Reported"`, `"Administratively Canceled"`
+  * Derivation: `STATUS CODE` field from MASTER.txt (positions 254-255), decoded to human-readable text. Codes include V=Valid, R=Pending, E=Revoked by enforcement, M=Manufacturer, etc.
+
+* `registrant_type`
+  * Definition: Type of entity that owns the aircraft.
+  * Examples: `"Individual"`, `"Corporation"`, `"LLC"`, `"Government"`
+  * Derivation: `TYPE REGISTRANT` field from MASTER.txt (position 57), decoded: 1=Individual, 2=Partnership, 3=Corporation, 4=Co-Owned, 5=Government, 7=LLC, 8=Non Citizen Corporation, 9=Non Citizen Co-Owned.
+
+* `fractional_ownership`
+  * Definition: Whether the registration has fractional ownership.
+  * Examples: `"true"`, `"false"`
+  * Derivation: `FRACTIONAL OWNERSHIP` field from MASTER.txt (position 266), `Y` = true, blank = false.
+
+#### Certification
+
+* `airworthiness_class`
+  * Definition: Airworthiness certificate classification.
+  * Examples: `"Standard"`, `"Experimental"`, `"Restricted"`, `"Light Sport"`
+  * Derivation: `CERTIFICATION A - AIRWORTHINESS CLASSIFICATION CODE` from MASTER.txt (position 238), decoded: 1=Standard, 2=Limited, 3=Restricted, 4=Experimental, 5=Provisional, 6=Multiple, 7=Primary, 8=Special Flight Permit, 9=Light Sport.
+
+* `approved_operations`
+  * Definition: Approved operations for the airworthiness certificate.
+  * Examples: `"Normal"`, `"Utility"`, `"Agriculture and Pest Control"`, `"Amateur Built"`
+  * Derivation: `CERTIFICATION B - APPROVED OPERATION CODES` from MASTER.txt (positions 239-247), decoded based on airworthiness class.
+
+#### Registrant Information
+
+* `registrant_name`
+  * Definition: Name of the registered owner as it appears on the Application for Registration.
+  * Examples: `"SMITH JOHN"`, `"DELTA AIR LINES INC"`, `"UNITED STATES GOVERNMENT"`
+  * Derivation: `REGISTRANT'S NAME` field from MASTER.txt, positions 59-108.
+
+* `registrant_address`
+  * Definition: Formatted street address of the registrant.
+  * Derivation: Concatenation of `STREET1` (positions 110-142) and `STREET2` (positions 144-176) from MASTER.txt.
+
+* `registrant_city`
+  * Definition: City of the registrant.
+  * Examples: `"ATLANTA"`, `"WICHITA"`, `"SEATTLE"`
+  * Derivation: `REGISTRANT'S CITY` field from MASTER.txt, positions 178-195.
+
+* `registrant_state`
+  * Definition: Two-letter state code of the registrant.
+  * Examples: `"GA"`, `"KS"`, `"WA"`
+  * Derivation: `REGISTRANT'S STATE` field from MASTER.txt, positions 197-198.
+
+* `registrant_zip_code`
+  * Definition: Postal ZIP code of the registrant.
+  * Examples: `"30320"`, `"67201-1234"`
+  * Derivation: `REGISTRANT'S ZIP CODE` field from MASTER.txt, positions 200-209.
+
+* `registrant_region`
+  * Definition: FAA region of the registrant.
+  * Examples: `"Eastern"`, `"Western-Pacific"`, `"Great Lakes"`
+  * Derivation: `REGISTRANT'S REGION` field from MASTER.txt (position 211), decoded: 1=Eastern, 2=Southwestern, 3=Central, 4=Western-Pacific, 5=Alaskan, 7=Southern, 8=European, C=Great Lakes, E=New England, S=Northwest Mountain.
+
+#### Dates
+
+* `last_activity_date`
+  * Definition: Date of last registration activity.
+  * Examples: `"2024/03/15"`
+  * Derivation: `LAST ACTIVITY DATE` from MASTER.txt (positions 220-227), format YYYY/MM/DD.
+
+* `certificate_issue_date`
+  * Definition: Date the registration certificate was issued.
+  * Examples: `"2023/06/01"`
+  * Derivation: `CERTIFICATE ISSUE DATE` from MASTER.txt (positions 229-236), format YYYY/MM/DD.
+
+* `airworthiness_date`
+  * Definition: Date of airworthiness certification.
+  * Examples: `"2001/09/14"`
+  * Derivation: `AIRWORTHINESS DATE` from MASTER.txt (positions 268-275).
+
+* `expiration_date`
+  * Definition: Certificate of Registration expiration date.
+  * Examples: `"2027/03/31"`
+  * Derivation: `EXPIRATION DATE` from MASTER.txt (positions 532-539), format YYYY/MM/DD.
+
+#### Co-Owners
+
+* `other_owner_name`
+  * Definition: Co-owner or partnership name (up to 5 additional names).
+  * Derivation: `OTHER NAME 1` through `OTHER NAME 5` from MASTER.txt (positions 277-530).
+  * Note: Stored as multiple atoms when multiple co-owners exist.
+
+#### Kit Aircraft
+
+* `kit_manufacturer`
+  * Definition: Kit manufacturer name (for kit-built aircraft).
+  * Derivation: `KIT MFR` from MASTER.txt (positions 550-579).
+
+* `kit_model`
+  * Definition: Kit model name.
+  * Derivation: `KIT MODEL` from MASTER.txt (positions 581-600).
+
+### Aircraft Properties (from DEREG.txt -- additional fields)
+
+Deregistered aircraft share all properties above where available, plus:
+
+* `cancel_date`
+  * Definition: Date the registration was canceled.
+  * Examples: `"2023/01/15"`
+  * Derivation: `CANCEL DATE` from DEREG.txt (positions 240-247).
+
+* `export_country`
+  * Definition: Country the aircraft was exported to upon deregistration.
+  * Examples: `"CANADA"`, `"BRAZIL"`
+  * Derivation: `EXPORT COUNTRY` from DEREG.txt (positions 260-277).
+
+### Organization Properties (from DEALER.txt)
+
+#### Identity
+
+* `dealer_certificate_number`
+  * Definition: FAA dealer certificate number.
+  * Examples: `"24-0001"`, `"23-1234"`
+  * Derivation: `CERTIFICATE NUMBER` from DEALER.txt (positions 1-7), format YY-NNNN.
+
+* `dealer_ownership_type`
+  * Definition: Ownership type of the dealer.
+  * Examples: `"Individual"`, `"Corporation"`, `"LLC"`
+  * Derivation: `OWNERSHIP` from DEALER.txt (position 9), decoded: 1=Individual, 2=Partnership, 3=Corporation, 4=Co-Ownership, 7=LLC, 8=Non Citizen Corporation.
+
+* `dealer_certificate_issue_date`
+  * Definition: Date the dealer certificate was issued.
+  * Derivation: `CERTIFICATE ISSUE DATE` from DEALER.txt (positions 11-18), format YYYYMMDD.
+
+* `dealer_expiration_date`
+  * Definition: Dealer certificate expiration date.
+  * Derivation: `EXPIRATION DATE` from DEALER.txt (positions 20-27), format YYYYMMDD.
+
+* `dealer_expired`
+  * Definition: Whether the dealer certificate has expired.
+  * Examples: `"true"`, `"false"`
+  * Derivation: `EXPIRATION FLAG` from DEALER.txt (position 29), `*` = true.
+
+#### Address
+
+* `dealer_address`
+  * Definition: Mailing address of the dealer.
+  * Derivation: Concatenation of DEALER.txt address fields (STREET1, STREET2, CITY, STATE, ZIP CODE).
+
+### Document Properties (from DOCINDEX.txt)
+
+* `faa_document_id`
+  * Definition: Unique document identifier assigned by the FAA.
+  * Examples: `"000123456789"`
+  * Derivation: `DOCUMENT ID` from DOCINDEX.txt (positions 92-103).
+
+* `collateral_type`
+  * Definition: Type of collateral the document pertains to.
+  * Examples: `"Aircraft"`, `"Engine"`, `"Propeller"`, `"Spare Parts"`
+  * Derivation: `TYPE COLLATERAL` from DOCINDEX.txt (position 1), decoded: 1=Aircraft, 2=Engine, 3=Propeller, 4=Spare Parts, 5=Document, 9=Unidentified.
+
+* `collateral_identifier`
+  * Definition: Collateral identification -- typically an N-number for aircraft, or make/model/serial for engines and propellers.
+  * Derivation: `COLLATERAL` from DOCINDEX.txt (positions 3-39).
+
+* `document_receipt_date`
+  * Definition: Date the document was filed for recordation with the Aircraft Registry.
+  * Derivation: `DOCUMENT RECEIPT DATE` from DOCINDEX.txt (positions 105-112), format YYYYMMDD.
+
+* `document_type`
+  * Definition: Type of document being indexed.
+  * Examples: `"BOS"` (Evidence of Ownership), `"S/A"` (Security Conveyance/Lien), `"REL"` (Lien Release)
+  * Derivation: `DOC TYPE` from DOCINDEX.txt (positions 165-167).
+
+### Aircraft Properties (from RESERVED.txt)
+
+Reserved N-numbers produce minimal `aircraft` records:
+
+* `reservation_type`
+  * Definition: Type of N-number reservation.
+  * Examples: `"Fee paid"`, `"Reserved to manufacturer"`, `"N-Number change in process"`
+  * Derivation: `TYPE RESERVATION` from RESERVED.txt (positions 168-169), decoded.
+
+* `reservation_date`
+  * Definition: Date the N-number was reserved.
+  * Derivation: `RESERVE DATE` from RESERVED.txt (positions 159-166), format YYYYMMDD.
+
+* `reservation_expiration_date`
+  * Definition: Date the reservation expiration notice was sent.
+  * Derivation: `EXPIRATION NOTICE DATE` from RESERVED.txt (positions 171-178), format YYYYMMDD.
+
+---
+
+## Entity Relationships
+
+```
+aircraft      ──[is_located_at]──────→ location        (registrant city/state)
+aircraft      ──[has_document]───────→ document         (via N-number in DOCINDEX collateral)
+organization  ──[is_located_at]──────→ location         (dealer address)
+```
+
+---

package/skill/faaregistry/schema.yaml

@@ -0,0 +1,386 @@
+# Dataset schema for FAA Releasable Aircraft Database.
+#
+# Source: https://www.faa.gov/licenses_certificates/aircraft_certification/aircraft_registry/releasable_aircraft_download
+# Updated daily at 11:30 PM CT.
+#
+# This schema describes U.S. civil aircraft registrations from the FAA
+# Aircraft Registry, including MASTER.txt records joined with ENGINE.txt
+# reference data for engine manufacturer, model, and performance details.
+name: "faaregistry"
+description: "FAA aircraft registration data including N-number identity, aircraft and engine details, registration status, certification, and registrant information"
+
+extraction:
+  flavors: closed
+  properties: closed
+  relationships: closed
+  attributes: closed
+  events: closed
+
+flavors:
+  - name: "aircraft"
+    description: "An aircraft such as a plane, helicopter, glider, or unmanned aerial vehicle"
+    display_name: "Aircraft"
+    mergeability: not_mergeable
+    strong_id_properties: ["aircraft_id"]
+    passive: true
+
+  - name: "organization"
+    description: "A particular business, institution, or organization such as a corporation, university, government agency, or non-profit"
+    display_name: "Organization"
+    mergeability: not_mergeable
+    passive: true
+
+  - name: "person"
+    description: "A named individual such as a business owner, executive, or public figure"
+    display_name: "Person"
+    mergeability: not_mergeable
+    passive: true
+
+  - name: "location"
+    description: "A specific named geographic location such as a city, country, region, or landmark"
+    display_name: "Location"
+    mergeability: not_mergeable
+    examples: ["WICHITA, KS", "SEATTLE, WA", "ATLANTA, GA"]
+    passive: true
+
+properties:
+  # Identity and Registration
+  - name: "aircraft_id"
+    type: string
+    description: "Composite aircraft identifier combining manufacturer name and serial number (format: MANUFACTURER:SERIAL)"
+    display_name: "Aircraft ID"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["CESSNA:172S10245", "BOEING:28-7990244"]
+    passive: true
+
+  - name: "n_number"
+    type: string
+    description: "FAA registration N-number uniquely identifying a U.S. civil aircraft"
+    display_name: "N-Number"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["12345", "789AB"]
+    passive: true
+
+  - name: "serial_number"
+    type: string
+    description: "Complete aircraft serial number assigned by the manufacturer"
+    display_name: "Serial Number"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["28-7990244", "172S10245"]
+    passive: true
+
+  - name: "mode_s_code_hex"
+    type: string
+    description: "Aircraft Mode S transponder code in hexadecimal format (ICAO 24-bit address)"
+    display_name: "Mode S Code (Hex)"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["A12345", "ABCDEF"]
+    passive: true
+
+  - name: "mode_s_code"
+    type: string
+    description: "Aircraft Mode S transponder code in octal format"
+    display_name: "Mode S Code"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "unique_id"
+    type: string
+    description: "FAA-assigned unique identification number for the registration record"
+    display_name: "Unique ID"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  # Aircraft Details (joined from ACFTREF.txt)
+  - name: "manufacturer_name"
+    type: string
+    description: "Name of the aircraft manufacturer, joined from the FAA aircraft reference table"
+    display_name: "Manufacturer Name"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["CESSNA", "BOEING", "PIPER", "BEECH"]
+    passive: true
+
+  - name: "model_name"
+    type: string
+    description: "Aircraft model and series name, joined from the FAA aircraft reference table"
+    display_name: "Model Name"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["172S", "737-800", "PA-28-181"]
+    passive: true
+
+  - name: "number_of_engines"
+    type: string
+    description: "Number of engines on the aircraft, from the FAA aircraft reference table"
+    display_name: "Number of Engines"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["1", "2", "4"]
+    passive: true
+
+  - name: "number_of_seats"
+    type: string
+    description: "Maximum number of seats in the aircraft, from the FAA aircraft reference table"
+    display_name: "Number of Seats"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["4", "189", "12"]
+    passive: true
+
+  - name: "aircraft_weight_class"
+    type: string
+    description: "Maximum gross takeoff weight classification of the aircraft"
+    display_name: "Aircraft Weight Class"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Up to 12,499 lbs", "12,500 - 19,999 lbs", "20,000 and over"]
+    passive: true
+
+  - name: "cruising_speed"
+    type: string
+    description: "Average cruising speed of the aircraft in miles per hour, from the FAA aircraft reference table"
+    display_name: "Cruising Speed"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["124", "530"]
+    passive: true
+
+  - name: "aircraft_category"
+    type: string
+    description: "Land, sea, or amphibian classification of the aircraft"
+    display_name: "Aircraft Category"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Land", "Sea", "Amphibian"]
+    passive: true
+
+  - name: "builder_certification"
+    type: string
+    description: "Builder certification classification indicating whether the aircraft is type certificated"
+    display_name: "Builder Certification"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Type Certificated", "Not Type Certificated", "Light Sport"]
+    passive: true
+
+  - name: "type_certificate_data_sheet"
+    type: string
+    description: "FAA Type Certificate Data Sheet reference number"
+    display_name: "TC Data Sheet"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "type_certificate_holder"
+    type: string
+    description: "Name of the Type Certificate holder for this aircraft model"
+    display_name: "TC Data Holder"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "aircraft_type"
+    type: string
+    description: "Type of aircraft such as fixed wing, rotorcraft, glider, or balloon"
+    display_name: "Aircraft Type"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Fixed wing single engine", "Rotorcraft", "Balloon"]
+    passive: true
+
+  - name: "engine_type"
+    type: string
+    description: "Type of engine installed on the aircraft"
+    display_name: "Engine Type"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Reciprocating", "Turbo-fan", "Electric"]
+    passive: true
+
+  - name: "year_manufactured"
+    type: string
+    description: "Year the aircraft was manufactured"
+    display_name: "Year Manufactured"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["1978", "2023"]
+    passive: true
+
+  # Joined Engine Details (from ENGINE.txt)
+  - name: "engine_manufacturer"
+    type: string
+    description: "Name of the engine manufacturer, joined from the FAA engine reference table"
+    display_name: "Engine Manufacturer"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["LYCOMING", "CONT MOTOR", "P&W"]
+    passive: true
+
+  - name: "engine_model"
+    type: string
+    description: "Engine model name, joined from the FAA engine reference table"
+    display_name: "Engine Model"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["O-320-D2J", "IO-540"]
+    passive: true
+
+  - name: "engine_horsepower"
+    type: string
+    description: "Engine horsepower for reciprocating and turboprop engines, from the FAA engine reference table"
+    display_name: "Engine Horsepower"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["180", "310"]
+    passive: true
+
+  - name: "engine_thrust"
+    type: string
+    description: "Engine thrust in pounds for turbojet and turbofan engines, from the FAA engine reference table"
+    display_name: "Engine Thrust"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["27300", "56000"]
+    passive: true
+
+  # Registration Status
+  - name: "aircraft_registration_status"
+    type: string
+    description: "Current FAA registration status of the aircraft"
+    display_name: "Registration Status"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Valid Registration", "Registration Expired", "Sale reported"]
+    passive: true
+
+  - name: "registrant_type"
+    type: string
+    description: "Type of entity that owns the aircraft"
+    display_name: "Registrant Type"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    examples: ["Individual", "Corporation", "LLC", "Government"]
+    passive: true
+
+  - name: "fractional_ownership"
+    type: string
+    description: "Whether the aircraft registration has fractional ownership"
+    display_name: "Fractional Ownership"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["true", "false"]
+    passive: true
+
+  # Certification
+  - name: "airworthiness_class"
+    type: string
+    description: "FAA airworthiness certificate classification"
+    display_name: "Airworthiness Class"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["Standard", "Experimental", "Restricted", "Light Sport"]
+    passive: true
+
+  # Registrant address (on person/organization entities)
+  - name: "address"
+    type: string
+    description: "Physical street address of the entity"
+    display_name: "Address"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    examples: ["1030 DELTA BLVD, ATLANTA, GA 30354"]
+    passive: true
+
+  # Dates
+  - name: "last_activity_date"
+    type: string
+    description: "Date of last registration activity"
+    display_name: "Last Activity Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "certificate_issue_date"
+    type: string
+    description: "Date the registration certificate was issued"
+    display_name: "Certificate Issue Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "airworthiness_date"
+    type: string
+    description: "Date of airworthiness certification"
+    display_name: "Airworthiness Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "expiration_date"
+    type: string
+    description: "Certificate of Registration expiration date"
+    display_name: "Expiration Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  # DEREG.txt-specific
+  - name: "cancel_date"
+    type: string
+    description: "Date the aircraft registration was canceled"
+    display_name: "Cancel Date"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "export_country"
+    type: string
+    description: "Country the aircraft was exported to upon deregistration"
+    display_name: "Export Country"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    examples: ["AUSTRALIA", "CANADA", "BRAZIL"]
+    passive: true
+
+  # Kit Aircraft
+  - name: "kit_manufacturer"
+    type: string
+    description: "Kit manufacturer name for kit-built aircraft"
+    display_name: "Kit Manufacturer"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+  - name: "kit_model"
+    type: string
+    description: "Kit model name for kit-built aircraft"
+    display_name: "Kit Model"
+    mergeability: not_mergeable
+    domain_flavors: ["aircraft"]
+    passive: true
+
+relationships:
+  - name: "owns_aircraft"
+    description: "A person or organization owns (is the registered owner of) an aircraft"
+    display_name: "Owns Aircraft"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    target_flavors: ["aircraft"]
+    examples: ["DELTA AIR LINES INC owns aircraft N12345"]
+    passive: true
+
+  - name: "is_located_at"
+    description: "An entity is located at, operates in, resides in, is headquartered in, was born in, visits, or died in a location"
+    display_name: "Located At"
+    mergeability: not_mergeable
+    domain_flavors: ["person", "organization"]
+    target_flavors: ["location"]
+    examples: ["DELTA AIR LINES INC is located at ATLANTA, GA"]
+    passive: true

package/skill/sanctions/schema.yaml

@@ -51,7 +51,7 @@ flavors:
     passive: true
 
   - name: "aircraft"
-    description: "An airplane identified in sanctions designations"
+    description: "An aircraft such as a plane, helicopter, glider, or unmanned aerial vehicle"
     display_name: "Aircraft"
     mergeability: not_mergeable
     strong_id_properties: ["sanctions_id"]