{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/terminal-telematics/json-schema/terminal-telematics-fault-code-event-schema.json",
  "title": "Fault Code Event",
  "x-generated": "2026-11-15",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/terminal.openapi.json#/components/schemas/FaultCodeEvent",
  "x-model-category": "time-series",
  "x-read-permission": "fault-codes:read",
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/$defs/FaultCodeEventId"
    },
    "provider": {
      "$ref": "#/$defs/ProviderCode"
    },
    "vehicle": {
      "$ref": "#/$defs/ExpandableVehicle",
      "description": "The vehicle associated with the fault."
    },
    "protocol": {
      "$ref": "#/$defs/FaultCodeProtocol"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "pending",
        "closed"
      ],
      "description": "The status of the fault code at the time of the event. Some providers do not report closed statuses."
    },
    "code": {
      "type": "string",
      "description": "The fault code identifier. For OBD-II systems: alphanumeric DTC codes (P0087, U0046, C0123, B1234). For J1939 systems: SPN-FMI format (SPN3031-FMI9) or derived codes from SPN/FMI combinations."
    },
    "description": {
      "type": "string",
      "description": "Human-readable description of the fault"
    },
    "observedAt": {
      "$ref": "#/$defs/ISODateTime",
      "description": "The time the fault code was observed"
    },
    "milStatus": {
      "type": "string",
      "enum": [
        "on",
        "off"
      ],
      "description": "The Malfunction Indicator Lamp (MIL) status of the vehicle at the time the fault code was observed"
    },
    "obdii": {
      "type": "object",
      "description": "OBD-II Diagnostic Trouble Code information for light/medium duty vehicles. Contains standardized alphanumeric codes like P0087, U0046, C0123, B1234.",
      "properties": {
        "code": {
          "type": "string",
          "description": "Alphanumeric DTC code (e.g., P0087, U0046)"
        },
        "description": {
          "type": "string",
          "description": "Human-readable description of the DTC"
        }
      },
      "required": [
        "code"
      ]
    },
    "j1939": {
      "type": "object",
      "description": "J1939 fault code information for heavy-duty vehicles. FMI (Failure Mode Identifier) indicates the specific nature of the fault (0-31 numeric codes).",
      "properties": {
        "fmi": {
          "type": "integer",
          "description": "Failure Mode Identifier (FMI) - numeric code (0-31) indicating the specific nature of the fault"
        },
        "fmiDescription": {
          "type": "string",
          "description": "Human-readable description of the FMI failure mode"
        },
        "spn": {
          "type": "integer",
          "description": "Suspect Parameter Number (SPN) - identifies the specific parameter/system affected"
        },
        "spnDescription": {
          "type": "string",
          "description": "Human-readable description of the SPN parameter/system"
        },
        "occurrenceCount": {
          "type": "integer",
          "description": "The occurrence count reported by the provider at the time the fault code was observed"
        },
        "sourceAddress": {
          "type": "integer",
          "description": "The source address of the fault code"
        }
      },
      "required": [
        "spn"
      ]
    },
    "metadata": {
      "$ref": "#/$defs/EntityMetadata"
    },
    "raw": {
      "$ref": "#/$defs/RawDataList"
    }
  },
  "oneOf": [
    {
      "title": "FaultCodeEventObdii",
      "properties": {
        "protocol": {
          "const": "obdii"
        }
      },
      "required": [
        "protocol",
        "obdii"
      ]
    },
    {
      "title": "FaultCodeEventJ1939",
      "properties": {
        "protocol": {
          "const": "j1939"
        }
      },
      "required": [
        "protocol",
        "j1939"
      ]
    }
  ],
  "required": [
    "id",
    "provider",
    "vehicle",
    "code",
    "protocol",
    "observedAt",
    "status",
    "metadata"
  ],
  "x-description": "A fault code observed at a specific time",
  "$defs": {
    "AddedAt": {
      "title": "AddedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was ingested into Terminal. Note: this is not the date and time the record was created in the provider's system."
    },
    "CoreEntityMetadata": {
      "title": "CoreEntityMetadata",
      "type": "object",
      "description": "Internal metadata about the record.",
      "required": [
        "addedAt",
        "modifiedAt"
      ],
      "properties": {
        "addedAt": {
          "$ref": "#/$defs/AddedAt"
        },
        "modifiedAt": {
          "$ref": "#/$defs/ModifiedAt"
        },
        "deletedAt": {
          "$ref": "#/$defs/DeletedAt"
        },
        "visibility": {
          "type": "string",
          "enum": [
            "visible",
            "hidden_by_exclude_list",
            "hidden_by_include_list",
            "hidden_by_status",
            "deleted"
          ],
          "description": "Visibility status of a resource. Read more about hidden records [here](https://docs.withterminal.com/guides/vehicle-driver-filtering)."
        }
      }
    },
    "DeletedAt": {
      "title": "DeletedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was deleted from Terminal. Note: this is not the date and time the record was deleted in the provider's system."
    },
    "DeviceId": {
      "title": "DeviceId",
      "type": "string",
      "format": "ulid"
    },
    "EntityMetadata": {
      "title": "EntityMetadata",
      "type": "object",
      "description": "Internal metadata about the record.",
      "required": [
        "addedAt",
        "modifiedAt"
      ],
      "properties": {
        "addedAt": {
          "$ref": "#/$defs/AddedAt"
        },
        "modifiedAt": {
          "$ref": "#/$defs/ModifiedAt"
        }
      }
    },
    "ExpandableVehicle": {
      "oneOf": [
        {
          "$ref": "#/$defs/VehicleId"
        },
        {
          "$ref": "#/$defs/ExpandedVehicle"
        }
      ]
    },
    "ExpandedVehicle": {
      "title": "Expanded Vehicle",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "$ref": "#/$defs/VehicleId"
        },
        "sourceId": {
          "$ref": "#/$defs/SourceId"
        },
        "provider": {
          "$ref": "#/$defs/ProviderCode"
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "inactive"
          ],
          "description": "The status in the providers system"
        },
        "vin": {
          "title": "VIN",
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "make": {
          "type": "string"
        },
        "model": {
          "type": "string"
        },
        "year": {
          "type": "integer"
        },
        "groups": {
          "type": "array",
          "description": "The groups the vehicle belongs to.",
          "items": {
            "$ref": "#/$defs/GroupId"
          }
        },
        "devices": {
          "type": "array",
          "description": "The devices installed in the vehicle.",
          "items": {
            "$ref": "#/$defs/DeviceId"
          }
        },
        "licensePlate": {
          "type": "object",
          "properties": {
            "state": {
              "$ref": "#/$defs/State"
            },
            "number": {
              "type": "string"
            }
          }
        },
        "fuelType": {
          "enum": [
            "gasoline",
            "diesel",
            "propane",
            "electric",
            "hybrid_gasoline",
            "hybrid_diesel",
            "biodiesel",
            "compressed_natural_gas",
            "liquefied_natural_gas",
            "ethanol",
            "hydrogen",
            "plug_in_hybrid"
          ]
        },
        "fuelEfficiency": {
          "type": "number",
          "deprecated": true,
          "description": "This field will be removed in the future as is not commonly available from providers."
        },
        "fuelTankCapacity": {
          "description": "Maximum amount of fuel vehicle can hold in liters.",
          "title": "Volume In Liters",
          "type": "number"
        },
        "createdAt": {
          "$ref": "#/$defs/SourceCreatedAt"
        },
        "updatedAt": {
          "$ref": "#/$defs/SourceUpdatedAt"
        },
        "metadata": {
          "$ref": "#/$defs/CoreEntityMetadata"
        },
        "raw": {
          "$ref": "#/$defs/RawDataList"
        }
      },
      "required": [
        "id",
        "sourceId",
        "provider",
        "status",
        "metadata"
      ],
      "x-description": "The model representing a vehicle in Terminal."
    },
    "FaultCodeEventId": {
      "title": "FaultCodeEventId",
      "type": "string",
      "format": "ulid"
    },
    "FaultCodeProtocol": {
      "type": "string",
      "enum": [
        "j1939",
        "obdii"
      ],
      "description": "The diagnostic protocol used"
    },
    "GroupId": {
      "title": "GroupId",
      "type": "string",
      "format": "ulid"
    },
    "ISODateTime": {
      "title": "ISODateTime",
      "type": "string",
      "format": "date-time",
      "description": "[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date"
    },
    "ModifiedAt": {
      "title": "ModifiedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider's system."
    },
    "ProviderCode": {
      "type": "string",
      "description": "Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers)."
    },
    "RawData": {
      "title": "RawData",
      "type": "object",
      "properties": {
        "provider": {
          "type": "string"
        },
        "schema": {
          "type": "string"
        },
        "extractedAt": {
          "type": "string"
        },
        "data": {
          "type": "object"
        }
      },
      "required": [
        "provider",
        "schema",
        "extractedAt",
        "data"
      ]
    },
    "RawDataList": {
      "title": "RawDataList",
      "type": "array",
      "items": {
        "$ref": "#/$defs/RawData"
      }
    },
    "SourceCreatedAt": {
      "title": "SourceCreatedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was created in the provider's system. This timestamp comes directly from the source system and represents when the data was originally created there. Note: not all providers expose this."
    },
    "SourceId": {
      "title": "SourceId",
      "type": "string",
      "description": "The ID used to represent the entity in the source system."
    },
    "SourceUpdatedAt": {
      "title": "SourceUpdatedAt",
      "type": "string",
      "format": "date-time",
      "description": "The date and time the record was updated in the provider's system. This timestamp comes directly from the source system and represents when the data was last updated there. Note: not all providers expose this."
    },
    "State": {
      "title": "State",
      "type": "string",
      "enum": [
        "AL",
        "AK",
        "AS",
        "AZ",
        "AR",
        "CA",
        "CO",
        "CT",
        "DE",
        "FL",
        "GA",
        "GU",
        "HI",
        "ID",
        "IL",
        "IN",
        "IA",
        "KS",
        "KY",
        "LA",
        "ME",
        "MD",
        "MA",
        "MI",
        "MN",
        "MP",
        "MS",
        "MO",
        "MT",
        "NE",
        "NV",
        "NH",
        "NJ",
        "NM",
        "NY",
        "NC",
        "ND",
        "OH",
        "OK",
        "OR",
        "PA",
        "PR",
        "RI",
        "SC",
        "SD",
        "TN",
        "TX",
        "UT",
        "VT",
        "VA",
        "WA",
        "WV",
        "WI",
        "WY",
        "VI",
        "AB",
        "BC",
        "MB",
        "NB",
        "NL",
        "NS",
        "ON",
        "PE",
        "QC",
        "SK",
        "NT",
        "NU",
        "UM",
        "YT",
        "DC"
      ],
      "description": "US State or Canadian Province"
    },
    "VehicleId": {
      "title": "VehicleId",
      "description": "Unique identifier for the vehicle in Terminal.",
      "type": "string",
      "format": "ulid",
      "pattern": "^vcl_[0-9A-HJKMNP-TV-Z]{26}$"
    }
  }
}