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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottagraph-app/data-model-skill",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "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