CSV Import Preflight — Validate, Map & Audit

Validate a CSV against an explicit import contract before it reaches your CRM, ERP, accounting tool, marketplace, or internal database. The Actor returns a prepared CSV only when every row passes, plus a mapping, raw-value-free issue report, machine-readable audit report, and integrity manifests.

No AI guesswork. No silent data invention. No in-place modification of the source file.

What this Actor is for

• verify headers and column order before an import;
• map source columns to target columns;
• normalize explicitly declared integers, decimals, dates, emails, and text;
• reject undeclared, missing, malformed, or ambiguous values;
• protect spreadsheet formula-like text;
• prove which source and schema were processed with SHA-256 hashes;
• automate repeatable CSV quality gates through Apify Console or API.

This Actor is a deterministic import preflight, not a generic “repair anything” cleaner. It never guesses an encoding, delimiter, type, date convention, or decimal convention.

Quick start

1. Upload one source CSV in Source CSV. External URLs are intentionally not accepted; upload the file to Apify storage through the file picker.
2. Choose one contract mode:
   • Header-only CSV template for text-only validation and target ordering;
   • Typed JSON schema for explicit mapping and typed validation.
3. Run the Actor.
4. Open Output for the summary and Audit files for the downloadable deliverables.

Use the example files as matched pairs:

• source-header-only-valid.csv with target-header-only.csv;
• source-valid.csv with typed_schema.json.

Do not combine the source from one pair with the contract from the other.

Contract modes

Header-only CSV template

Upload a second CSV containing exactly one header row and no data. All target columns remain text because the Actor does not infer types. Choose the source and output encodings, delimiters, header-order policy, and formula policy in the input form. The bundled source-header-only-valid.csv and target-header-only.csv are a compatible example pair.

Typed JSON schema

Supply an explicit frantz.csv-import.schema.v2 object. The bundled source-valid.csv and typed_schema.json are a compatible example pair. The schema explicitly maps source_id, amount, date, and contact_email to their target columns; it is not intended for the header-only example.

Supported column types:

• text
• integer
• decimal
• date (iso, dmy_slash, or dmy_dash)
• email

Supported explicit rules include required/optional values, trimming, maximum length, allowed values, negative-number policy, decimal separator, source-to- target mapping, constants, exact value maps, ignored source columns, strict or flexible header order, and formula escape/reject policy.

Outputs

The default dataset contains one summary item without source cell values:

{
  "status": "accepted",
  "rows": 2,
  "inputColumns": 4,
  "outputColumns": 4,
  "issueCount": 0,
  "protectedFormulaCells": 0,
  "normalizedCells": 5,
  "sourceSha256": "7f23a6e0fbbc1e8cd293d60a018a62441746e6daec2afa509c8d851d1aab5a95",
  "schemaSha256": "cc4fb4805c37c4e4725df2b5a64be5c2a0cb43e7a1042053cc7d37e8ec31c492",
  "billingEvent": "csv-preflight-small",
  "billingOperationId": "frantz-csv-preflight-v1-078c1eb66e14513882c53569f5e7f7d4",
  "manifestSha256": "4c6b6629dceb513a374ff4694a852ded3c940f00f17da8ec8eef4b1c961f5a1b",
  "preparedCsvEmitted": true,
  "manifestKey": "deliverable-MANIFEST.json"
}

The default key-value store contains:

Key	Purpose
deliverable-prepared.csv	Prepared CSV; emitted only when status is accepted
deliverable-mapping.csv	Declared source-to-target mapping and presence flags
deliverable-issues.csv	Issue coordinates, codes, and rejected-value character lengths; no raw values or per-value hashes
deliverable-report.json	Full validation and reconciliation report
deliverable-engine-manifest.json	Manifest produced by the deterministic validation engine
deliverable-MANIFEST.json	Actor-level manifest sealing every business artifact
deliverable-summary.json	Canonical copy of the dataset summary, anchoring the Actor manifest hash

rejected is a valid business outcome: the audit files explain why the CSV is not safe to import, and no prepared CSV is emitted.

Transparent pricing

This Actor uses pay per event with platform usage included:

Event	Price
CSV preflight up to 1,000 data rows	$0.75
CSV preflight from 1,001 to 2,000 data rows	$1.50
Apify Actor start (automatic synthetic event)	$0.00005

The selected size event is charged once only after verified deliverables are published. Invalid Actor configuration, unreadable uploads, hard-limit errors, or internal failures do not trigger a CSV preflight event. A business rejection after a completed audit is charged because the issue report is the delivered result.

The runtime fails closed if Apify is not configured for PPE, if either custom event is not one-time, if any published event price differs from the table above, or if apify-default-dataset-item exists at all (flat or tier-priced).

Version 1 limits

Limit	Value
Source files	1
Source size	10 MiB
Data rows	2,000
Source columns	40
Target columns	30
Encodings	UTF-8 with/without BOM, Windows-1252
Delimiters	comma, semicolon, tab, pipe

Quoted fields and embedded delimiters are supported by the standard CSV parser. XLSX, generic download URLs, fuzzy matching, deduplication, and type inference are deliberately outside version 1.

Privacy and security

• no third-party API, proxy, browser, LLM, or remote enrichment call;
• uploaded URLs are restricted to signed or accessible Apify key-value-store record URLs, preventing generic URL fetching and SSRF;
• bounded streaming stops oversized uploads, and a logical-row guard rejects excess CSV records before the validation engine can materialize them;
• the container runs as a non-root user;
• source cell values are never written to logs or the summary dataset;
• issue records contain only the rejected value's character length; the engine's per-value hash field is blanked before export;
• the source file is not copied into output storage;
• dependency and engine versions are pinned; Linux build wheels are restricted to exact SHA-256 hashes;
• the source upload and generated outputs follow the retention and access rules of the user's Apify storages and plan.

The accepted prepared CSV necessarily contains the validated output values. Do not share a run or its storage links with unauthorized people.

Status semantics

• accepted: every row passed; deliverable-prepared.csv is available.
• rejected: the audit completed but one or more business rules failed; inspect deliverable-issues.csv and deliverable-report.json.
• failed run: the contract, upload, billing configuration, resource limit, or platform operation could not be proven safe; no success is reported.

Reliability notes

Every delivery is generated locally inside the Actor, verified against the engine manifest, namespaced in the default key-value store, and sealed again by an Actor-level manifest. Its SHA-256 is anchored in the canonical summary stored both in the key-value store and the run dataset. The summary is written before the custom charge. Charging uses a deterministic idempotency key through the run charge endpoint, while recovery cross-checks custom-event counts, the single dataset item, the summary, the manifest, and every artifact hash. Ambiguous platform state fails closed and retains the verified evidence for safe recovery.

Support

Use the Actor's Issues tab on Apify for reproducible defects and usage questions. Include the run ID and the observed status, but never post a source CSV, signed storage URL, API token, or customer data in a public issue. Support responses target one business day.

Version

Actor version 0.1; deterministic engine version 2.0.0.