CSV import

Let customers import a CSV file: column mapping, a dry run, an error report row by row, and no half-finished imports.

This is an app part spec on Spekkr, published by vex. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
vex/csv-import
Version
0.1.2
Published by
vex
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/vex/csv-import/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by vex.

What does the result look like?

CSV import: folio uploadCSV import: folio mapCSV import: folio reviewCSV import: folio result

What can I customize?

Database

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance criteria.

    CSV import

    What this builds

    A way for an app's customers to bring their own data in from a spreadsheet. The person uploads a CSV file, says which column is which, sees what would happen before anything is saved, and gets a report of every row that has a problem.

    Read spekkr.inputs.json first. The pages call the thing being imported a record_noun. A file has at most max_rows rows. update_existing changes R5, and undo decides whether R7 exists.

    The spec imports into one example table, contacts, described as data in design.md. To import something else, change that description and nothing else.

    This spec needs the app to know who is signed in. It does not build sign-in.

    Out of scope

    • Excel files. The upload page says how to save a sheet as CSV.
    • Imports that run on a schedule or from an address.
    • Records that span several rows.

    Requirements

    Each requirement has an id. Tests name the id they cover.

    R1. Read the file
    • A file is at most 20 MB (20,000,000 bytes) and max_rows rows, not counting the header. A larger one is refused before it is read to the end.
    • The file is UTF-8, with or without a byte order mark, or UTF-16 with one. Any other encoding is refused with a message that says how to save as UTF-8.
    • The separator is whichever of comma, semicolon and tab splits the first 10 lines into the same number of columns, more than one. If none does, the person is asked.
    • Fields follow the usual rules: a field in double quotes can hold separators, line breaks and doubled quotes. The cases in design.md come out exactly as given.
    • The first row is the header. Empty rows are skipped. A row with more or fewer fields than the header is an error for that row, not for the file.

    Accept when: every case in the table in design.md parses as given, and a file of max_rows plus one rows is refused.

    R2. Map the columns
    • The person sees the header and the first 5 rows, and for each field of the record a list to choose a column from.
    • Each field starts on the column whose header matches its name or one of its other names, ignoring case, spaces, hyphens and underscores.
    • A required field must be mapped before the person can go on. A column can be left out.
    • The choice is remembered for that person, and offered again for a file with the same header.

    Accept when: a header of E-mail Address is matched to email unasked, and going on without a required field is refused.

    R3. Dry run
    • Every row is checked against the rules of the fields it maps to: required, the form of an email address, a number, a date, a longest length.
    • Dates are read as YYYY-MM-DD, or in the one other form the person picks from a list on the mapping page. A date that fits neither is an error.
    • The result says how many rows would be created, updated, skipped and refused, and shows the first 20 problems with row number, column and reason.
    • The person can download every refused row as a CSV file: the original columns plus one, Error.
    • Nothing is saved to the record table during a dry run.

    Accept when: the counts add up to the number of rows, the downloaded report holds exactly the refused rows, and the record table is unchanged.

    R4. Import
    • After the dry run the person imports the valid rows, or cancels.
    • The import runs in the background, 500 rows to a database transaction, and the page shows how far it has got.
    • An import that is interrupted carries on from the last finished batch when it is started again. No row is saved twice.
    • A person can cancel a running import. Batches already saved stay saved, and the result says so.
    • One person runs one import at a time.

    Accept when: an import killed after any batch and started again ends with the same records as one that ran straight through.

    R5. Rows that match
    • A record is recognised by its key field. For contacts that is email, compared without regard to case.
    • Two rows in the file with the same key: the first counts, and each later one is refused with "same email as row N".
    • A row whose key matches an existing record: if update_existing is on, the record's mapped fields are updated and fields that are not mapped are left alone. An empty cell does not erase a value. If it is off, the row is skipped and counted.

    Accept when: a file with a repeated key creates one record and reports the other row, and an update with an empty cell keeps the old value.

    R6. Safe reports
    • In any file the app writes, a cell that starts with =, +, -, @, a tab or a carriage return gets a single quote in front, so a spreadsheet does not run it as a formula.

    Accept when: a refused row whose name is =HYPERLINK("http://x","y") appears in the report with a quote in front.

    R7. Undo

    Only if undo is on.

    • For 24 hours an import can be undone. Records it created are deleted. Records it updated get their old values back.
    • A record that someone changed after the import is left as it is and listed in the result of the undo.

    Accept when: undoing leaves the table as it was before the import, apart from records changed since, which are listed.

    R8. History
    • A page lists a person's imports: file name, when, counts, state, and links to the error report and, if undo is on, to undo.
    • Uploaded files and reports are deleted after 30 days. The history line stays.

    Accept when: one person never sees another person's imports or files.

    R9. Pages
    • Four steps: upload, map, review, result. The person can go back from review to mapping without uploading again.
    • Progress is announced to screen readers, not only drawn.

    Accept when: each page works with a keyboard alone and at a 360 pixel wide screen.

    Definition of done

    • Every acceptance check above has an automated test, and all tests pass.
    • A README explains how to describe another record in place of contacts, and how to run the tests.
    # CSV import
    
    ## What this builds
    
    A way for an app's customers to bring their own data in from a spreadsheet. The
    person uploads a CSV file, says which column is which, sees what would happen
    before anything is saved, and gets a report of every row that has a problem.
    
    Read `spekkr.inputs.json` first. The pages call the thing being imported a
    `record_noun`. A file has at most `max_rows` rows. `update_existing` changes R5,
    and `undo` decides whether R7 exists.
    
    The spec imports into one example table, `contacts`, described as data in
    `design.md`. To import something else, change that description and nothing else.
    
    This spec needs the app to know who is signed in. It does not build sign-in.
    
    ## Out of scope
    
    - Excel files. The upload page says how to save a sheet as CSV.
    - Imports that run on a schedule or from an address.
    - Records that span several rows.
    
    ## Requirements
    
    Each requirement has an id. Tests name the id they cover.
    
    ### R1. Read the file
    
    - A file is at most 20 MB (20,000,000 bytes) and `max_rows` rows, not counting the header. A larger
      one is refused before it is read to the end.
    - The file is UTF-8, with or without a byte order mark, or UTF-16 with one. Any
      other encoding is refused with a message that says how to save as UTF-8.
    - The separator is whichever of comma, semicolon and tab splits the first 10 lines
      into the same number of columns, more than one. If none does, the person is
      asked.
    - Fields follow the usual rules: a field in double quotes can hold separators, line
      breaks and doubled quotes. The cases in `design.md` come out exactly as given.
    - The first row is the header. Empty rows are skipped. A row with more or fewer
      fields than the header is an error for that row, not for the file.
    
    Accept when: every case in the table in `design.md` parses as given, and a file of
    `max_rows` plus one rows is refused.
    
    ### R2. Map the columns
    
    - The person sees the header and the first 5 rows, and for each field of the
      record a list to choose a column from.
    - Each field starts on the column whose header matches its name or one of its
      other names, ignoring case, spaces, hyphens and underscores.
    - A required field must be mapped before the person can go on. A column can be
      left out.
    - The choice is remembered for that person, and offered again for a file with the
      same header.
    
    Accept when: a header of `E-mail Address` is matched to `email` unasked, and going
    on without a required field is refused.
    
    ### R3. Dry run
    
    - Every row is checked against the rules of the fields it maps to: required, the
      form of an email address, a number, a date, a longest length.
    - Dates are read as `YYYY-MM-DD`, or in the one other form the person picks from a
      list on the mapping page. A date that fits neither is an error.
    - The result says how many rows would be created, updated, skipped and refused,
      and shows the first 20 problems with row number, column and reason.
    - The person can download every refused row as a CSV file: the original columns
      plus one, `Error`.
    - Nothing is saved to the record table during a dry run.
    
    Accept when: the counts add up to the number of rows, the downloaded report holds
    exactly the refused rows, and the record table is unchanged.
    
    ### R4. Import
    
    - After the dry run the person imports the valid rows, or cancels.
    - The import runs in the background, 500 rows to a database transaction, and the
      page shows how far it has got.
    - An import that is interrupted carries on from the last finished batch when it is
      started again. No row is saved twice.
    - A person can cancel a running import. Batches already saved stay saved, and the
      result says so.
    - One person runs one import at a time.
    
    Accept when: an import killed after any batch and started again ends with the same
    records as one that ran straight through.
    
    ### R5. Rows that match
    
    - A record is recognised by its key field. For contacts that is `email`, compared
      without regard to case.
    - Two rows in the file with the same key: the first counts, and each later one is
      refused with "same email as row N".
    - A row whose key matches an existing record: if `update_existing` is on, the
      record's mapped fields are updated and fields that are not mapped are left
      alone. An empty cell does not erase a value. If it is off, the row is skipped
      and counted.
    
    Accept when: a file with a repeated key creates one record and reports the other
    row, and an update with an empty cell keeps the old value.
    
    ### R6. Safe reports
    
    - In any file the app writes, a cell that starts with `=`, `+`, `-`, `@`, a tab or
      a carriage return gets a single quote in front, so a spreadsheet does not run it
      as a formula.
    
    Accept when: a refused row whose name is `=HYPERLINK("http://x","y")` appears in
    the report with a quote in front.
    
    ### R7. Undo
    
    Only if `undo` is on.
    
    - For 24 hours an import can be undone. Records it created are deleted. Records it
      updated get their old values back.
    - A record that someone changed after the import is left as it is and listed in
      the result of the undo.
    
    Accept when: undoing leaves the table as it was before the import, apart from
    records changed since, which are listed.
    
    ### R8. History
    
    - A page lists a person's imports: file name, when, counts, state, and links to the
      error report and, if `undo` is on, to undo.
    - Uploaded files and reports are deleted after 30 days. The history line stays.
    
    Accept when: one person never sees another person's imports or files.
    
    ### R9. Pages
    
    - Four steps: upload, map, review, result. The person can go back from review to
      mapping without uploading again.
    - Progress is announced to screen readers, not only drawn.
    
    Accept when: each page works with a keyboard alone and at a 360 pixel wide screen.
    
    ## Definition of done
    
    - Every acceptance check above has an automated test, and all tests pass.
    - A README explains how to describe another record in place of contacts, and how
      to run the tests.
    

    Open spec.md as plain text

  • design.md Data model, rules and flows.

    Design

    This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.

    The record, as data

    Everything the importer knows about the record comes from one description. Keep it in one place in code.

    FieldLabelTypeRulesOther names it answers to
    emailEmailemailrequired, key, at most 254 characterse-mail, email address, mail
    nameNametextrequired, at most 200 charactersfull name, contact name
    companyCompanytextat most 200 charactersorganisation, organization, account
    phonePhonetextat most 40 characterstelephone, mobile, tel
    joined_onJoined ondatejoined, signup date, created

    Data model

    Use the database in the database input.

    TableColumns
    contactsid, owner_id, email (unique per owner, lowercase), name, company, phone, joined_on, created_at, updated_at
    importsid, user_id, file_name, file_key, separator, mapping (JSON), date_format, state, rows_total, rows_done, created, updated, skipped, refused, report_key, created_at, finished_at
    import_changesimport_id, record_id, action, before (JSON), after (JSON) (only if undo is on)
    import_mappingsuser_id, header_hash, mapping; primary key on the first two

    state is one of uploaded, checked, running, done, cancelled and failed.

    Parsing cases

    Each line of the first column is one line of the file. ⏎ marks a line break inside the file.

    FileFields
    a,b,ca, b, c
    "a,b",ca,b, c
    "say ""hi""",xsay "hi", x
    "one⏎two",xone field holding one, a line break and two; then x
    a,,ca, an empty field, c
    a;b;c in a file whose lines all have two semicolonsa, b, c
    a , ba, b: spaces around a value are trimmed
    " a "a: also when the value was quoted
    A byte order mark, then email,nameemail, name: the mark is not part of the first header
    a,b then an empty last lineone row; the empty line is not a row

    Lines end with a line feed, or a carriage return and a line feed. Accept both in one file. Use a maintained CSV library if the language has one, and run these cases against it.

    Rules

    • Read the file as a stream. Never hold all of it in memory.
    • The dry run and the import run the same code for each row, with one switch that says whether to save. That is what keeps the counts of the two equal.
    • Row numbers in messages count the header as row 1, as a spreadsheet shows them.
    • To carry on after an interruption: rows_done is updated in the same transaction as its batch. Starting again skips that many rows.
    • A row's fate is decided against the database inside its batch's transaction, so a record created by someone else during the import is updated or skipped, not duplicated. The unique index on email is the last guard.
    • For undo, write one import_changes row for each record created or updated, in the same transaction, with the values before and after. To undo an update, restore a field only if it still holds the after value.

    Configuration

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.

    Who is signed in

    The spec reaches the app's sign-in through one function, current_user(request). It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session.

    When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production.

    Named here

    • When two separators split the first lines equally well, comma wins, then semicolon, then tab.
    • The other date forms a person may pick: MM/DD/YYYY, DD/MM/YYYY, DD.MM.YYYY.
    • Empty rows are not counted in any total.

    What this spec leaves to you

    Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.

    # Design
    
    This file fixes the parts that are easy to get wrong. Choose the language and
    framework that fit the person's project; nothing here depends on them.
    
    ## The record, as data
    
    Everything the importer knows about the record comes from one description. Keep it
    in one place in code.
    
    | Field | Label | Type | Rules | Other names it answers to |
    | --- | --- | --- | --- | --- |
    | `email` | Email | email | required, key, at most 254 characters | `e-mail`, `email address`, `mail` |
    | `name` | Name | text | required, at most 200 characters | `full name`, `contact name` |
    | `company` | Company | text | at most 200 characters | `organisation`, `organization`, `account` |
    | `phone` | Phone | text | at most 40 characters | `telephone`, `mobile`, `tel` |
    | `joined_on` | Joined on | date | | `joined`, `signup date`, `created` |
    
    ## Data model
    
    Use the database in the `database` input.
    
    | Table | Columns |
    | --- | --- |
    | `contacts` | `id`, `owner_id`, `email` (unique per owner, lowercase), `name`, `company`, `phone`, `joined_on`, `created_at`, `updated_at` |
    | `imports` | `id`, `user_id`, `file_name`, `file_key`, `separator`, `mapping` (JSON), `date_format`, `state`, `rows_total`, `rows_done`, `created`, `updated`, `skipped`, `refused`, `report_key`, `created_at`, `finished_at` |
    | `import_changes` | `import_id`, `record_id`, `action`, `before` (JSON), `after` (JSON) (only if `undo` is on) |
    | `import_mappings` | `user_id`, `header_hash`, `mapping`; primary key on the first two |
    
    `state` is one of `uploaded`, `checked`, `running`, `done`, `cancelled` and
    `failed`.
    
    ## Parsing cases
    
    Each line of the first column is one line of the file. `⏎` marks a line break
    inside the file.
    
    | File | Fields |
    | --- | --- |
    | `a,b,c` | `a`, `b`, `c` |
    | `"a,b",c` | `a,b`, `c` |
    | `"say ""hi""",x` | `say "hi"`, `x` |
    | `"one⏎two",x` | one field holding `one`, a line break and `two`; then `x` |
    | `a,,c` | `a`, an empty field, `c` |
    | `a;b;c` in a file whose lines all have two semicolons | `a`, `b`, `c` |
    | ` a , b ` | `a`, `b`: spaces around a value are trimmed |
    | `" a "` | `a`: also when the value was quoted |
    | A byte order mark, then `email,name` | `email`, `name`: the mark is not part of the first header |
    | `a,b` then an empty last line | one row; the empty line is not a row |
    
    Lines end with a line feed, or a carriage return and a line feed. Accept both in
    one file. Use a maintained CSV library if the language has one, and run these
    cases against it.
    
    ## Rules
    
    - Read the file as a stream. Never hold all of it in memory.
    - The dry run and the import run the same code for each row, with one switch that
      says whether to save. That is what keeps the counts of the two equal.
    - Row numbers in messages count the header as row 1, as a spreadsheet shows them.
    - To carry on after an interruption: `rows_done` is updated in the same
      transaction as its batch. Starting again skips that many rows.
    - A row's fate is decided against the database inside its batch's transaction, so
      a record created by someone else during the import is updated or skipped, not
      duplicated. The unique index on `email` is the last guard.
    - For undo, write one `import_changes` row for each record created or updated, in
      the same transaction, with the values before and after. To undo an update,
      restore a field only if it still holds the `after` value.
    
    ## Configuration
    
    | Secret | Purpose |
    | --- | --- |
    | `DATABASE_URL` | Connection string for the chosen database. |
    
    ## Who is signed in
    
    The spec reaches the app's sign-in through one function, `current_user(request)`.
    It answers with the person's id, and says whether they are an administrator where
    this spec asks. In the person's app it reads their session.
    
    When there is no app yet, build this stand-in and nothing more: a page that lists
    two seeded people, one of them an administrator, with a button for each that sets
    a signed cookie naming them. The stand-in refuses to start in production.
    
    ## Named here
    
    - When two separators split the first lines equally well, comma wins, then
      semicolon, then tab.
    - The other date forms a person may pick: `MM/DD/YYYY`, `DD/MM/YYYY`,
      `DD.MM.YYYY`.
    - Empty rows are not counted in any total.
    
    ## What this spec leaves to you
    
    Where this spec names something, use that name, so that two builds of it agree.
    Where it does not, the choice is yours. List what you chose in the README.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Add the tables in design.md, somewhere to keep uploaded files, and the smallest app if there is none: a signed-in user. Check: migrations run from empty.
    2. Read the file (R1). Encoding, separator and fields, as a stream. Use the max_rows input. Check: a test runs every parsing case in design.md, and the R1 limits hold.
    3. The record as data. The description in design.md, and the checks for each type of field. Check: tests cover each rule with a value that passes and one that fails.
    4. Map the columns (R2). Check: the R2 acceptance tests pass.
    5. Dry run (R3) and safe reports (R6). Check: the R3 and R6 acceptance tests pass.
    6. Rows that match (R5). As the update_existing input says. Check: the R5 acceptance tests pass.
    7. Import (R4). In the background, in batches, able to carry on. Check: the R4 test that kills the import after each batch in turn passes.
    8. Undo (R7). Only if undo is on. Check: the R7 acceptance tests pass.
    9. History (R8) and pages (R9). Use the record_noun input on the pages. Check: the R8 test passes, and every page can be used with a keyboard alone and at 360 pixels wide.
    10. Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Add the tables in `design.md`, somewhere to keep uploaded files, and
       the smallest app if there is none: a signed-in user.
       Check: migrations run from empty.
    
    2. **Read the file (R1).** Encoding, separator and fields, as a stream. Use the
       `max_rows` input.
       Check: a test runs every parsing case in `design.md`, and the R1 limits hold.
    
    3. **The record as data.** The description in `design.md`, and the checks for each
       type of field.
       Check: tests cover each rule with a value that passes and one that fails.
    
    4. **Map the columns (R2).**
       Check: the R2 acceptance tests pass.
    
    5. **Dry run (R3) and safe reports (R6).**
       Check: the R3 and R6 acceptance tests pass.
    
    6. **Rows that match (R5).** As the `update_existing` input says.
       Check: the R5 acceptance tests pass.
    
    7. **Import (R4).** In the background, in batches, able to carry on.
       Check: the R4 test that kills the import after each batch in turn passes.
    
    8. **Undo (R7).** Only if `undo` is on.
       Check: the R7 acceptance tests pass.
    
    9. **History (R8) and pages (R9).** Use the `record_noun` input on the pages.
       Check: the R8 test passes, and every page can be used with a keyboard alone and
       at 360 pixels wide.
    
    10. **Finish.** Write the README and run the whole test suite.
        Check: every item under "Definition of done" in `spec.md` is true.
    

    Open tasks.md as plain text

Is it for me?

Platforms
web, backend

What does it need?

Agent permissions
shell, network
Secrets it reads
DATABASE_URL

What changed?

  • 0.1.215 Nov 2026Names what it builds.
  • 0.1.114 Nov 2026Says "person" where it said "buyer".
  • 0.1.014 Nov 2026Moved from dwrtz/csv-import.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.