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.

Try the identifier validator and builder: a browser-local companion with strict parsing, separate normalization suggestions, the bundled game registry and a public stateless API. Structure alone does not establish catalog existence, card identity, authenticity, or deck legality.

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. The implementation checks two-letter shape only, not membership in the ISO registry. Aliases such as jp can parse strictly but normalize to ja.
• 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

The table is derived from packages/sku/src/games.ts. The parser rejects SKUs whose game code is not registered. Registry status is a bundled declaration, not a fresh catalog lookup: known means marked as having catalog rows; anticipated means registered but not so marked; internal is the test code. No status verifies a particular card.

The bundled language annotations live in GAMES[code].languages. Unlisted two-letter values remain syntactically accepted; the validator annotates them separately. This is not evidence about publisher releases. Strict canonical status means parsing succeeds and normalization leaves the input unchanged, not that its language appears in this list.

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 normalizer uses its fixed language-alias map; it does not validate against the whole ISO registry.

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)

Variant tokens compose, for example pkm-svobf-006-en-rev-holo. Their presence is not proof of a printing. The implementation preserves token order; it does not sort variants or verify their meaning. Examples on this page illustrate syntax, not verified catalog entries.

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 and the parser is inspectable in the monorepo. Implementation rights: repository LICENSEand applicable more-specific notices. The specification text's CC0 dedication does not create a separate code license.

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.