CLCTN · IMPORT FORMAT · AUGUST 2026

One required column. Everything else is a favour to yourself.

Every collector who has kept a list for more than a year has it in a spreadsheet, and no two of those spreadsheets look alike. So the format below is not a requirement — it is the shape we publish, for people starting fresh, while the importer reads whatever columns already exist. A format nobody can fail is worth more than a format that is elegant.

Give this page to anyone — it is the whole specification. Section 06 is the file itself, 07 is the prompt that converts a messy sheet into it, and 09 is the reason we may never have to pay for that conversion.

01 · THE WHOLE RULE

One row,
one object

Not one row per photo, not one row per copy. Own three pressings of the same record? Three rows — they are three objects with three conditions and three prices.

A header row,
in any order

First line names the columns. Case, accents and order are all irrelevant. Title, TITRE and name all land in the same place.

Only name
is required

A file with one column and four hundred rows is a valid import. You get four hundred objects waiting for detail, which is four hundred more than you had.

02 · THE COLUMNS

Twelve, and eleven of them optional. If a concept isn't here, it belongs in a column of your own — see section 04.

COLUMN

WHAT IT HOLDS

EXAMPLE

STATUS

03 · WHAT WE SORT OUT WITHOUT ASKING

Every one of these is a dialog box a lesser importer would show you. None of them is a question you should have to answer about your own file.

04 · THE COLUMN WE DON'T RECOGNISE

We keep it. All of it.

An unmatched column becomes a field of your own, attached to every object in the file, named exactly what you named it. Étagère, Prêté à, Rayure ? — someone spent years filling those in. Discarding them because they aren't in our twelve would be the single most insulting thing this app could do on day one.

The consequence to accept: collections arrive with fields we can't compute on. That's correct. Storing a fact we don't understand is cheaper than losing it.

05 · THE FIVE THINGS THE IMPORTER NEVER DOES

06 · THE TEMPLATE

This is the file we hand out — a header row and five example rows: a fully filled-in object, one where only the year is known, a second copy of something held as its own row rather than a quantity, twelve genuinely interchangeable coins that do belong on one row, and a last row carrying nothing but a name and a type, to prove that counts as a valid entry. Anyone can delete the examples and start typing.

CLCTN-TEMPLATE.CSV

{{ l.t }}

Also published as an Excel file and a Numbers file with the same columns, because telling a collector to "just save it as CSV" is where half of them stop.

07 · THE PROMPT WE PUBLISH WITH IT

Some files are past mechanical rescue: merged cells, three collections in one sheet, condition and price in the same string, fifteen years of shorthand only the owner understands. Writing a parser for those is a year of work. Handing the owner a prompt is an afternoon.

So we publish the prompt beside the template. The collector pastes it into whichever assistant they already pay for, along with their own sheet, and gets back a file this importer reads cleanly. It costs us nothing to run, it improves every time those models improve, and — the part that matters — their spreadsheet never comes near us. The conversion happens in their account, on their terms.

CLCTN-CONVERSION-PROMPT.TXT

ONE TAP TO COPY, IN APP

{{ p.t }}

07b · THE PER-TYPE APPENDIX

This is where the prompt earns its keep. Condition and identifier mean something different in every collecting world, and a model told what they mean produces data close enough to ours to price against. Only the block matching the collection gets appended — a vinyl collector never reads the watch rules.

TYPE

CONDITION MEANS

IDENTIFIER MEANS

The line we have to hold

The prompt says never invent four separate times, because a language model's instinct is to be helpful and fill the gap. A hallucinated purchase price is worse than an empty cell — it looks like a fact the owner supplied, it flows into insurance totals, and nobody ever catches it. Anything the model was unsure about arrives flagged, at the top of the collection, in the owner's face.

08 · THE TUTORIAL

Published as one page with five screenshots, and shown inside the app the moment someone taps Copy the prompt. Written for a collector who has used ChatGPT twice and is not sure whether this is going to break something.

AND THE THREE THINGS THAT WILL GO WRONG

09 · OR THE MODEL ALREADY ON THE PHONE

You said you don't want to pay to host a model. You don't have to — Apple ships one inside iOS 26, and the Foundation Models framework hands it to us at no inference cost. Worth the afternoon you're planning to give it, because it changes the shape of the feature. It is also beta software with a hard OS floor, which is why it changes the shape rather than replacing it.

Four things in that documentation matter to us, in descending order of how much they matter.

THE FINE PRINT THAT DECIDES IT

What I'd test first, in this order

Take one genuinely awful real spreadsheet. One: define the twelve columns as a @Generable struct with a @Guide on every property and convert a single row — if guided generation holds, the malformed-output problem is gone permanently. Two: feed it thirty rows in batches and check whether the type label stays consistent across batch boundaries, because that is the thing a chunked loop breaks and the thing that decides whether the import lands as one collection or four. Three: hand it a photo of a handwritten page. If that works even badly, it is a feature no competitor has, aimed precisely at the collector nobody else can reach.

What none of it changes: the published prompt stays. On-device is a shortcut for recent iPhones running an OS that is still in beta — the floor has to work on a 2020 handset and on a Mac, and section 08 is that floor.

10 · HOW CLEVER THIS ACTUALLY HAS TO BE

Reading the sections above, the importer looks like it needs to be the smartest thing in the app. It needs to be close to the least smart — and every place we were tempted to add intelligence is a place to add a list or a screen instead.

Three layers, in descending order of cleverness required. The last one requires none.

Put the intelligence in the screen, not the code.

A mediocre guess shown plainly, with one tap to correct it, beats an excellent guess made silently. The collector knows what ETAGERE means and we never will — so the mapping screen is not a confirmation step bolted onto the importer, it is the importer. Everything behind it can be boring.

Which leaves exactly one thing that needs real care, and it is not cleverness — it is the discipline in section 05. Never overwrite, never merge, never invent, undo the whole batch for thirty days. A dumb importer with those four rules is trustworthy. A brilliant one without them is not.

11 · WHAT I NEED DECIDED