Skip to content

JSE-21: unmapped schema fields are null in every row - #100

Merged
securedeveloper merged 1 commit into
mainfrom
jse-21-unmapped-null
Nov 16, 2026
Merged

securedeveloper merged 1 commit into
mainfrom
jse-21-unmapped-null

Conversation

@securedeveloper

Copy link
Copy Markdown
Owner

JSE-21: unmapped schema fields come back as null, so imported rows always have the schema's shape. Afzal approved it (proposed in react-data-import #10). It's a behaviour change in the prerelease, with a minor changeset.

Change

applyMapping, and so importDataset with a schema:

  • Rows: every row has a key for every schema field, in schema order. A field without a column is null. Before, the key was missing, so a Zod .nullable() field failed with "expected date, received undefined".
  • Columns: columns has one entry per schema field. An unmapped field's entry has title: '', letter: '', type: 'empty' and its field, so columns and rows match.
  • Required fields: a required field without a column still gives one MAPPING_MISSING issue (row 0). It's null in the rows, and gets no per-row REQUIRED issue (that was already the case).
  • Unchanged: meta.mapping (unmapped fields are null there), meta.unmappedColumns, unmapped: 'keep' (a kept column whose key equals a field name is still suffixed _2).

Flag: the brief covered the rows. I made columns list every schema field as well, so that a consumer iterating columns, react-data-export's exportDataset(result) for example, sees the same shape as the rows. react-data-import's useColumnMapping already skips fields whose mapping is null, so it's unaffected.

Docs and tests

  • docs/api.md §5.6: the ImportDatasetResult.columns comment and the applyMapping bullets.
  • test/import/mapping.test.ts: the two expectations that encoded the old shape now expect null-valued keys and full schema columns.
  • test/import/pipeline.test.ts: a new "unmapped schema fields (JSE-21)" block:
    • optional fields are null, with empty columns and meta.mapping null
    • a required unmapped field gives one MAPPING_MISSING, nulls, and no REQUIRED
    • every row has the same keys, in schema order
  • Locally (Node 26.13.1): typecheck, 860 tests and docs:check pass.

Follow-up

react-data-import picks this up once it ships in the next javascript-excel alpha. That PR covers its docs and types (§4.2/§6: "one per schema field"), and switches the playground's demo schema back from .nullish() to .nullable().

applyMapping (and so importDataset) now gives every schema field a column and
a key in every row: a field without a column is null, with an entry in
columns (title and letter '', type 'empty', its field). Rows always have the
schema's shape, so validators such as Zod's .nullable() accept them; before,
the key was missing. A required field without a column still gives one
MAPPING_MISSING issue and no per-row REQUIRED issue.
@securedeveloper
securedeveloper merged commit a0a9741 into main Nov 16, 2026
9 checks passed
@securedeveloper
securedeveloper deleted the jse-21-unmapped-null branch November 16, 2026 15:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant