{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.fleetfax.com/schema/carrier-risk-profile-v1.json",
  "title": "fleetfax Carrier Risk Profile",
  "version": "1.0.0",
  "description": "The published, versioned shape of a fleetfax carrier risk profile: the public FMCSA record for one US motor carrier or freight broker, as fleetfax surfaces it. This is the object our REST alias returns as `carrier` (GET https://api.fleetfax.com/ai/carrier/{query}) and our MCP connector returns as `snapshot` (get_carrier_details), field-for-field. It is DESCRIPTIVE, not prescriptive: fleetfax surfaces the federal facts as findings; the broker makes the booking judgment. There is no book / do-not-book field and no composite safety, risk, or quality score anywhere in this schema, by design. Every value is a restatement of a public record (FMCSA census, Socrata authority/insurance/inspection feeds, and the Motus L&I registry), never an inference beyond what the record states. The response envelope that carries this object also carries a `report_url` (the live fleetfax report) and an `attribution` string; those are documented in $defs.envelope but are not part of the profile object itself.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "usdot",
    "legal_name",
    "verdict",
    "authority",
    "insurance",
    "safety_rating",
    "fleet",
    "operation",
    "physical_address",
    "mcs150_last_filed",
    "findings"
  ],
  "properties": {
    "usdot": {
      "type": "string",
      "pattern": "^[0-9]{1,8}$",
      "description": "The carrier's USDOT number, the canonical primary key, always emitted as a STRING (never a JSON number) so leading context and identifier semantics are preserved. Source: FMCSA census. Example (unissued, illustrative): \"9999999\"."
    },
    "legal_name": {
      "type": "string",
      "description": "The carrier's legal name as registered with FMCSA, title-cased. Falls back to the DBA name, then to \"USDOT <n>\", if no legal name is on file. Source: FMCSA census."
    },
    "dba_name": {
      "type": ["string", "null"],
      "description": "The carrier's doing-business-as name, title-cased, or null when there is no DBA distinct from the legal name. Source: FMCSA census."
    },
    "mc_number": {
      "type": ["string", "null"],
      "description": "The carrier's primary docket number in compact form. Most often an MC docket (e.g. an unissued, illustrative \"MC9999999\"), but it may also be an MX (Mexican) or FF (freight-forwarder) docket when that is the docket on file: fleetfax emits the first docket available, not only MC. Null when no docket is on file. It is a legacy lookup key that resolves to the USDOT number. Source: FMCSA authority (Licensing & Insurance).",
      "pattern": "^(MC|MX|FF)[0-9]+$"
    },
    "verdict": {
      "type": "string",
      "description": "A one-line DESCRIPTIVE summary of the findings below. Never booking advice, never a score. It takes one of these shapes: \"Blocking issues found\" (one or more hard-stop findings present); \"N issues to review\" or \"N cautions found\" (a critical or caution finding present, no hard-stop); \"No blocking issues found\" or \"No blockers or cautions found\" (clean). The machine-readable tier behind this line is verdict_state. Source: computed over `findings` by fleetfax; see https://www.fleetfax.com/methodology.",
      "examples": ["No blockers or cautions found", "2 cautions found", "1 issue to review", "Blocking issues found"]
    },
    "verdict_state": {
      "$ref": "#/$defs/verdict_state"
    },
    "authority": {
      "type": "string",
      "description": "A plain-language restatement of the carrier's federal operating authority: which dockets (common, contract, broker) are active, inactive, or pending, whether the USDOT registration is inactive, whether a revocation is pending, and whether federal authority is not applicable (an intrastate operation needs no federal docket). Source: FMCSA authority + Motus L&I. This describes the record; it does not assert the carrier is or is not permitted to haul a specific load."
    },
    "insurance": {
      "type": "string",
      "description": "A plain-language restatement of the insurance on file with FMCSA: whether liability (BIPD) coverage is on file and its dollar amount when published, whether cargo coverage is on file, and whether a cancellation is pending. HOUSE FACT (do not misread): FMCSA's `cancl_effective_date` is the scheduled annual TERM-END of a policy, NOT a processed cancellation; a coverage end-date on file can be a routine renewal boundary or a pending cancellation, so the record states the ambiguity rather than asserting a lapse. A BIPD filing row with no dollar amount means a bond or self-insurance instrument is in force (its presence means in force), not that coverage is absent. Source: Socrata ActPendInsur (qh9u-swkp) + FMCSA on-file flags."
    },
    "safety_rating": {
      "type": "string",
      "description": "The carrier's published FMCSA safety rating and the date of the rating decision when present (e.g. \"Satisfactory (rating decision 2021-03-14)\"), or \"No published safety rating\" when none is on file. Most active carriers carry no published rating; absence is not a negative fact. Source: FMCSA census (safety rating)."
    },
    "fleet": {
      "type": "string",
      "description": "The carrier's self-reported fleet size as filed on the MCS-150, e.g. \"12 power units, 15 drivers\". Self-reported, not fleetfax-verified. Source: FMCSA census."
    },
    "operation": {
      "type": "string",
      "description": "The carrier's operation classification (e.g. \"Interstate\"), or \"Not specified\". Source: FMCSA census (carrier operation)."
    },
    "physical_address": {
      "type": "string",
      "description": "The carrier's physical (domicile) address on file, or \"Not on file\". This is the identity block's domicile field. Source: FMCSA census."
    },
    "mcs150_last_filed": {
      "type": "string",
      "description": "The date the carrier last filed its MCS-150 (biennial update), formatted for display, or \"Not on file\". A stale MCS-150 is surfaced as a finding, not inferred here. Source: FMCSA census."
    },
    "safety_record": {
      "type": ["string", "null"],
      "description": "A one-line restatement of the carrier's 24-month roadside record: inspection count, vehicle out-of-service rate, and recordable crash count (e.g. \"48 roadside inspections, 12.5% vehicle out-of-service rate, 1 recordable crash.\"). Null for brokers, which have no inspection record by definition. Source: FMCSA inspections + crashes (Socrata)."
    },
    "findings": {
      "type": "array",
      "description": "The discrete, editorial facts fleetfax found true in the federal record right now, each surfaced as a caution the broker weighs. An empty array means no critical or caution findings were present. Each finding is a fact about the record, never an instruction. The stable machine identifier for a finding is its `id` (the reason code); the human-facing fields are `severity`, `title`, and `detail`.",
      "items": { "$ref": "#/$defs/finding" }
    },
    "as_of": {
      "$ref": "#/$defs/as_of"
    }
  },
  "$defs": {
    "verdict_state": {
      "type": "string",
      "enum": ["blocking", "cautions", "none"],
      "description": "The machine-readable DESCRIPTIVE tier derived from the record, mapped from the internal verdict tier behind the `verdict` line (ssrComputeVerdict). \"blocking\": one or more hard-stop findings present (the verdict reads \"Blocking issues found\"); the hard-stop reason codes are FLAG-OOS, FLAG-00a, FLAG-00b, and FLAG-INS-LAPSED. \"cautions\": a critical or caution finding present, no hard-stop (the verdict reads \"N cautions found\"). \"none\": only informational notes, or nothing (the verdict reads \"No blockers or cautions found\"). These are descriptive tokens, never a book / do-not-book instruction and never a numeric score. It is an optional, additive projection of that tier; the response payload itself carries the human `verdict` line, so real output validates whether or not this field is present."
    },
    "finding": {
      "type": "object",
      "additionalProperties": false,
      "required": ["severity", "title"],
      "properties": {
        "severity": {
          "type": "string",
          "enum": ["Critical", "Caution"],
          "description": "The finding's surfaced severity. \"Critical\" and \"Caution\" are the two values emitted on this summary surface; informational notes are folded into \"Caution\" here. The full engine severity ceiling (critical / caution / info) is carried on the live report."
        },
        "title": {
          "type": "string",
          "description": "The human-facing one-line statement of the finding, e.g. \"Active for less than 6 months, limited vetting history\". Descriptive; never an instruction."
        },
        "detail": {
          "type": ["string", "null"],
          "description": "An optional second line expanding the finding (the flag subtitle), or null."
        },
        "id": {
          "$ref": "#/$defs/flag_id"
        }
      },
      "description": "One finding: a stable reason code (`id`) plus its human severity, title, and detail. On the free summary surface `id` is omitted (the surface emits severity + title + detail only); it is published here as the standard's stable reason-code vocabulary and matches the `blocking[].id` field on structured surfaces."
    },
    "flag_id": {
      "type": "string",
      "description": "The STABLE reason code for a finding. These identifiers are the canonical, code-derived fleetfax flag ids (docs/signals-registry.md); the enum is closed at v1.0.0 of this schema and new ids ship in a new schema version. Titles and severities may be re-worded; the id is the durable contract.",
      "enum": [
        "FLAG-OOS",
        "FLAG-CHA",
        "FLAG-DOR",
        "FLAG-FLEET-DISPERSED",
        "FLAG-00a",
        "FLAG-00b",
        "FLAG-AUTH-UNVERIFIED",
        "FLAG-02",
        "FLAG-INS-LAPSED",
        "FLAG-03",
        "FLAG-INS-BOND-GAP",
        "FLAG-07",
        "FLAG-SAFETY-STALE",
        "FLAG-MCS-STALE",
        "FLAG-FLEET",
        "FLAG-OFFICER-REVOKED",
        "FLAG-FLEET-SUCCESSION",
        "FLAG-SHARED-FLEET",
        "FLAG-11",
        "FLAG-12",
        "FLAG-13",
        "FLAG-ENFORCEMENT-CASE",
        "FLAG-01",
        "FLAG-05",
        "FLAG-06",
        "FLAG-BASIC-ALERT",
        "FLAG-08",
        "FLAG-FATAL",
        "FLAG-HAZMAT-UNDECLARED",
        "FLAG-09",
        "FLAG-10"
      ]
    },
    "as_of": {
      "type": ["object", "null"],
      "additionalProperties": false,
      "description": "Response-level freshness and provenance, emitted at the response envelope on structured surfaces (MCP get_carrier_details). The free summary omits it. There is no per-field as_of: fields carry provenance through their descriptions (which name each field's source feed), and this object states when the response was assembled. All fleetfax data is public-record data restated; observed is not booked, absence is not proof, self-reported is not verified.",
      "properties": {
        "retrieved_at": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when fleetfax assembled this response."
        },
        "timeline_observed_since": {
          "type": ["string", "null"],
          "description": "ISO date fleetfax began observing this carrier's change history, or null when unavailable. Structured surfaces only."
        }
      }
    },
    "envelope": {
      "type": "object",
      "description": "The response envelope that carries a Carrier Risk Profile. Documented for reference; the profile object above is the schema's subject. `/ai/carrier` returns { carrier, report_url, attribution }; MCP get_carrier_details returns { snapshot, timeline, insurance_history, oos_orders, report_url, as_of, attribution }.",
      "properties": {
        "carrier": { "$ref": "#" },
        "snapshot": { "$ref": "#" },
        "report_url": {
          "type": "string",
          "format": "uri",
          "description": "The canonical, permanently reachable fleetfax report URL: https://www.fleetfax.com/carrier/<usdot>."
        },
        "attribution": {
          "type": "string",
          "description": "The stable attribution string fleetfax asks integrators to cite alongside the data."
        }
      }
    }
  }
}