defects

Faults recorded against a vehicle or a component. Delivered daily. Update key: external_system_id

Columns

Column	Type	Required	Notes
`external_system_id`	text(100)	●	Update key
`defect_datetime`	timestamptz	●	When the fault occurred
`defect_title`	text(60)	●	Maximum 60 characters
`defect_description`	text	●
`location`	text(100)	○	Location on the vehicle or component
`vehicle_number`	text(100)	○	Must exist in project. Required unless `component_serial_number` is set
`component_serial_number`	text(100)	○	Must exist in project
`action_code`	text(50)	○	Free text, not validated
`action_description`	text(255)	○
`cause_code`	text(50)	○	Free text, not validated
`cause_description`	text(255)	○
`fault_indication_code`	text(50)	○	Free text, not validated
`warranty_flag`	boolean	●	`True` / `False`, never empty
`last_updated`	timestamptz	●	Staleness key
`consequence_code`	text(50)	○
`consequence_description`	text(255)	○
`category`	text(100)	○	Free text, e.g. `Mechanical`
`severity`	text(50)	○	Free text, e.g. `Major`
`delay_minutes`	integer	○	Operational delay caused
`closed_date`	timestamptz	○	Empty means still open
`product_group_code`	text(100)	●	Product group code on the vehicle’s type. Must resolve, or the file is rejected
`slot_position`	text(20)	○	Position on the vehicle’s type, looked up on `product_group_code` or one of its ancestors. Matched exactly, case-sensitive. Optional; a value that is sent must match, or the file is rejected

Rules

Every row needs at least one of vehicle_number / component_serial_number.
vehicle_number and component_serial_number must resolve within the project, or the file is rejected.
product_group_code must resolve to a product group of the vehicle’s type, or the file is rejected. On a component-only row the vehicle is the one in the configuration record covering defect_datetime; a component with no covering record, or with overlapping ones, has no vehicle type to resolve the code on and the row is rejected.
slot_position only means something together with product_group_code — the pair identifies a slot on the vehicle’s type. The vehicle type comes from the vehicle; never send it.
A slot_position that is sent must resolve, or the file is rejected. Leave it empty when the source does not know the position; the mount history fills the slot where it can.
location is free text and is never parsed. Send the position in slot_position if you want it recorded as a position; writing Bogie 1 in location does not resolve a slot, and neither field replaces the other.

Every reference in this file is hard: a value that is sent must resolve, or the file is rejected. Optional references may be left empty.

Unlike every other file, defects reports all of its error classes in one message rather than aborting at the first failing stage.

Resolution rules

The import resolves the fields the row names first, then fills those still empty from the configuration record covering defect_datetime — mounted_at at or before it, and either still open or dismounted after it. Derivation reads whatever mount history is already loaded, so vehicle_configurations must be imported before defects.

Explicit values win. slot_position is matched against the slots defined on the resolved product group or any of its ancestors on the vehicle’s type; the nearest node wins. The search never descends — a code above the slot’s node does not resolve. Surrounding whitespace is trimmed before matching. A position that matches nothing rejects the file; the mount history never stands in for a wrong position, and never overrides a resolved one.
A component derives its vehicle and slot. A row with a component_serial_number takes its missing vehicle_number and slot from the covering mount, and through the derived vehicle resolves its product_group_code as well; without exactly one covering mount the row is rejected (see Rules). A mount on a different vehicle than the row resolved leaves the slot empty; the warning names both vehicles.
A slot derives its component. A row with a resolved vehicle and slot but no serial takes the component mounted there at defect_datetime.

On a row that names its vehicle, overlapping mounts at defect_datetime derive nothing and warn, and a missing covering mount derives nothing and is silent. A component-only row in either situation is rejected, because its product group cannot resolve. Re-imports treat the three derived links — vehicle, component and slot — identically: a resolved value overwrites the stored one, an unresolved value keeps it. A row whose mount history derived nothing can therefore still carry a value from an earlier import, and an empty column never clears a link — corrections require re-sending a row that resolves. The product group always resolves, so it is always replaced.

Example

external_system_id,defect_datetime,defect_title,defect_description,location,vehicle_number,component_serial_number,action_code,action_description,cause_code,cause_description,fault_indication_code,warranty_flag,last_updated,consequence_code,consequence_description,category,severity,delay_minutes,closed_date,product_group_code,slot_position
X61-DEF-001,2025-06-02T08:30:00Z,Wheelset flat spot detected,Flat spot on wheelset causing vibration at speed.,Bogie 1,X61001,,INSP,Inspected and measured,WEAR,Normal wear and tear,EC-WEAR-01,True,2026-03-22T10:00:00Z,CSQ-001,Service disruption 15 min,Mechanical,Major,15,2025-07-10T00:00:00Z,EC,1
X61-DEF-002,2025-06-05T14:15:00Z,Traction inverter fault,Inverter reported overcurrent protection trip during acceleration.,Car A,X61001,,REP,Replaced inverter module,ELEC,Electrical fault,FD-ELEC-01,True,2026-03-22T10:00:00Z,CSQ-002,Train stopped at station,Electrical,Critical,45,2025-07-15T00:00:00Z,FD,

The first row pins the fault to bogie position 1. The second leaves slot_position empty — the traction inverter is not a slotted position on this type, and location carries what is known about where it sits.

Why a file gets rejected

Row 5: missing or empty defect_title
Row 8: must have vehicle_number or component_serial_number
Row 9: missing or empty product_group_code
Row 12: vehicle_number "X61099" not found in project
Row 14: component_serial_number "0123-9" not found in project
Row N: product_group_code "X" could not be resolved
Row N: product_group_code "X" could not be resolved - component-only row without exactly one configuration covering defect_datetime, so no vehicle type to resolve it on
Row N: slot_position "P" not found on product_group_code "X" or its ancestors

N is the row number in the file, and the quoted values are echoed from that row. Warnings, which do not reject the file. There are three, one per situation, and each is emitted only when the field it names actually ends up empty (<ts> is the row’s defect_datetime):

Row N: component "S" has overlapping configuration history at <ts> - slot left empty
Row N: component "S" was mounted on vehicle "A" at <ts>, not "B" - slot left empty
Row N: slot has overlapping configuration history at <ts> - component left empty

Overview

File formats

Tables

Columns

Rules

Resolution rules

Example

Why a file gets rejected

​Columns

​Rules

​Resolution rules

​Example

​Why a file gets rejected

Columns

Rules

Resolution rules

Example

Why a file gets rejected