Upload Validation Rules | TRACT Help Center

Every file you upload to TRACT goes through two stages of validation. Knowing what is checked at each stage helps you fix issues before they cause an upload failure.

FILE CHECK (static validation): Runs immediately when you submit the file. Validates structure and field-level formatting — no database lookup required.

SYSTEM CHECK (second-stage validation): Runs after File Check passes. Cross-references your data against existing records in the system.

Make sure you download the latest template.

1. All File Types

These checks apply to every upload regardless of file type.

Rule	Stage	Details
File format	FILE CHECK	Upload CSV or Excel (.xlsx) files only. Other formats are not accepted.
Template version	FILE CHECK	Use the latest TRACT-provided template for your file type. Do not modify column headers or sheet names.
Required tabs	FILE CHECK	All required worksheet tabs must be present and named correctly.
Data rows	FILE CHECK	The file must contain at least one data row — empty files are rejected.

2. Master Data

Applies to: Farms, Facilities, Farmer Groups, Customer Destinations templates.

Field / Rule	Stage	Validation
Node ID — format	FILE CHECK	Mandatory field — cannot be left blank. Allowed characters: letters, numbers, and `. _ -` or apostrophe (`'`). These special characters cannot appear consecutively or at the start/end of the value.
Node ID — uniqueness	SYSTEM CHECK	Must not already exist in the system as a Node ID, Universal ID, or Node ID. Must also be unique within the file being uploaded.
Node Name	FILE CHECK	Must be between 3 and 256 characters. Cannot contain: `/ \ [ ] : ; \| = + * ? ! < >` Spaces and `. _ -` are allowed.
Country	FILE CHECK	Mandatory field. Must match a value from the Country_List tab in the template.
Latitude / Longitude	FILE CHECK	Latitude must be between -90 and 90. Longitude must be between -180 and 180.
Farm Radius (km)	FILE CHECK	Must be a numeric value. Text or empty values are not accepted.
Total Cultivated Area (ha)	FILE CHECK	Must be a numeric value. Text or empty values are not accepted.
Coordinate within Country	SYSTEM CHECK	The latitude/longitude values must fall within the boundary of the Country specified for that record.
Duplicate records	SYSTEM CHECK	No two rows can share the same Farm Name OR the same Node ID. If duplicates are detected, the entire file is rejected — not just the duplicate row.

3. Traceability

Traceability records transactions and shipments. Master Data must be uploaded first — StartNodeID and EndNodeID values are validated against existing Master Data records.

Field / Rule	Stage	Error message
StartNodeID / EndNodeID	SYSTEM CHECK	Must exist as a valid Node ID in uploaded Master Data. Accepted formats: 32-character hex Node ID, Universal ID, or External ID. StartNodeID is a mandatory field.
TransactionId — format	FILE CHECK	Allowed format: letters and numbers, with optional `. _ -` separators. No spaces or other special characters. TransactionId is mandatory when EndNodeID is not provided.
TransactionId — uniqueness	SYSTEM CHECK	Each TransactionId must be unique — both within the file and against all previously uploaded records.
UnloadDate	FILE CHECK	Mandatory field. Accepted formats: `DD/MM/YYYY`, `YYYY/MM/DD`, `MM/YYYY`, `MMM/YYYY`, `YYQQ`, `YYYY`
Other date fields	FILE CHECK	All date fields (e.g. DeliveryPeriodEndDate) must follow accepted formats: `DD/MM/YYYY`, `YYYY/MM/DD`, `MM/YYYY`, `MMM/YYYY`, `YYQQ`, `YYYY`
Product	FILE CHECK	Mandatory field. Must be a valid product from the allowed list.
SubProduct	FILE CHECK	Mandatory field. Must be a valid sub-product from the allowed list for the selected Product.
ProductCertification	FILE CHECK	Mandatory field. Must be a value from the allowed list for the selected Product.
SupplyChainType	FILE CHECK	Mandatory field. Must be a valid value from the allowed list.
Harvest Year	FILE CHECK	Accepted formats: `YYYY` or `YYYY/ZZZZ` (where ZZZZ − YYYY = 1, e.g. 2023/2024).
Chain linking (PreviousTransactionId)	SYSTEM CHECK	When transactions are linked, the End Node of the previous segment must match the Start Node of the current segment. Product Certification and Supply Chain Type must also match across linked segments. The Unload Date of the previous segment must not be later than the current segment.
Duplicate records	FILE CHECK	No two rows can share the same combination of core fields. If duplicates are found, the entire file is rejected.

4. GeoJSON

GeoJSON files contain geolocation data (polygon boundaries) for farms and other nodes. Master Data must be uploaded first — NodeIDs in GeoJSON are validated against existing records.

Rule	Stage	Validation
NodeID property	FILE CHECK	Every GeoJSON feature must include a NodeID property. The NodeID must match an existing record in Master Data.
Polygon point count	FILE CHECK	A polygon ring must have at least 4 coordinate points. (The first and last point must be the same to close the ring — so the minimum unique points is 3.)
Closed ring	FILE CHECK	The first coordinate and the last coordinate in each polygon ring must be identical. An open ring (first point ≠ last point) is invalid.
Self-intersections	FILE CHECK	The polygon boundary cannot cross itself. Use the TRACT Geolocation Formatter (QGIS plugin) to detect and correct self-intersections before upload.
No interior holes	FILE CHECK	Polygons and multipolygons cannot contain interior holes (interior rings). Remove any hole geometries before upload.
Valid JSON format	FILE CHECK	The file must be valid, well-formed GeoJSON. JSON syntax errors (e.g. missing brackets, trailing commas) will cause the upload to fail.
Auto-corrected by TRACT		Duplicate vertices are automatically removed during upload — you do not need to fix these manually. Coordinates are trimmed to 6 decimal places.

Need help fixing an error?
If your upload fails, check our step-by-step guides for common errors: