[plainprogrammer]

Defines the format a collector's data is exported in, so that export (#38), import preview (#39) and import apply (#40) are built against one definition. It is an enabling slice: a format document, a schema, examples and an ADR. No page, job, setting or application code is added.

Closes #37

Why

Foundation principle 2 says collectors own their data in open, documented formats, and the 1.0 test's second check ("an export of that instance has been restored into a fresh instance and matched") had no definition of "matched". This PR gives it one.

What the format is

• One JSON document per account, UTF-8, with a header (format, format_version, exported_at, optional generator), the collector's profile, one currency and the lots.
• Keyed by external ids. A lot's entry is identified by collectible_type and source_id (for Magic, the Scryfall card id). No internal primary key appears anywhere. The name, set code, collector number and language ride along as information only, so a person can read the file without a catalog.
• A lot carries its quantity, finish, condition, price paid per copy (a two-place decimal string) and when it was added and last changed. Finish, condition and price are always present, and null when not recorded.
• Well-formed and resolvable are kept apart. Whether a file is well-formed never depends on a catalog; whether its entries exist is a question about one instance.
• "The same collection" is defined by the profile, the currency and the lots as sets. That is what "matched" means.
• format_version is a whole number, 1 here. It rises when an older reader would misread a file or lose the collector's data from it, so the spec that puts a lot in a location (Put a lot in a location #45) will make version 2.

What changed

• docs/export-format/README.md: the format document.
• docs/export-format/v1.schema.json: a JSON Schema (draft 2020-12).
• docs/export-format/examples/: 33 example files (valid, invalid, and pairs for the comparison rule) and problems.json, which names why each invalid file is invalid.
• spec/export_format_examples_spec.rb, spec/export_format_document_spec.rb, spec/support/export_format_rules.rb: 27 examples that check the document, the schema, the examples and the application against each other.
• docs/adr/0020-export-format.md: the decision and the alternatives rejected (CSV, an id-only reference, descriptive fields as a fallback match, whole-number minor units for price).
• Gemfile: json_schemer in the :test group, require: false. The published image installs the test group already, so the gem is present there and never loaded.
• README.md, docs/adr/README.md, docs/roadmap.md (item 2 done, decision log 32), CLAUDE.md.

The guard for "export covers it"

The format document has a coverage table of every database table that belongs to an account or a user: exported, left out, or nothing to export, with each column of an exported table accounted for. The suite compares it with the database, so a later spec that adds a table with account_id or user_id, or a column to accounts, lots or users, fails until the document says what the format does about it. It compares names; it can't tell whether a mapping is right.

Verification

• bin/ci passed locally on 37e7778: 1146 examples, 0 failures, 1 pending (pending before this branch too; the baseline was 1119). The head commit adds only the verification record after that run. The pre-push hook ran bin/ci again on the head commit and let the push through.
• Each phase was written test first; its red and green counts are in the verification record.
• A read-only review of the implementation against the spec found all 20 acceptance criteria met: 13 by passing examples and 7 by reading the format document.

Spec: spec.md · Plan: plan.md · Verification: verification.md · Format: docs/export-format/README.md · ADR 0020

There are no screenshots: nothing a collector or operator can see changed.

Worth a look

• The field names are frozen once this merges. The meaning of version 1 never changes after release.
• The spec moved after approval, to 1.2.1. Version 1.2.0 records six additions the maintainer approved with the plan (a repeated JSON key and a time that is no real moment are not well-formed, no byte order mark, collection_view is required, accounts is in the coverage table, generator may name any program). Version 1.2.1 fixes four sentences that were left stale.
• The rules module is test support. Import (Preview an import #39) decides where a copy inside the app lives, and must look at format_version before it validates: a file of a higher version fails version 1's schema, and is "newer", not malformed.
• Sibling branches (specs 018 and 019) may also touch CLAUDE.md and the roadmap's decision log. ADR 0020 and log row 32 were free on main when this was pushed.

Owed from the maintainer

• Read docs/export-format/README.md as rendered on GitHub, including its relative links. That rendering is unchecked.
• Confirm the GitHub checks pass (the ci job and both image builds with their smoke test). They run only on a pull request.
• Session wrap for memories and lessons, before this is marked ready.
• At merge, re-check ADR 0020 and decision-log row 32 against whichever sibling branch merged first.

No phone or in-person check is needed for this spec.

🤖 Generated with Claude Code