Excel Workbook to Typed JSON — Schema & Cell Evidence

Convert one inline Base64 XLSX workbook into deterministic typed rows, column schema, warnings, hashes, and cell provenance in one Dataset item. Processing uses no URL, external request, Browser, binary office suite, or temporary extracted workbook.

Input is exactly:

{"workbookBase64": "UEsDB..."}

Canonical standard RFC 4648 Base64 is required. Data URIs, whitespace, URL-safe Base64, URLs, paths, passwords, sheet selectors, locale, timezone, and unknown fields are rejected.

Fixed safety and output bounds

• compressed XLSX: 2 MiB
• ZIP entries: 1,000
• total uncompressed ZIP: 20 MiB
• per-entry and total compression ratio: 100:1
• sheets: 10
• rows: 1,000 per sheet
• columns: 100 per sheet
• output cells: 10,000 per workbook
• canonical UTF-8 output: 2 MiB

Before parsing, the Actor rejects absolute/traversing/NUL paths, Unicode-normalized duplicate paths, symlinks, encrypted entries, CRC failure, DTD/entity declarations, macros/VBA, embedded executable objects, missing XLSX parts, and size/ratio violations. Nothing is extracted to the filesystem. Old XLS, XLSB, ODS, CSV, macro-enabled, and password-protected workbooks are unsupported.

The first non-empty row is the header. Labels use Unicode NFKC, LF line endings, collapsed whitespace, and trim. Blank headers become column_N; duplicates receive __2, __3 in source order. Column schema includes observed normalized types, inferred type, nullability, and formula/error counts. Strings are not trimmed or interpreted. Native booleans/integers/dates/datetimes remain conservative types; finite decimal values become canonical decimal strings. Date-like strings, currency, percentages, locale, IDs, and PII are never inferred.

Formulas are loaded with data_only false and returned only as leading-equals literal strings. They are never evaluated and cached values/external links are not used; FORMULA_NOT_EVALUATED identifies formula cells. Excel errors and unsupported types become null with fixed cell warnings.

Valid workbooks with no data rows succeed with NO_DATA_ROWS, one default Dataset item, and one built-in apify-default-dataset-item event. Invalid/unsafe/malformed/over-limit/internal or Dataset failures produce zero items/events. Raw Base64, workbook binary, ZIP/XML, full-sheet text, and metadata are not saved or normally logged.

Workbook sheet names, headers, formula literals, and cell values can contain personal or confidential information. This Actor does not detect or redact them. Only synthetic non-PII fixtures are approved for this release candidate.

Dependency gate

Official PyPI JSON checked 2026-08-15:

• openpyxl 3.1.5: MIT classifier, Python >=3.8, non-yanked pure-Python py2.py3-none-any wheel
• et-xmlfile 2.0.0: MIT classifier, Python >=3.8, non-yanked pure-Python py3-none-any wheel

Both are exact-pinned. openpyxl runs read-only from BytesIO with data_only false and keep_links false. The Actor adds its own bounded ZIP/CRC/XML preflight because parser defaults alone are not the security boundary.

Local verification and limits

..\..\.venv\Scripts\python.exe -m unittest discover -s tests -v
..\..\.venv\Scripts\python.exe tools/local_actor_smoke.py

No real or sensitive workbook, external request, or Cloud run is used. Real-workbook accuracy, memory/cold-start, platform cost, paid demand, revenue, profit, margin, and break-even remain null.

Unapproved pricing hypothesis: $0.005 per successful summary Dataset item, at most $0.005/run, with no actor-start or custom event.