malie.io Pokémon Trading Card Game export format¶
This document specifies the format used by malie.io to export Pokémon Trading Card Game data.
This is version 2024-05-20 of the draft specification, corresponding with reference exports of TCGL data in https://cdn.malie.io/file/malie-io/tcgl/export/index.json.
Changelog¶
Changes not yet being recorded until first tagged version.
Copyright and Licensing¶
FIXME
“© nago 2023-2024” for now, need to figure this out
The authors of this document are not affiliated in any way, shape or form with The Pokémon Company International, The Pokémon Company (“株 式会社ポケモン”, “Kabushiki Gaisha Pokémon”), nor any subsidiaries thereof, past or present.
Introduction¶
This specification document defines the common format used by malie.io to export Pokémon Trading Card Game data and images.
Goals¶
This format can’t reasonably be everything to everyone. The goals of this specification are:
It should be a good interchange format.
It should serve as a reasonable basis for writing tooling without needing to worry about the specifics of a particular data source’s quirks.
This format should provide a reasonable basis for normalizing data extracted both from official and unofficial sources, such as tcgo, tcgl, carddex, pokemon.com, pkmncards.com, etc.
It should be easy to understand as plaintext by a human:
The data should both make sense as a machine-readable export and as something a human can read and make sense of. This cuts down on the number of formats we need to define and creates a more obvious “single source of truth” for the definition of a card.
It should be easy to edit by a human:
Not all cards that exist are defined in digital sources; some cards will need to be defined by hand. In service of the “single source of truth” goal, the ability to submit plaintext corrections by casual contributors is vital to the accuracy and reliability of the data.
Importantly, even official digital sources are incorrect. The ability to diff, edit, and submit changes easily is a crucial feature for the format.
Natural language strings are preferred whenever possible instead of enumerated numerical IDs. You should be able to edit the file as-is without needing to “translate” to or from a machine-centric format whenever possible.
The format should be language agnostic.
Most of the data processed by malie.io is not in English; localization must be considered and integrated from the outset of the format.
Ideally, the format would not lean on English quite as heavily as it does for enumeration names and definitions. Cards are usually defined in Japanese first, but Japanese cards are currently out of scope and, in service of having any specification at all, we begrudgingly accept English as the lingua franca for enumerations. At the end of the day, English is what I speak and I’m doing the best I can!
Prefer a specification that minimizes coordination:
Ideally, when new cards are released, it should be unambiguous for how to represent them in the data format without requiring a central authority to issue reference output or provide guidance or issue hotfixes to the specification.
The longevitiy of a standard here is perceived to be linked to its usefulness for real sites to operate, and real sites often cannot wait for a standards body to provide updates to a specification on release days.
Represent information as it exists on the card:
By deferring to the information printed on the card wherever possible, the canonical source of truth is unambiguous and does not rely on cooperation between disparate parties.
Avoid data that is prone to change over time:
The definition for a card should be “set in stone” when it is created and should not function as a living document. Fields like “evolves into” are not feasible as part of this specification and should be maintained elsewhere.
This also precludes external links and information as a rule; e.g. links to Bulbapedia, Troll & Toad, TCGPlayer and so on are too volatile for inclusion here.
Avoid data that is external to the card itself:
In general, prefer describing the card itself from what can be observed on the card and avoid relying on external sources.
This cannot always be helped - for example, cards prior to Scarlet & Violet do not have any text that describes what expansion they are from, but this information is considered crucial to the functioning of an interchange format.
Essential information like card rarity names are not defined on the card itself, either. In these cases we settle for secondary official sources such as the Elite Trainer Box’s player’s guide and pokemon.com.
Bend the rules when it’s really helpful anyway:
We acknowledge that the goals as laid out above are not always strictly possible and that there are valid usability concerns that necessitate bending the rules. Oh well!
Non-Goals¶
This is not a relational database schema.
This is a specification for an interchange format, i.e., the export and transfer of data about Pokémon cards. It is not a goal of this specification to provide any considerations about how this data would be searched by a non-technical end user, nor to give any consideration to relational database schema or the normalization thereof. These concerns are considered to be implementation details and not relevant to the interchange format itself.
This is not an API specification.
Filesize or bandwidth considerations are not considered. JSON is notoriously wasteful of bandwidth due to its repeated plaintext keys, making this a terrible binary format for a production website. The mechanics of translating this specification for an efficient streaming protocol such as protobuf is beyond the scope of this document.
This is not an SDK.
This format does not make any attempt to consider or define efficient in-memory representations of card objects; only the JSON export format is described here.
Card Errata are not covered.
This specification does not cover how to handle errata. If the card has an error on it such as the wrong artist, the wrong energy cost, the wrong Pokémon name, etc - this specification does not cover how to represent that information. This specification covers solely “The card exactly as printed”.
Errata will be handled separately and elsewhere.
Scope¶
The current version of this specification covers Scarlet & Violet expansions from Pokémon TCG Live only.
Future revisions of this specification will seek to cover all Wizards of the Coast / Pokémon USA / The Pokémon Company International published cards in all languages. Even later revisions may seek to add APAC region cards. The current scope is being limited for two reasons:
We need an operational specification that addresses the immediate need of exporting data from Pokémon Trading Card Game Live to update fan sites, databases, etc - and this only involves Scarlet & Violet for TPCi cards in that immediate use case, and
Reducing the scope allows us to focus on a smaller set of cards and review the specification more thoroughly. This will allow us to incrementally broaden the scope over time and in future revisions.
Wherever reasonable, cards from outside of this scope are considered to avoid needing to rework the fundamental schema of the specification. For example, there are cards which feature multiple types and multiple illustrators, so the schema presented here accommodates those features even though they do not occur on any cards within the stated scope.
Wherever the schema may be amended by the simple addition of new enumerations to handle older (or newer) cards, these amendments are considered out-of-scope and will be handled at a later date. (I.e., new rarity names, new Pokémon stages, etc.)
The current scope for exhaustive review excludes cards from outside of the TPCi publishing region, notably the APAC regions (Japanese, Korean, Thai, Indonesian, Chinese, etc.)
Overview¶
The export format is a JSON document consisting of a list of card objects. Each card object represents a single card in a single language; different variants of each card (different foiling, etc) will each have their own object instance.
The encoding of this JSON document must be UTF-8.
The name of each field below is followed by the type of that field in parentheses. When the type is “string”, the type will be clarified as either “i18n str” when the contents of this field are likely to change based on the language of the card, or “enum str” when the contents of this field do NOT vary with the language of the card.
Not all fields marked as “i18n str” will actually vary between languages; but this marker denotes that the field is to represent the text as it appears on the card and it MAY vary between languages should the circumstance ever arise.
All fields will be marked as Optional (“nullable”) or Required (must always be present). The definition of “Optional” here does not mean the field value can be omitted at one’s discretion, but rather that the field is not guaranteed to hold a value for all cards within scope.
A field with a False-y value (empty string, 0, empty array, empty object, &c), an explicitly nulled field, and an absent field are all semantically equivalent. Not all fields that may take a “False-y” value permit omission or null values, however.
Common Fields¶
All card objects generally fall into two categories: Pokémon and Everything Else, though this taxonomy is not formally defined and is not strictly adhered to.
The fields described in this section are common to all card types, although some fields are Optional and may not be defined for a given card’s record.
The class hierarchy this suggests is not perfectly stringent; some fields that are “Optional” are in practice always defined except for certain circumstances that do not fall neatly along class boundaries:
subtype
is not currently used forPOKEMON
cards.
artists
does not happen to be defined for anyENERGY
cards in scope, but it would be if any Energy cards did list an illustrator. Classic WOTC cards did list illustrator credits for Energy.
regulation_mark
also does not happen to be defined for anyENERGY
-BASIC
cards, but it would be if any Basic Energy cards did happen to feature a regulation mark.Some
tags
are only semantically valid for certain categories of cards. There are no tags currently defined that apply to any Energy cards in-scope, but there’s no fundamental reason why this will or should remain true.
On rare occasion, there are cards that strain the boundaries of the
card_type
classification:
Cards with the
PLAYABLE_TRAINER
tag will also have thehp
field set, as if they were a Pokémon. Thehp
field is required for Pokémon, but Optional for Trainers.The
types
field is required forPOKEMON
, but is also required forENERGY
-BASIC
cards too!
lang
(enum str, Required)¶
The language as written and used on the card, as a BCP 47 language tag.
This field does not describe the region in which a card was published; it describes the language present on the face of the card.
Under the current scope of this specification (TCGL cards only, SV-on), this should be one of the following languages:
de-DE
(🇩🇪 Deutsch)en-US
(🇺🇸 American English)es-ES
(🇪🇸 Español)fr-FR
(🇫🇷 Français)it-IT
(🇮🇹 Italiano)pt-BR
(🇧🇷 português brasileiro)
All cards published and distributed by TPCi since Scarlet & Violet released are one of six languages: English, German, Spanish, French, Italian or Brazilian Portuguese.
Additional languages are presently beyond the scope of this specification; including all of the APAC regions and languages (Japanese, Korean, Indonesian, Thai and Chinese). Other langauges that are not in current production are also beyond the scope of this document (Russian, Polish, Dutch, Portuguese).
All official Portuguese cards produced in this timeframe have been for the LATAM/Brazillian market specifically, and so “pt-BR” is used instead of “pt-PT”.
The majority of English cards produced in this timeframe have been for the North American market, and so “en-US” is preferred. e.g., “Grafaiai” has an attack named “Colorful Graffiti” and not “Colourful Graffiti”.
Out of scope
Cards not present in TCGL are currently beyond the scope of this document, and mercifully, precludes us from discussing the FUTSAL promotional cards, which may rightly be “en-GB”. 🇬🇧☕💂)
card_type
(enum str, Required)¶
The gameplay type of this card. Regardless of the card’s language, this is one of three strings:
POKEMON
ENERGY
TRAINER
POKEMON
¶
POKEMON
cards feature a stage
in the upper-left corner of the
card, HP
and types
in the upper-right corner of the card, list
weakness
, resistance
and retreat
information, and have one or
more abilities/attacks in the card text area.
ENERGY
¶
ENERGY
cards have the word “ENERGY” (or the localized equivalent)
in the upper-right corner of the card:
TRAINER
¶
TRAINER
cards have the word “TRAINER” (or the localized
equivalent) in the upper-right corner of the card:
Out of scope
How to classify Diamond & Pearl era Stadium/Supporter cards, LEGEND cards, and V-UNION cards are beyond the current scope of this specification and will be addressed in a future revision.
See Appendix A
for localizations.
subtype
(enum str, Optional)¶
For TRAINER
and ENERGY
cards, a required additional
classification of the gameplay type of the card. POKEMON
cards do
not utilize this field.
For TRAINER
cards, the subtype is specified on the card in the
upper left, on the same line as “TRAINER” (or the localized
equivalent) in the upper-right. It is one of:
ITEM
SUPPORTER
STADIUM
TOOL
For ENERGY
cards, the subtype is specified on the card in the
upper left, on the same line as “ENERGY” (or the localized equivalent)
in the upper-right. It is one of:
BASIC
SPECIAL
ITEM
¶
ITEM
cards say “Item” (or the localized equivalent) in the
upper-left hand of the card in blue text, on the same line as
“TRAINER” (or its localized equivalent).
SUPPORTER
¶
SUPPORTER
cards say “Supporter” (or the localized equivalent) in
the upper-left hand of the card in red text, on the same line as
“TRAINER” (or its localized equivalent).
STADIUM
¶
STADIUM
cards say “Stadium” (or the localized equivalent) in the
upper-left hand of the card in green text, on the same line as
“TRAINER” (or its localized equivalent).
TOOL
¶
TOOL
cards say “Pokémon Tool” (or the localized equivalent) in the
upper-left hand of the card in purple text, on the same line as
“TRAINER” (or its localized equivalent).
BASIC
¶
BASIC
cards say “Basic Energy” (or the localized equivalent) in the
upper-left hand of the card in darkened text, on the same line as
“ENERGY” (or its localized equivalent).
SPECIAL
¶
SPECIAL
cards say “Special Energy” (or the localized equivalent)
in the upper-left hand of the card in darkened text, on the same line
as “ENERGY” (or its localized equivalent).
name
(i18n str, Required)¶
The name field contains the name of the card as written (where possible; see below for exceptions).
Subtitles¶
Some cards feature a subtitle that is not considered to be part of the
name, and should be omitted from the name
field. See the subtitle
field
definition for more information.
Type symbols¶
Names occasionally contain symbols that cannot be represented by UTF-8. In those cases, a standardized markup is used. For cards that include energy symbols in the name, the following markup is defined:
—
{G}
—
{R}
—
{W}
—
{L}
—
{P}
—
{F}
—
{D}
—
{M}
—
{Y}
—
{N}
—
{C}
The single-letter codes are chosen considering official shorthand from a variety of sources. In the future, if new markup becomes necessary, Pokemon Trading Card Game Live’s deck export feature will be consulted to check the canonical markup. TCGL’s markup will be preferred, provided it does not conflict with existing markup in this standard.
Sources for currently-defined markup:
Wizards of the Coast Oracle text uses
{G|R|W|L|P|F|C}
shorthand from the earliest days of the original Base Set [1]Wizards of the Coast Oracle text for Neo Genesis adds
{D|M}
shorthand codes for [2]Official “Card Dex” PDFs (which ceased mid-BW era) also use
{G|R|W|L|P|F|D|M|C}
[3]{N}
, representing can be seen in the Card Dex PDFs for Dragons Exalted [4]Pokémon TCG Online used
{G|R|W|L|P|F|D|M|N|Y|C}
in its deck export functionality, as well as allowing users to type those symbols in chat. [5]Pokémon TCG Card Dex used these codes in its internal data. [6]
Pokémon TCG Live uses these codes in its deck export functionality, as well as in its internal data. [7]
Pokémon ex¶
The “ex” symbol, representing both Pokémon ex and Tera Pokémon ex, is represented simply by the string “ex”. The current version of this specification does not provide a discrete method in markup for differentiating between the blue and silver “ex” symbol used for Pokémon ex or the crystalline “ex” used for Tera Pokémon ex.
How to write “ex” card names in plain text for each language can be determined by consulting the Pokémon ex Rule Box. Languages that use the phrase “Pokémon ex” in the Rule Box use a space between the Pokémon name and “ex”. Languages that use the phrase “Pokémon-ex” use a hyphen between the Pokémon name and “ex”.
Caution
Different languages have different conventions for how to write the name of a “Pokémon ex” in plaintext.
A non-exhaustive list of examples:
Gender symbols¶
Cards with ♀ or ♂ in the title use the UTF-8 characters for those symbols. The Emoji selector is not used.
Prefixes and Suffixes¶
Regional form Pokémon have their form names typeset in a smaller font. The form name is still part of the card name, and is not marked up in any special way.
Some Trainer cards have a prefix that is similarly typeset; those prefixes are also part of the card name and are not marked up.
Some cards have a suffix that is also considered to be part of the name. “Pikachu with Grey Felt Hat” is the prime example.
subtitle
(i18n str, Optional)¶
Some cards feature a subtitle that is not considered to be part of the
card’s name
. Subtitles are typeset using a smaller, gray font that
is right-justified. The subtitle field is any remainder of the text in
the title area that is not part of the canonical name
of the card.
This field may be omitted when there is no subtitle.
Cards in-scope (SV-on) at time of writing that have subtitles:
Boss’s Orders (Japanese: ボスの指令)
Ghetsis
Giovanni
Professor’s Research (Japanese: 博士の研究)
Professor Magnolia
Professor Sada
Professor Turo
There may be future additions to this list. The normative references are the Pokémon Trading Card Game Rulebook and Official errata announcements which define what text is or is not part of a card’s name.
Note
By convention, these subtitles may be printed in parentheses alongside the name of the card, e.g. “Professor’s Research (Professor Sada)”. The parentheses are not part of the subtitle field. Parentheses are not currently known to appear in the name of any card.
For example, refer to the Pokemon Trading Card Game Database for how they display Professor’s Research (Professor Oak)
Caution
Pokémon Trading Card Game Live will omit these subtitles when exporting decks in English, but includes them in parentheses when exporting in any other language.
artists
(object, Optional)¶
Object describing illustrator credits; may be omitted for cards that do not have any visible illustrator credits such as Basic Energy cards.
artists.text
(i18n str, Required)¶
The illustrator credit and prefacing credit type, as it appears on the card. The prefacing credit type is preserved exactly as it appears on the card. The overwhelming majority of credits are “Illus.” (or localized equivalent), but other forms of credits have shown up on occasion.
artists.list
(i18n str[], Required)¶
An ordered array of credited artists that appear on the card, with the prefacing credit type removed.
The artists should otherwise be written as they are credited on the card. In the event that an artist is credited differently in different localizations of the card, that difference should also be reflected in this field and not be normalized.
regulation_mark
(i18n str, Optional)¶
The regulation mark, as written. Since the mark was introduced, it has been a single capital letter in the lower-left of the card face. Legal values for TPCi-published cards are currently “D”, “E”, “F”, “G” and “H”.
All SV cards published in TCGL to date are regulation mark “G” or “H”.
Basic Energy cards do not have a regulation mark, in which case this field will be omitted, or null.
Out of scope
How to represent the “Ditto” regulation mark from the Sword & Shield special Pokémon GO set is currently out of scope.
set_icon
(i18n str, Required)¶
A textual representation of the expansion icon that appears in the lower-left hand of the card, to the right of the regulation mark.
Starting with Scarlet & Violet, all cards including Energy cards and promotional cards have a text-based set icon.
The language code that appears in a smaller font to the right of the expansion code should be separated by an underscore. (This decision is fully arbitrary, but is for readability.)
Out of scope
How to represent graphical icons from earlier sets that do not have intuitive text representations is out of scope and will be addressed in a subsequent revision of the specification.
collector_number
(object, Optional)¶
Object describing the “collector number”, which appears in the lower-left hand corner of the card, to the right of the set icon and to the left of the rarity symbol.
As of Scarlet & Violet, this field is always set; prior to Scarlet & Violet, Basic Energy only had a collector number if they were part of a set.
collector_number.full
(i18n str, Required)¶
This is the full text of the collector number, including the total number of non-secret cards in the set, if present.
collector_number.numerator
(i18n str, Required)¶
The first portion of the collector number, excluding the number of non-secret cards in the set.
Note
In practice, this is the same as the “full” field, but omitting everything from the first “/” onwards. The intent is to be “separator agnostic” here; in the event that other separators are ever used, this field should still represent only information as it pertains to this specific card. (i.e. the number of THIS card, without set information.)
RFC
Is there a better name than “numerator”? As Egon points out, it isn’t exactly a fraction. Egon uses “left part” and “right part” which I just find a little too generic for my tastes.
collector_number.denominator
(i18n str, Optional)¶
The second portion of the collector number, the number of non-secret cards in the set.
Note
In practice, this is the same as the “full” field, but omitting every character until one after the first “/” is encountered.
collector_number.numeric
(int, Required)¶
A numeric version of the “numerator” field, which necessitates the removal of any non-numeric information that may appear in the collector number.
Note
Although it’s out of scope for now, The intent for Alph Lithograph cards that feature collector numbers written as “ONE”, “TWO”, “THREE”, and “FOUR” in Unown script would produce the numeric values 1, 2, 3 and 4 here.
rarity
(object, Optional)¶
Object representing rarity information. This field is Optional because some cards do not have any rarity information present, such as “setless” Basic Energy cards.
rarity.designation
(enum str, Requred)¶
The rarity designation of the card. Must be one of:
PROMO
— For all cards featuring the iconCOMMON
UNCOMMON
RARE
DOUBLE_RARE
ILLUSTRATION_RARE
ULTRA_RARE
SPECIAL_ILLUSTRATION_RARE
HYPER_RARE
SHINY_RARE
SHINY_ULTRA_RARE
ACE_SPEC_RARE
Since Scarlet & Violet, this designation correlates 1:1 with the rarity symbol printed on the card, but this has historically not always been the case. While the canonical rarity of the card can be determined in recent cases solely by the symbol on the card, older cases must be determined by consulting either:
The Card Checklist PDF published on pokemon.com or tcg.pokemon.com, which offers a rarity key at the bottom of the page, or
The physical Player’s Guide booklet included with each expansion’s Elite Trainer Box, which also offers a rarity key. Prior to Scarlet & Violet, this rarity key was the only canonical source of rarity information for secret cards within the expansion.
The rarity key for each language is as follows:
FIXME
Add rarity keys for Paldean Fates (Shiny) and SV5 (ACE rare)
Note
For Scarlet & Violet, the rarity designation correlates directly and unambiguously with the rarity icon. That mapping is:
Designation |
Symbol |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Out of scope
The rarity designation for cards released prior to the introduction of ETB booklets is out of scope for this document and will be addressed later.
In general, the canonical sources of rarity information are:
Wizards of the Coast oracle text
Physical checklists packaged with theme deck products (Through end of WOTC)
Pokémon USA Card Dex PDFs (through mid-BW)
ETB Player’s Guide booklets (from late-BW onwards)
In some cases, these sources disagree particularly on “secret” cards, which will require closer scrutiny and review at a later date.
rarity.icon
(enum str, Required)¶
A description of the rarity icon symbol itself as it appears on the card.
Symbol Name |
Symbol |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
There are no known official sources for names of these icons, so they have been arbitrarily chosen here. If new rarity icons are introduced, we will unfortunately require an amendment to this specification.
Note
SOLID_CIRCLE
, SOLID_DIAMOND
and SOLID_STAR
are printed in black ink, except on Darkness-type cards where
white ink is used for contrast reasons instead. TWO_BLACK_STARS
are always printed in black, but use a white outline when
necessary.
copyright
(object, Required)¶
Object representing copyright information at the center bottom of the card.
copyright.text
(i18n str, Required)¶
Copyright text as it appears on the card, exactly as written.
copyright.year
(int, Required)¶
The most recent year in the copyright string as an integer.
size
(enum str, Required)¶
An enumeration that describes the physical size of the card.
This is always
STANDARD
for cards in TCGL, whose real world equivalents are 63mm x 88mm.G8_OVERSIZED
refers to the newer oversized cards introduced shortly after the launch of Sword & Shield. They measure 5.25” x 7.375” (5 1/4” x 7 3/8”).OVERSIZED
refers to the classic size of oversized cards produced from 2000 to 2020. They measure 5.75” x 8”.BOX_TOPPER
refers to the Box Toppers produced in the late WOTC era. They measure about 91.5mm x 127mm or 3 5/8” x 5”.
back
(enum str, Required)¶
An enumeration that describes the design on the card back.
This is one of:
POCKET_MONSTERS_1996
POKEMON_1999
POKEMON_2001
MY_FIRST_BATTLE
WORLD_CHAMPIONSHIPS_2004
WORLD_CHAMPIONSHIPS_2005
WORLD_CHAMPIONSHIPS_2006
WORLD_CHAMPIONSHIPS_2007
WORLD_CHAMPIONSHIPS_2008
WORLD_CHAMPIONSHIPS_2009
WORLD_CHAMPIONSHIPS_2010
WORLD_CHAMPIONSHIPS_2011
WORLD_CHAMPIONSHIPS_2012
WORLD_CHAMPIONSHIPS_2013
WORLD_CHAMPIONSHIPS_2014
WORLD_CHAMPIONSHIPS_2015
WORLD_CHAMPIONSHIPS_2016
WORLD_CHAMPIONSHIPS_2017
WORLD_CHAMPIONSHIPS_2018
WORLD_CHAMPIONSHIPS_2019
WORLD_CHAMPIONSHIPS_2022_BLUE
WORLD_CHAMPIONSHIPS_2022_ORANGE
WORLD_CHAMPIONSHIPS_2022_PINK
WORLD_CHAMPIONSHIPS_2022_YELLOW
WORLD_CHAMPIONSHIPS_2023_BLUE
WORLD_CHAMPIONSHIPS_2023_GREEN
WORLD_CHAMPIONSHIPS_2023_ORANGE
WORLD_CHAMPIONSHIPS_2023_YELLOW
This is always POKEMON_1999
for cards in TCGL, which is the classic
design introduced in 1999 and has been the exclusive card back for all
competition legal cards produced in NA, LATAM and Europe.
Although unused in the current scope of this specification,
POKEMON_2001
represents the redesigned Japanese back while
POCKET_MONSTERS_1996
represents the classic Japanese design.
This field requires some coordination from a standards authority contrary to our stated goal; however, the design of the back is unlikely to change very often and it should not pose a problem in practice. The World Championships card backs are updated every year, but follow a predictable pattern - generally WORLD_CHAMPIONSHIPS plus the year, and if needed, a disambiguating color.
foil
(object, Optional)¶
Object representing the foil attributes of the card, if any. If the card does not have any foiling or etching, this field can be omitted.
foil.type
(enum str, Required)¶
An enumeration representing the type of foil layer present on the physical card.
This is one of:
SV_HOLO
SV_ULTRA
SV_ULTRA_SCODIX
FLAT_SILVER
SUN_PILLAR
COSMOS
ACE_FOIL
FIXME
How to identify the foil layers is a work in progress. We know which foil layers are used for which cards from internal data in PTCGO, PTCGL and Card Dex. However, not all cards are present in these sources and we’ll need to define the foil layers in terms of observable properties in order to add promotional variants in the future.
We’ll need good pictures that illustrate the foil layers. I’ve stripped some cards clean with acetone and am in the process of getting convincing, representative photos of each layer.
SV_HOLO
is the standard foil layer used for Rare cards in the SV era. It looks like mostly horizontal prismatic bands.FLAT_SILVER
is the standard foil layer used for most parallel holo cards - though the parallel holo mask design may change from generation to generation or card type to card type, the foil layer itself is a simple flat reflective layer.SUN_PILLAR
is used for , and cards. It has a characteristic diagonal prismatic banding that is easy to see even on cards with etching.SV_ULTRA
also features horizontal prismatic banding, but it has fewer bands visible at a time thanSV_HOLO
does. The defining characteristic is the addition of a prismatic “glitter” effect not present in theSV_HOLO
layer. It may be tough to identify this foil through the etching layer, but the presence of a prismatic glitter effect on the card border should be easier to identify. It is used for Tera Pokémon ex , Tera Pokémon ex , and cards.SV_ULTRA_SCODIX
is a new foil layer used only on the Paldean Fates Hyper Rares. Information on how to identify it is TBD; it is not currently known if this layer will be used in new sets.COSMOS
is the well-known holographic foil layer used mainly for promotional cards.ACE_FOIL
is a new foil layer used only on the new cards.
Out of Scope
The difference between “pixel” cosmos and “smooth” cosmos is out of scope for now, but will be addressed in a future revision.
The names of these foil types have been taken from the internals of Pokémon: Trading Card Game Online, Pokémon: Trading Card Game Live, and Pokémon Card Dex applications, and are not expected to change. However, some foil types are not covered by these sources and will require additional review and scrutiny when adding new types in the future.
foil.mask
(enum str, Required)¶
An enumeration that describes where the foil is visible on the card.
One of:
HOLO
— For cards where the holographic effect is applied to the illustration on the card, both for full arts and typical cards where the holographic effect only applies to a smaller illustration window.REVERSE
— When the holographic effect is applied everywhere except the illustration on the card.ETCHED
— When the card has a texture created by etching grooves into a foil layer. This is used for Tera Pokémon ex , , and cards.STAMPED
— When the only visible foil is a stamped logo. Most prominently, this refers to the WORLDS promotional cards.
Note
The names here are chosen based on internal data from PTCGO, PTCGL, and Card Dex. These distinctions have been present for long enough and over a wide enough period of time that they are unlikely to change, so we are seeking to avoid re-defining our own classifications from the ground-up.
RFC
This classification might leave some things to be desired, though: note that cards do not have any meaningful description that indicates there are little stars present. We also do not have a field at present that describes or categorizes the foil patterns visible for the reverse holos, etc.
More or less, though, the thought is: “If it’s good enough for TPCi, it’s probably good enough for us.”
I’m not against adding additional foil fields to describe other properties of the foil if we decide we really need that in the future; for example to differentiate “Holo on just the art window” vs “Holo over the entire card” which is otherwise uncaptured by the “mask” field as-is.
text
(object[], Optional)¶
An ordered array of objects representing gameplay-relevant text elements on the card, in order of their appearance on the card. For all locales in-scope, that order is top-to-bottom and left-to-right.
It may be omitted for cases where there is no text, such as for Basic Energy cards.
Fields common to all (or, most) text elements are “kind”, “name” and “text”; though not all entries will set “name”. The “kind” field can be considered as a tagged union discriminator; the following sections describe the text elements for each enumeration of “kind”.
The “name” and “text” fields, where present, represent what is written on the card verbatim; they are not enumerations and their values will vary with the language of the card.
ABILITY
¶
ABILITY
text represents a literal Pokémon Ability, printed
strictly as “Ability” (or the localized equivalent). It
does not include “Pokémon Power”, “Poké-POWER”, “Poké-BODY”, etc.
It is represented as follows:
{
"kind": "ABILITY",
"name": "Counterattack Quills",
"text": "If this Pokémon is in the Active Spot and is damaged by an attack from your opponent's Pokémon (even if this Pokémon is Knocked Out), put 3 damage counters on the Attacking Pokémon."
}
ATTACK
¶
ATTACK
text represents an attack which always has a cost, but may
sometimes omit damage or text (but not both).
A basic attack is represented as follows:
{
"kind": "ATTACK",
"name": "Superpowered Throw",
"text": "This attack does 30 more damage for each {C} in your opponent's Active Pokémon's Retreat Cost.",
"cost": [ "GRASS", "COLORLESS" ],
"damage": {
"amount": 10,
"suffix": "+"
}
}
The name
field must always be defined.
The text
field may be omitted for attacks that don’t have any
descriptive text. (Attacks that describe only a cost and damage
are common.)
The cost
field is an ordered array of types, with the order
matching the order of the symbols comprising the attack cost on the
card. Attacks that do not require energy (This can be seen on Basic
regional forms fairly often) use an explicit cost of ["FREE"]
instead.
The damage
field is an Optional compound object that can be
omitted for attacks that do not describe a damage (and only describe
some effect via the text
). damage.amount
is a Required
subfield that describes the integer amount of the damage as
written. damage.suffix
is an Optional subfield that can be the
string "×"
, "+"
, or "-"
when necessary.
EFFECT
¶
EFFECT
text represents some “effect” a Pokémon card has that is
not considered to be an ATTACK
nor an ABILITY
.
The name was chosen from the EN rulebook, which states: “Tera Pokémon ex have a crystalline appearance and a new effect that prevents all attack damage done to them while they’re on your Bench. This effect applies to all attacks, both yours and your opponent’s.” [40]
It is represented as follows:
{
"kind": "EFFECT",
"name": "Tera",
"text": "As long as this Pokémon is on your Bench, prevent all damage done to this Pokémon by attacks (both yours and your opponent’s)."
}
REMINDER
¶
REMINDER
text represents reminder text that appears on cards
calling attention to rules from the rulebook, but don’t introduce new
gameplay attributes in and of themselves.
Reminder text is represented as:
{
"kind": "REMINDER",
"text": "You may play only 1 Supporter card during your turn."
}
RULE_BOX
¶
RULE_BOX
text represents “Rule Boxes” on cards, such as the
“Pokémon ex rule”. It is only used for texts which are considered to
be a “Rule Box” for the purposes of cards such as Artazon.
A “Rule Box” must contain the word “rule” (or its localized equivalent) in its name, and only applies to cards starting from the Black & White era. [41]
Rule Boxes are represented as:
{
"kind": "RULE_BOX",
"name": "Pokémon ex rule",
"text": "When your Pokémon ex is Knocked Out, your opponent takes 2 Prize cards."
}
TEXT_BOX
¶
TEXT_BOX
text represents unstructured card text for TRAINER
and ENERGY
cards.
Text boxes are represented as:
{
"kind": "TEXT_BOX",
"text": "Search your deck for an Item card and a Pokémon Tool card, reveal them, and put them into your hand. Then, shuffle your deck."
}
Pokémon card fields¶
stage
(enum str, Required)¶
An enumeration describing a Pokémon’s stage. The enumeration is based on the English text present in the upper-left corner of the Pokémon card.
One of:
BASIC
STAGE1
STAGE2
See Appendix A
for localizations.
Out of Scope
Baby
, MEGA
, LEVEL-UP
&c will be addressed in future
revisions on an as-needed basis.
BASIC
¶
A Pokémon’s stage is BASIC
if “BASIC” (or the localized
equivalent) is written in the top-left corner of the card.
STAGE1
¶
A Pokémon’s stage is STAGE1
if “STAGE 1” (or the localized
equivalent) is written in the top-left corner of the card.
STAGE2
¶
A Pokémon’s stage is STAGE2
if “STAGE 2” (or the localized
equivalent) is written in the top-left corner of the card.
stage_text
(i18n str, Required)¶
Any text, verbatim, as included in the “Stage” graphic element, or explicit “Evovles into …” text on Antique fossil cards.
- Examples:
“Evolves from Gloom”
“Entwickelt sich aus Knilz”
“Evolves into Omanyte”
“Évolue en : Ptéra”
RFC
Should I rename this one “evolution_text”? It might serve the fossil cards from 151 better.
hp
(int, Required)¶
The Pokémon’s HP, as an integer. The HP is located in the upper-right
corner of the card, to the left of the Pokemon’s types
.
Some TRAINER
cards that can be played as Pokémon also have HP, such as
some fossils and dolls. See the PLAYABLE_TRAINER
tag.
Out of scope
The possibility of non-numerical text may need to be handled; for cards like Ancient Mew. Later.
types
(enum str[], Required)¶
The Pokémon’s type(s), as represented in the upper-right hand corner of the card. For compatibility with older expansions that occasionally feature multi-type Pokémon, this field is an Array instead of a string.
Each type is one of:
—
GRASS
—
FIRE
—
WATER
—
LIGHTNING
—
PSYCHIC
—
FIGHTING
—
DARKNESS
—
METAL
—
FAIRY
—
DRAGON
—
COLORLESS
This field is also defined for ENERGY
- BASIC
cards:
weakness
(object, Optional)¶
The Pokémon’s weakness(es), if any. It can be omitted if there are no weaknesses listed on the card.
weakness.types
(enum str[], Required)¶
An ordered list of types this Pokémon is weak to; please refer to the
types
field. If this Pokémon is weak to multiple types, they should
be listed in the same order they are on the card top to bottom, left
to right.
weakness.amount
(int, Required)¶
The numerical weakness amount as listed on the card. For cards in
scope, this is always 2
.
weakness.operator
(enum str, Required)¶
The weakness operator as listed on the card. For cards in-scope, this
is always "×"
.
resistance
(object, Optional)¶
The Pokémon’s resistance(s), if any. It can be omitted if there are no resistances listed on the card.
resistance.types
(enum str[], Required)¶
An ordered list of types this Pokémon is resistant to; please refer to the
types
field. If this Pokémon is resistant to multiple types, they should
be listed in the same order they are on the card top to bottom, left
to right.
resistance.amount
(int, Required)¶
The numerical resistance amount as listed on the card. For cards
in scope, this is always 30
.
resistance.operator
(enum str, Required)¶
The resistance operator as listed on the card. For cards in-scope, this is always "-"
.
retreat
(int, Required)¶
The retreat cost for this Pokémon, represented as an integer. If there is no retreat cost printed, this is 0.
flavor_text
(i18n str, Optional)¶
The flavor text for this Pokémon, written exactly as it appears on the card if it is present.
In the Scarlet & Violet era, flavor text is present on any Pokémon card that does not feature a Pokémon ex. (This is , , and ; and sometimes and cards.)
Other fields¶
images¶
FIXME
TODO
ext¶
FIXME
TODO
Appendix A¶
FIXME
TODO. There will be a localization table here.
References