Defects

Defects are faults and conditions found against your assets: a rail surface defect, a worn switch component, a measurement that has breached a threshold. Each defect captures what was found, where it sits on the network, and which assets it affects, so the platform can track condition and the work needed to fix it.

At a glance

• Represents: a fault or condition identified against one or more assets
• Body: a JSON array of defect objects
• Keyed by: id — your external identifier, and the upsert key
• Belongs to: the assets it relates to (assets[].assetId)

Tip

The full field list, required vs. optional flags, and a runnable example payload are in the API Reference under Defect Import (POST /v2/defects).

What it represents

A defect records something that needs attention:

• Descriptive text — a name, a longer description, and free-form comments.
• Classifiers for triage — a category, a type, a severity, and a priority.
• Lifecycle dates — when the defect was identified, when rectification is required, and when it was completed.

Where a defect involves a threshold that has been exceeded, it can record the threshold class, its value and unit, and the measured value that breached it. This turns a condition reading into an actionable defect.

To trace a defect back to its source, it can hold references into your source system: a source name, a third-party identifier, and links to a related notification or order.

Attaching to assets

Every defect must relate to at least one asset. Each entry in its assets list names an asset by the assetId you imported, and may pin the defect’s position with the shared geolocation concept. This is useful when a defect sits at a specific point along an asset rather than the asset as a whole.

Because defects reference assets by identifier, import your assets first. A defect that points at an assetId the platform doesn’t yet recognise passes request validation but fails at job time; see Common Errors.

Using it

• A defect needs an id, an identifiedDate, and a non-empty assets list with an assetId on each entry; everything else is optional.
• Re-importing is safe: a defect with an existing id is updated in place. Keep identifiers stable so updates land on the right record instead of creating a duplicate.
• Capture source-system fields that don’t map onto a standard defect concept as metadata name/value pairs.