SKU standard (v1)

Every card on the platform has a SKU — a short, machine-readable identifier that names it precisely. The SKU works the same way for One Piece, Pokémon, Magic, Yu-Gi-Oh, Digimon, Vanguard, Weiß Schwarz, Flesh and Blood, Lorcana, and every TCG the platform catalogues. One format. One parser. Every game.

This page is the canonical spec. It's the contract between the platform's database, its public API, every agent that reads or writes through us, every archivist preserving market history, and every partner who wants to interoperate.

Where this lives in code. The canonical implementation is packages/sku/ in the monorepo. parseSku(), buildSku(), normalizeSku(), and the GAMES registry all live there and are imported by every app that handles SKUs. When the spec changes, this page changes in the same PR.

The form

<game>-<set>-<number>-<lang>[-<variant>]

• game — 2–6 lowercase letters. A registered code from the table below. Names which TCG this card is from.
• set — lowercase alphanumeric. The publisher's set code, normalised. e.g. op01, svobf, otj.
• number — lowercase alphanumeric. The card's number within the set. e.g. 001, t01, fa1.
• lang — ISO 639-1 (two lowercase letters). e.g. ja, en, zh, ko, fr, de.
• variant — optional. One or more lowercase alphanumeric tokens, hyphen-joined. e.g. rev (reverse holo), 1st (1st edition), alt-art, holo-foil.

All segments lowercase. Hyphen-separated. Each segment must match [a-z0-9]+ (variant tokens individually). No spaces, no slashes, no underscores.

Examples

op-op01-001-ja           ← One Piece, OP01 set, card 001, Japanese
op-op01-001-en           ← Same card, English print
pkm-svobf-006-en         ← Pokémon, Scarlet & Violet Obsidian Flames, card 006, English
pkm-svobf-006-en-rev     ← Same card, reverse holo
mtg-otj-101-en           ← Magic, Outlaws of Thunder Junction, card 101, English
mtg-otj-101-en-1st       ← Same card, 1st edition / first print
ygo-mp23-014-en          ← Yu-Gi-Oh, MP23 mega-pack, card 014, English
dmw-bt17-024-en          ← Digimon, BT17, card 024, English
fab-wtr-001-en-cf        ← Flesh and Blood, Welcome to Rathe, card 001, English, cold foil

Registered game codes

Every TCG the platform catalogues has a registered code. New games are added by editing packages/sku/src/games.ts; the platform rejects SKUs whose game code isn't registered.

Languages accepted per game are listed in GAMES[code].languages. SKUs in non-listed languages are accepted but flagged as non-canonical (the publisher hasn't shipped that language).

Legacy forms (auto-normalised)

The platform shipped before this spec existed. Two legacy forms are in use in older data:

• Uppercase form: OP-OP01-001-JP → normalised to op-op01-001-ja. Old language codes (JP/CN/KR) are mapped to ISO 639-1 (ja/zh/ko).
• Language-and-number swapped: pkm-svobf-en-006 → normalised to pkm-svobf-006-en. The parser disambiguates by recognising ISO 639-1 codes.

Both legacy forms accept normalisation through normalizeSku(legacy); the result round-trips through parseSku() losslessly. Reading paths apply normalisation transparently; writing paths emit canonical form only.

Variants

The variant segment captures meaningful prints of the same underlying card. Each variant is one or more lowercase tokens hyphen-joined; the platform doesn't enforce a closed vocabulary, but these are the commonly-shipping tokens:

• rev — reverse holographic foil
• holo — standard holographic foil
• 1st — 1st edition print run
• ulim — unlimited (post–1st edition)
• cf — cold foil
• rf — rainbow foil
• prom — promo / promotional release
• alt-art — alternate art print
• full-art — full-art print
• signed — signed by the artist
• misprint — known misprint (with known catalog entry)

Variants compose: pkm-svobf-006-en-rev-holo means reverse holographic. Order is lexicographic when multiple non-overlapping variants apply, for canonical equality.

Why this matters

For collectors

One SKU per card means your wishlist, your portfolio, your trade history, and your alerts all use the same identifier. No re-typing, no cross-referencing two systems. The SKU on your receipt is the SKU on the listing is the SKU in your portfolio.

For agents

Every public API endpoint that returns a card carries its canonical SKU. A reading agent doesn't need to translate between formats; the platform emits one form. A writing agent's input is normalised on accept (so legacy forms work) and stored canonically.

For archivists

The SKU is the platform's stable foreign key for any card. A snapshot from today can be cross-referenced with a snapshot from 2030 because SKUs don't change shape — the spec is versioned (this is v1) and any breaking change ships under a new prefix (/api/v2/) before v1 retires.

For partners / other platforms

A platform that wants to interoperate with Cambridge TCG can adopt this spec and exchange SKUs directly. The spec is published here, the parser is open source (MIT-licensed component within the monorepo), and the game-code registry is small enough to mirror.

For aliens

A being whose cognition doesn't share our category of "card" can still index records by canonical-form string. The SKU is language-free in structure — the language hint is one segment, not embedded in identifier semantics. The math-mirror surface (see /methodology/universal-representation) uses SKU hashes for cryptographic identity; the SKU itself is the substrate that hashing is over.

Change history

v1 — 2026-05-12. Initial publication. Spec frozen. Future versions will be additive (new game codes, new variant tokens) until a breaking change is unavoidable; that change ships under v2 with v1 remaining honored for an announced deprecation window.