CSV imports for MENA SaaS: validate before committing

A CSV import should tell an operator what will change before it changes customer records. That sounds modest, but it rules out a common implementation: read each row, save it immediately, and discover halfway through that the file uses a different column order or refers to the wrong customer account.

For a SaaS product serving Arabic and English operations teams, the import boundary also has to preserve names, references and amounts without guessing their meaning. A successful upload or a readable preview is not enough. The useful result is an authorised, explainable change that remains safe to retry.

This guide proposes a staged import for customer and catalogue data. It covers the path from accepted file to committed records, rather than malware scanning or spreadsheet export. Use a separate, stricter workflow for payments, payroll or other actions whose consequences extend beyond updating a database.

Cover: original SultanByte artwork showing CSV records moving through a preview gate before a database commit.

Give the importer a contract, not a guessing contest

Publish a versioned template and describe its encoding, delimiter, header names and field meanings. Decide what an empty cell means. For an update, it might mean “leave unchanged,” “clear this field” or “invalid”; those are different operations.

RFC 4180 documents a common CSV format, including quoted fields containing commas or line breaks and doubled quotes inside quoted fields. It is informational, not a guarantee that every file called CSV follows one dialect. A newline splitter followed by a comma splitter is therefore the wrong parser.

The W3C tabular-metadata recommendation separates dialect information from schema information and includes column types, required values and key relationships. You do not need to implement its entire vocabulary to adopt that separation. The parser should determine where a cell begins; the business schema should determine whether the cell is acceptable.

For a first release, prefer one documented UTF-8 profile. If legacy encodings or semicolon-delimited files are necessary, make the operator choose a supported profile and confirm the preview. Do not silently retry several interpretations until one happens to parse.

The following is a proposed application contract, not a standard CSVW document or a runnable importer:

{
  "template": "customer-import-v1",
  "encoding": "utf-8",
  "delimiter": ",",
  "header": ["external_id", "name", "credit_limit", "currency"],
  "operation": "create_only",
  "empty_credit_limit": "reject",
  "duplicate_external_id": "reject",
  "commit_mode": "all_or_nothing"
}

Keep the destination tenant and deployment outside that customer-editable contract. Derive them from the authorised import session. A column supplied by the uploader must not choose which organisation receives the records.

Decode and parse without repairing the evidence

Reject malformed input with a useful error instead of replacing undecodable bytes and continuing. The WHATWG Encoding Standard distinguishes replacement decoding from fatal decoding; TextDecoder can throw on decoding errors when configured with fatal: true. This is a decoding control, not field validation.

If the profile accepts a leading UTF-8 byte-order mark, handle it at the decoding boundary. Do not remove invisible characters indiscriminately from every cell. Preserve the submitted file under restricted access for the agreed retention period, and keep any canonical field values separate from the source representation.

Use a maintained parser with explicit settings. Python's CSV documentation illustrates the distinction: its ordinary reader returns strings, while QUOTE_NONNUMERIC converts unquoted fields to floats. It also documents a configurable field-size limit and opening file objects with newline=''. Choose behaviour deliberately rather than inheriting an example's defaults.

Set budgets for bytes, records, columns and individual field length, plus worker time and memory. Reject duplicate headers before mapping rows into objects. Require the expected field count, including on late records. A preview of the first few rows cannot establish that the rest of the file is structurally valid.

Report a logical record number and column name. A quoted note can span physical lines, so “line 20” and “record 20” need not identify the same place. If the parser provides physical-line information, label it separately.

Keep regional formats explicit

Do not infer currency, country or number syntax from the interface language. In a proposed UAE customer template, the organisation might permit AED only; a separate Saudi customer template might permit SAR only. Those are tenant-specific product rules, not national CSV requirements. A multinational customer may need both and should receive an explicit currency column.

Treat external references as strings. Preserve leading zeros and reject an unexpected numeric representation rather than reconstructing a value the source spreadsheet may already have changed. For amounts, accept a declared decimal syntax and apply the selected currency and precision rules. An Arabic interface does not authorise guessing whether a separator is decimal or grouping punctuation.

If you support Arabic-Indic digits, define conversion by field. SultanByte's digit-validation guide covers that boundary; the import-specific requirement is to show a consequential conversion in the preview and keep its rule version in the import record.

