RFC: Introduce variants_detailed in V2 (to replace variants in V3) #834
Closed
Description
Discussed in https://github.com/orgs/tcgdex/discussions/744
Originally posted by Aviortheking May 24, 2025
A new field, variants_detailed, is introduced in V2 to better describe the different physical and visual versions a card can have. This field will coexist with variants in V2 and fully replace it in V3.
New Field Structure
variants_detailed?: Array<{
/**
* define the variant type
* - normal: no holographic elements
* - holo: the illustration has a foil
* - reverse: everything but the illustration is foiled
*/
type: 'normal' | 'holo' | 'reverse'
/**
* define the size of the card
* - standard: the classic size of a card
* - jumbo: also said oversized, big card.
*/
size?: 'standard' | 'jumbo'
/**
* indicate that this variant has a stamp
* - 1st edition: a 1st edition card (mostly for the first serie of the game)
* - w-promo:
* - pre-release:
*/
stamp?: '1st edition' | 'w-promo' | 'pre-release'
/**
* for the holo & reverse, **optionnnal** indicate which foil is used on the card
*/
foil?: 'pokeball' | 'ultraball'
}>
⚠️ The listed values are examples only and do not represent the final exhaustive list. They are subject to change and expansion.
Why This Matters
The existing variants field is too limited. variants_detailed provides more precise definitions, supporting richer combinations like:
holo,jumbo— jumbo-sized holo cardreverse,1st edition— reverse foil with 1st edition stamp
This structure allows better representation of how a card was actually printed and distributed.