Validation Model
How IngestX evaluates row validity
IngestX evaluates cells against your configured schema rules to help ensure structured data.
Row Classification
Every row processed by IngestX is classified into one of two output arrays:
validRows: Data mapped exactly to thekeystrings you defined. The row passed its schema validations, and defaults/transformations were applied.invalidRows: The original row object mapping headers directly to the cell values.
This provides a clear separation of valid and invalid structural data.
Validation Errors
When a cell violates its schema logic, the entire row is immediately pushed into the invalidRows array.
However, you often need to communicate precisely what failed back to the user. IngestX records this highly granular validation failure state and returns it within the errorsData object.
type ErrorsData = {
rowWiseErrors: Array<{
rowIndex: number; // The specific row in the chunk
columnKey: string; // The defined ColumnConfig key
receivedValue: unknown; // The raw spreadsheet value
errorMessage: string; // E.g. "String must be at least 3 characters"
}>;
};This array permits you to render inline data grids pointing a red outline explicitly to the broken cell in the UI, improving user correction speeds.
Execution Order
The execution pipeline for a cell behaves sequentially:
- Extraction: The raw text value is pulled from the spreadsheet cell.
- Trimming: If
.trim()was declared in the schema, it executes. - Optional Check: If the string is empty and
.optional()is declared, it passes validation. - Default Check: If the string is empty and
.default(value)is declared, it is populated. - Type Parsing: The value is cast to the schema type (e.g. attempting to convert the string to a Number).
- Validation Rules: Declared rules (
.min(),.regex()) are executed sequentially. The first rule to fail halts validation for this cell and throws the associated error message. - Transformation: If validation passes and a
.transform(fn)exists, the function is executed to produce the final value.