.stack

A standardized file format for importing and exporting lists of trading cards.

Status: RFC. This is a proposal. Nothing here is final. Feedback is requested via issues.

The problem

Every collection site, deck builder app and marketplace exports card lists in its own CSV or text dialect. Column names differ, data types are loose, and importing a list from one site into another is a guessing game that regularly fails or silently drops data.

And this is not a rare migration event. Card lists move constantly: wishlists go to marketplaces to be bought, decklists travel between builders and playgroups, trade lists and buylists change hands, purchases land back in collection trackers. Every one of those hops crosses a dialect boundary today.

The proposal

One small JSON format with fixed field names and strict types, validated by a published JSON Schema. If a file is valid, an import will succeed. That is the whole promise, and the schema is what makes it work universally.

{
  "stack": "1.0",
  "game": "mtg",
  "cards": [
    { "qty": 4, "name": "Lightning Bolt", "set": "m21", "number": "234", "finish": "foil" }
  ]
}

Only qty and name are required per card. Everything else (set, collector number, external ids, finish, language, condition, grouping) is optional, so the format covers everything from a scribbled-down decklist to a full collection export with Scryfall and Cardmarket ids.

Read the spec: SPEC.md

Design goals

• Guaranteed import. Validity is machine-checkable. Importers must accept every valid file and must ignore what they do not understand.
• Human-readable first. Card name and set are the identity. External ids (Scryfall, Cardmarket, ...) are an optional reference for exact printing resolution, never a requirement. You can read and write a .stack file in a text editor.
• Trivial to adopt. A site that already exports CSV can emit .stack with a few dozen lines of code. No library required beyond a JSON serializer.
• Game-agnostic core, per-game profiles. The envelope and card fields work for any TCG. Profiles pin what names, set codes and id namespaces mean per game: MTG, Pokemon, Sorcery. Want a profile for your game? Here is how to propose one.
• Minimal. Two required fields per card. Extensions are additive.

Why JSON and not CSV?

The industry exports CSV today, and CSV is exactly why imports fail: quoting, encodings, Excel mangling, semicolon locales, and no types. A "strict CSV" spec cannot be enforced, because most CSVs are round-tripped through tools that break strictness.

Adoption is not hurt by JSON, because the people who adopt this format are developers at sites and app makers, and every one of their stacks already speaks JSON. For site-to-site transfer, end users never open the file; they download from one site and upload to another.

Spreadsheets are the honest exception. Many people manage collections in Excel or Google Sheets, and neither imports JSON comfortably. That does not change the interchange format, but it is a real workflow to serve: see open question 5 on a defined CSV projection.

Non-goals

• Not a card database. The format carries references, not card data (no rules text, no images).
• Not a pricing format. Market data is out of scope for v1 (see open questions).
• Not a game rules format. group is a plain label, the spec does not define deck legality or zone semantics.

Open questions

Input is specifically requested on these. Each has a seeded issue, discuss there.

• Prices (#1). This will come up. Collections track acquisition price, marketplaces export listing prices, and users will ask for it. But price data drags in currency codes, price kinds (paid, ask, market, trend), timestamps (a price without a date is noise) and a maintenance burden that card identity does not have. Should v1 define a price field, reserve a shape for v1.x, or declare it permanently out of scope?
• Condition scale (#2): choosing a standard here is genuinely hard. There is no industry-wide grading standard, scales differ per marketplace (7 grades on Cardmarket, 5 on TCGplayer), grading is subjective, and every mapping between scales is lossy. v1 picks the 7-grade scale since a finer scale can represent a coarser one, but this is the most contested field in the spec. Should the spec define the mapping from the 5-grade scale (NM/LP/MP/HP/DMG), leave it to exporters, or drop condition entirely?
• Should there be a registry of game tokens and id namespaces in this repo, so two sites never mint the same name for different things? (#4)
• Spreadsheet access (#5). Many people manage collections in Excel or Google Sheets, and neither imports JSON comfortably. Card entries are flat, so a defined CSV projection (fixed column names matching the field names, id.scryfall flattened to id_scryfall) would be nearly lossless and give spreadsheet users a standardized path in and out. Should the RFC define this projection as a companion representation, or is JSON-only with per-site CSV exports enough?
• Media type registration, e.g. application/x.stack+json. (#6)
• Game-specific: Pokemon edition stamps (#7), Sorcery printing identity (#8), and a Yu-Gi-Oh! profile needs a domain expert owner (#3).

Validating a file

Any JSON Schema validator works, e.g.:

npx ajv-cli validate --spec=draft2020 -s schema/stack.schema.json -d examples/minimal.stack

Examples

See examples/: minimal, collection with ids and conditions, deck with groups, and one per profile: Pokemon, Sorcery.

Adopters

Sites and apps that import and/or export .stack:

• paperrectangles.eu (EU TCG marketplace): imports .stack for collection, inventory, bids and wishlists; exports collection, inventory and wishlists. Reference implementation.

Adopted the format? Open a PR adding your site or app to this list, stating what you import and export.

Governance

While the format is an RFC, @andli acts as editor: open questions are discussed in the issues and closed by editor decision, with the reasoning recorded in the issue. This is a practical bootstrap, not a power grab, and help governing is explicitly invited: if you represent a site, app or game community and want to co-maintain the spec or own a game profile, say so in an issue.

License

CC0 1.0 (public domain). Anyone can implement this format for any purpose without permission or attribution.