Allow Arabic and English header aliases only through a reviewed mapping. Detect collisions after mapping: two differently labelled columns must not silently target the same property. Keep original names intact and render bilingual previews as text, with appropriate direction handling, rather than interpreting cells as HTML.

Stage the whole change before asking for approval

Create an import record that binds the source file version, parser profile, mapping, schema version and intended operation to the tenant. Store parsed rows in a staging area that ordinary customer queries do not treat as live records.

Validate both individual rows and the set. Check required fields, allowed values, references to existing objects and repeated external IDs within the file. A record can be valid alone yet conflict with another record in the same upload. Scope reference lookups to the destination tenant; finding an object somewhere in the database does not authorise linking to it.

The preview should describe the proposed mutations: records to create, update or reject, with reasons. Distinguish a sampled display from whole-file validation. Let the operator inspect representative rows, but only enable approval after the entire accepted file has been evaluated.

Bind approval to that exact staged version. Changing a mapping, replacing the file or selecting another operation must invalidate the old preview. Give previews an expiry policy rather than retaining an apparently executable proposal indefinitely.

OWASP's authorization guidance recommends permission checks on every request. Apply that principle to upload, preview, approval, status and error downloads. Also recheck authority when the worker commits: permission held at upload time should not become permanent permission to modify customer records later.

Original graphic: SultanByte. Proposed import decision framework informed by RFC 4180, W3C CSVW, OWASP and PostgreSQL documentation, October 2026. These are design recommendations, not measured performance results.

Choose atomic or partial delivery before writing

For a bounded customer-master import, all-or-nothing is a useful default. If a required record fails, commit none of the proposed customer changes. PostgreSQL's transaction tutorial explains how BEGIN, COMMIT and ROLLBACK group database changes into an atomic operation.

Do the expensive parsing before opening that transaction. At commit, revalidate assumptions that can have changed since preview, then apply the mutations and record completion together. Keep database constraints as the final guard. PostgreSQL's constraint documentation supports multicolumn unique constraints and foreign keys; a proposed tenant-scoped external key should also have the necessary non-null constraints.

A preview cannot reserve the future. Another operator may create the same reference before approval. Reject the conflict or require a fresh preview. For updates, use an explicit concurrency policy, such as expected record versions, rather than overwriting changes made since validation.

Large independent catalogue updates may justify partial delivery. If so, name the atomic unit, retain a durable outcome for each unit and show the user exactly what succeeded. Stop calling the whole import “rolled back” once earlier units have committed. Cancellation should report committed work as well as work not attempted.

Neither mode makes external effects transactional. Do not send invitations, charge accounts or call a supplier API while pretending a database rollback will undo them. Record follow-up work durably with the committed change, then deliver it through a separately controlled worker.

Make retries return a receipt

Use a tenant-scoped import identifier and persist the approval version. For the proposed atomic mode, the commit transaction locks or conditionally claims the import record, refuses an obsolete state, writes the customer changes and saves the result receipt. A concurrent retry must observe the completed result or wait for the current attempt, not apply the file again. In partial mode, persist each unit's checkpoint with its changes and resume only units not already committed.

A file digest can help identify repeated bytes, but it is not the complete operation identity. The same file with a different mapping or operation has a different meaning. Conversely, a network retry of the same approved import should return its existing outcome.

If a connection fails around commit, show an unresolved status until the service reads the durable import record. Do not tell the operator to upload again merely because the browser did not receive a success response. Recovery should establish what happened before requesting another mutation.

Treat the error report as another data product

Return actionable errors without copying entire customer rows into logs. Keep the report tenant-scoped, access-controlled and subject to retention. Where possible, provide record identifiers, column names and error codes with narrowly selected values.

A downloadable CSV error report can introduce a second hazard. OWASP's CSV Injection guidance warns that spreadsheet applications can interpret untrusted cells as formulas. An import validator that merely reads a formula-like string has not necessarily executed it, but exporting that same string for an operator to open creates another boundary. Apply a tested spreadsheet-safe report policy; quoting alone is not a complete defence.

Before release, test a quoted multiline field, duplicate mapped headers, malformed UTF-8, a late invalid record and two simultaneous approvals. Add a cross-tenant lookup, revoked permission, a stale preview and a lost commit response. For partial mode, interrupt the worker after a committed unit and require the receipt to account for it.

Ship when the operator can answer what changed, what did not, and whether retrying will repeat anything. That is a more useful acceptance condition than a green progress bar.