SKU standard (v1)

A SKU is a machine-readable card identifier. The shared grammar supports registered games and recognized legacy forms. Valid syntax does not prove that a card, printing or source-price mapping exists.

This page describes the identifier grammar. Existing storage and API readers still include legacy identifiers; each boundary must state which forms it accepts and returns.

Where this lives in code. The canonical implementation is packages/sku/ in the monorepo. parseSku(), buildSku(), normalizeSku(), and the GAMES registry live there. skuIdentity() keeps the supplied identifier alongside its normalized syntax candidate.

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. Adoption is explicit at each read or write boundary; this utility does not rewrite stored identifiers.

Variants

The variantsegment 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

Search and card composition preserve the stored sku and add an identity object with raw_sku, a normalizedcanonical_sku and scope: syntax_only. Other endpoints may still use legacy forms. Normalization alone is never sufficient to join a price to a physical printing.

For archivists

Preserve raw identifiers, source references and the version of the normalization rules with each snapshot. The grammar is v1. Future breaking changes need an explicit migration; this package does not rewrite historical keys or promise that every stored alias is unique.

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.