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.

Authors

Note

This specification is a draft. If you would like to receive authorship credit for your feedback, suggestions, or review, please let nago know how you would like to be credited and they will happily add you.

Conversely, a name appearing on this list does not necessarily infer endorsement of this draft at this time.

Changelog

  • Changes not yet being recorded until first tagged version.

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:

  1. 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

  2. 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 for POKEMON cards.

  • artists does not happen to be defined for any ENERGY 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 any ENERGY - 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 the hp field set, as if they were a Pokémon. The hp field is required for Pokémon, but Optional for Trainers.

  • The types field is required for POKEMON, but is also required for ENERGY - 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.

Pokémon card

"card_type": "POKEMON"

ENERGY

ENERGY cards have the word “ENERGY” (or the localized equivalent) in the upper-right corner of the card:

Energy card

"card_type": "ENERGY"

Energy card

"card_type": "ENERGY"

Energy card

"card_type": "ENERGY"

Energy card

"card_type": "ENERGY"

Energy card

"card_type": "ENERGY"

TRAINER

TRAINER cards have the word “TRAINER” (or the localized equivalent) in the upper-right corner of the card:

Trainer card (English)

"card_type": "TRAINER"

Trainer card (Español)

"card_type": "TRAINER"

Trainer card (Français)

"card_type": "TRAINER"

Trainer card (Italiano)

"card_type": "TRAINER"

Trainer card (português brasileiro)

"card_type": "TRAINER"

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).

Item card, English

"subtype": "ITEM"

Item card, French

"subtype": "ITEM"

Item card, Spanish

"subtype": "ITEM"

Item card, Italian

"subtype": "ITEM"

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).

Supporter card, English

"subtype": "SUPPORTER"

Supporter card, German

"subtype": "SUPPORTER"

Supporter card, Italian

"subtype": "SUPPORTER"

Supporter card, Spanish

"subtype": "SUPPORTER"

Supporter card, Portuguese

"subtype": "SUPPORTER"

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).

Stadium card, English

"subtype": "STADIUM"

Stadium card, French

"subtype": "STADIUM"

Stadium card, Italian

"subtype": "STADIUM"

Stadium card, German

"subtype": "STADIUM"

Stadium card, Spanish

"subtype": "STADIUM"

Stadium card, Portuguese

"subtype": "STADIUM"

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).

Pokémon Tool card, English

"subtype": "TOOL"

Pokémon Tool card, French

"subtype": "TOOL"

Pokémon Tool card, Italian

"subtype": "TOOL"

Pokémon Tool card, German

"subtype": "TOOL"

Pokémon Tool card, Spanish

"subtype": "TOOL"

Pokémon Tool card, Portuguese

"subtype": "TOOL"

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).

Basic Energy card, English

"subtype": "BASIC"

Basic Energy card, French

"subtype": "BASIC"

Basic Energy card, German

"subtype": "BASIC"

Basic Energy card, Italian

"subtype": "BASIC"

Basic Energy card, Spanish

"subtype": "BASIC"

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).

Special Energy card, English

"subtype": "SPECIAL"

Special Energy card, French

"subtype": "SPECIAL"

Special Energy card, German

"subtype": "SPECIAL"

Special Energy card, Italian

"subtype": "SPECIAL"

Special Energy card, Spanish

"subtype": "SPECIAL"

name (i18n str, Required)

The name field contains the name of the card as written (where possible; see below for exceptions).

Pokemon Card's name field highlighted

"name": "Raichu"

Trainer Card's name field highlighted

"name": "Iono"

Energy Card's name field highlighted

"name": "Luminous Energy"

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.

Trainer Card's subtitle field highlighted

"name": "Professor's Research"

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:

  • Grass energy symbol{G}

  • Fire energy symbol{R}

  • Water energy symbol{W}

  • Lightning energy symbol{L}

  • Psychic energy symbol{P}

  • Fighting energy symbol{F}

  • Darkness energy symbol{D}

  • Metal energy symbol{M}

  • Fairy energy symbol{Y}

  • Dragon energy symbol{N}

  • Colorless energy symbol{C}

Card with an Energy symbol in its name

"name": "Basic {W} Energy"

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 Darkness energy symbol Metal energy symbol [2]

  • Official “Card Dex” PDFs (which ceased mid-BW era) also use {G|R|W|L|P|F|D|M|C} [3]

  • {N}, representing Dragon energy symbol 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”.

Mimikyu ex

"name": "Mimikyu ex"

Arcanine ex

There is currently no difference between the two “ex” symbols.
"name": "Arcanine ex"

Glurak-ex

Localization rules for each language are followed.
"name": "Glurak-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:

English:
“Arcanine ex” [8]
Español:
“Arcanine ex” [9]
Deutsch:
“Arkani-ex” [10]
Italiano:
“Arcanine-ex” [11]
Français:
“Arcanin-ex” [12]
português brasileiro:
“Arcanine ex” [13]
日本語:
“ウインディex” [14]

Gender symbols

Cards with ♀ or ♂ in the title use the UTF-8 characters for those symbols. The Emoji selector is not used.

Nidoran♂

"name": "Nidoran♂"
Using JSON unicode escapes, the following is equivalent:
"name": "Nidoran\u2642"

Nidoran♀

"name": "Nidoran♀"
Using JSON unicode escapes, the following is equivalent:
"name": "Nidoran\u2640"

Note

Canonically, there is no space in “Nidoran♀” nor “Nidoran♂”, in English [15][16], French [17][18], German [19][20], Italian [21][22], Spanish [23][24], or Portuguese [25][26].

See also: https://handy.trainingcourt.com/pokedex-names/

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.

Paldean Tauros

"name": "Paldean Tauros"

Paldea-Felino

"name": "Paldea-Felino"

Clodsire de Paldea

"name": "Clodsire de Paldea"

Clodsire di Paldea-ex

"name": "Clodsire di Paldea-ex"

Some Trainer cards have a prefix that is similarly typeset; those prefixes are also part of the card name and are not marked up.

Antique Helix Fossil

"name": "Antique Helix Fossil"

Fósil Domo Antiguo

"name": "Fósil Domo Antiguo"

Antiker Altbernstein

"name": "Antiker Altbernstein"

Fossile Dôme Ancien

"name": "Fossile Dôme Ancien"

Vecchio Helixfossile

"name": "Vecchio Helixfossile"

Ambar Velho Arcaico

"name": "Ambar Velho Arcaico"

Some cards have a suffix that is also considered to be part of the name. “Pikachu with Grey Felt Hat” is the prime example.

Pikachu with Grey Felt Hat

"name": "Pikachu with Grey Felt Hat"

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.

Boss's Orders (Ghetsis)

"subtitle": "Ghetsis"

Forschung des Professors (Prof. Antiqua)

"subtitle": "Prof. Antiqua"

Investigación de Professores (Profesor Turo)

"subtitle": "Profesor Turo"

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.

MEW_EN Bulbasaur 001/165

"text": "Illus. Yuu Nishida"

MEW_IT Charizard-ex 006/165

"text": "Ill. PLANETA Mochizuki"

MEW_DE Pikachu 173/165

"text": "Illustr. Hiroyuki Yamamoto"

MEW_ES Ayuda de Dalia 195/165

"text": "Ilus. Fumie Kittaka"

MEW_PT Convite da Érica 203/165

"text": "Ilust. Cona Nitanda"

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.

SVI_EN Potion 188/198

"list": ["Ayaka Yoshida"]

PAL_IT Recupero di Energia Plus 277/193

"list": ["Studio Bora Inc."]

OBF_DE Tauboss-ex 225/197

"list": ["Jerky"]

PAL_ES Tinkaton ex 240/193

"list": ["takuyoa"]

PAL_PT Mimikyu 097/193

"list": ["Kagemaru Himeno"]

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.

SVP_EN Cleffa 037

"regulation_mark": "G"

SVP_ES Sprigatito ex 087

"regulation_mark": "H"

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.

SVI_EN Pachirisu 068/198

"set_icon": "SVI_EN"

PAL_FR Dedenne-ex 093/193

"set_icon": "PAL_FR"

OBF_IT Cleffa 202/197

"set_icon": "OBF_IT"

MEW_DE Bisaflor-ex 198/165

"set_icon": "MEW_DE"

SVP_ES Pikachu 027

"set_icon": "SVP_ES"

SVE_PT Energia {F} Básica

"set_icon": "SVE_PT"

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.

MEW_EN Pikachu 025/165

"full": "025/165"

SWSHP Pikachu V SWSH285

"full": "SWSH285"

LOR Pikachu TG05/TG30

"full": "TG05/TG30"

SVE Basic {L} Energy

"full": "004"

collector_number.numerator (i18n str, Required)

The first portion of the collector number, excluding the number of non-secret cards in the set.

MEW_EN Pikachu 025/165

"numerator": "025"

SWSHP Pikachu V SWSH285

"numerator": "SWSH285"

LOR Pikachu TG05/TG30

"numerator": "TG05"

SVE Basic {L} Energy

"numerator": "004"

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.

MEW_EN Pikachu 025/165

"denominator": "165"

SWSHP Pikachu V SWSH285

"denominator": null

LOR Pikachu TG05/TG30

"denominator": "TG30"

SVE Basic {L} Energy

"denominator": null

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.

MEW_EN Pikachu 025/165

"numeric": 25

SWSHP Pikachu V SWSH285

"numeric": 285

LOR Pikachu TG05/TG30

"numeric": 5

SVE Basic {L} Energy

"numeric": 4

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 Black Star Promo symbol icon

  • COMMON

  • 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:

  1. The Card Checklist PDF published on pokemon.com or tcg.pokemon.com, which offers a rarity key at the bottom of the page, or

  2. 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:

Rarity key, English SV3.5

English Rarity key, SV1-onwards. [27]

Rarity key, French SV3.5

French Rarity key, SV1-onwards. [28]

Rarity key, Italian SV1

Italian Rarity key, SV1-onwards. [29]

Rarity key, German SV1

German Rarity key, SV1-onwards. [30]

Rarity key, Spanish SV1

Spanish Rarity key, SV1-onwards. [31]

Rarity key, Portuguese SV1

Portuguese Rarity key, SV1-onwards. [32]

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

PROMO

Black Star Promo symbol

COMMON

Common rarity symbol

UNCOMMON

Uncommon rarity symbol

RARE

Rare rarity symbol

DOUBLE_RARE

Double Rare rarity symbol

ILLUSTRATION_RARE

Illustration Rare rarity symbol

ULTRA_RARE

Ultra Rare rarity symbol

SPECIAL_ILLUSTRATION_RARE

Special Illustration Rare rarity symbol

HYPER_RARE

Hyper Rare rarity symbol

SHINY_RARE

Shiny Rare rarity symbol

SHINY_ULTRA_RARE

Shiny Ultra Rare rarity symbol

ACE_SPEC_RARE

Ace Spec Rare rarity 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:

  1. Wizards of the Coast oracle text

  2. Physical checklists packaged with theme deck products (Through end of WOTC)

  3. Pokémon USA Card Dex PDFs (through mid-BW)

  4. 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

BLACK_STAR_PROMO

Black Star Promo symbol

SOLID_CIRCLE

Common rarity symbol

SOLID_DIAMOND

Uncommon rarity symbol

SOLID_STAR

Rare rarity symbol

TWO_BLACK_STARS

Double Rare rarity symbol

GOLD_STAR

Illustration Rare rarity symbol

TWO_SILVER_STARS

Ultra Rare rarity symbol

TWO_GOLD_STARS

Special Illustration Rare rarity symbol

THREE_GOLD_STARS

Hyper Rare rarity symbol

SHINY_STAR

Shiny Rare rarity symbol

TWO_SHINY_STARS

Shiny Ultra Rare rarity symbol

PINK_STAR

Ace Spec Rare rarity 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.

SVI Pawmi 073/198

"icon": "SOLID_CIRCLE"

SVI Grimer 126/198

"icon": "SOLID_CIRCLE"

Note

SOLID_CIRCLE Common rarity symbol, SOLID_DIAMOND Uncommon rarity symbol and SOLID_STAR Rare rarity symbol are printed in black ink, except on Darkness-type cards where white ink is used for contrast reasons instead. TWO_BLACK_STARS Double Rare rarity symbol are always printed in black, but use a white outline when necessary.

"icon": "SOLID_DIAMOND"

"icon": "SOLID_DIAMOND"

"icon": "SOLID_STAR"

"icon": "SOLID_STAR"

"icon": "TWO_BLACK_STARS"

"icon": "GOLD_STAR"

"icon": "TWO_SILVER_STARS"

"icon": "TWO_GOLD_STARS"

"icon": "THREE_GOLD_STARS"

"icon": "SHINY_STAR"

"icon": "TWO_SHINY_STARS"

"icon": "PINK_STAR"

tags (enum str[], Optional)

An unordered array of enumeration strings that describe miscellaneous attributes of the card.

There are two categories of tags; “markers” and “attributes”. They are not distinguished in data, but are separated here for clarity.

Markers

Marker-style tags represent a graphical design element on the card. The enumerations used to represent them are simply upper-cased representations of their English text.

ANCIENT

This is an “Ancient” Paradox Pokémon/Trainer. The card says “ANCIENT” (or the localized equivalent) on the right-hand side of the art window.

"tags": ["ANCIENT"]

"tags": ["ANCIENT", "EX_LOWER"]

"tags": ["ANCIENT"]

"tags": ["ANCIENT", "TOOL"]

"tags": ["ANCIENT"]

"tags": ["ANCIENT", "EX_LOWER", "SHINY"]

FUTURE

This is a “Future” Paradox Pokémon/Trainer. The card says “FUTURE” (or the localized equivalent) on the right-hand side of the art window.

"tags": ["FUTURE"]

"tags": ["FUTURE", "EX_LOWER"]

"tags": ["FUTURE"]

"tags": ["FUTURE", "ITEM"]

"tags": ["FUTURE", "EX_LOWER"]

"tags": ["FUTURE", "EX_LOWER", "SHINY"]

ACE_SPEC

This is an ACE SPEC Trainer or Energy card. The card says “ACE SPEC” (or the localized equivalent) in bright pink lettering vertically on both the left and right side of the card.

FIXME

Add diagram when SV5 comes out.

Attributes

Attribute-style tags are potentially redundant information about a card that may or may not be represented by an explicit graphical element on the card.

These tags bend the rules for “As written” in favor of convenience.

EX_LOWER

This is a Pokémon ex. While it is sufficient to say that a Pokémon is “ex” if its name ends with “ex” and it has an “ex rule” on the card (the title and text of which can change in different localizations), localization may make this determination tricky.

As a convenience, the EX_LOWER tag is used to unambiguously specify that this is a Pokémon ex.

"tags": ["EX_LOWER"]

TERA

This is a Tera Pokémon ex. While it is sufficient to say that a Pokémon is “Tera” if it has the Tera effect (the title and text of which can change in different localizations), localization may make this determination difficult and this tag is provided as a convenience.

PAL EN Dedenne ex
PAL DE Dedenne-ex

"tags": ["TERA", "EX_LOWER"]

ITEM

This card is— or was at one point considered to be— an Item card. Due to the changing categorization of Item cards over the years, this tag is provided as a meta-classification convenience.

When Item cards were introduced to the international card game for the Black & White era (Late in the 4th generation in Japan), special errata were published that explicitly reclassified old Trainer cards as Items [33]. This errata applies to all “Trainer” cards from the first through fourth generations of cards that are not otherwise explicitly labeled as Supporters or Stadiums.

Compendium rulings have been issued that explicitly clarify that all Trainer cards that are not Supporters or Stadiums count as “Item” cards from the context of modern card phrasings [34]. This even applies to Trainer cards from Generations 1-4 subcategorized as “Pokemon Tool”, “Technical Machine”, “Rocket’s Secret Machine”, “Rocket’s Secret Robot” and “Goldenrod Game Corner”.

For the Unlimited format, there are further rulings both in the Tournament Rules Handbook [35] and in the Compendium [36] that clarify that any card whose text is changed in newer printings must be treated as if it were the newer print, effective immediately. Many of these older Trainer cards have been reprinted explicitly as Item cards, cementing their status as Item cards.

Later, in the Scarlet & Violet era, Pokémon Tool cards— which had been previously regarded as both “Item” and “Pokémon Tool” cards— were reclassified solely as “Pokémon Tool”, losing their Item status as of the ninth generation of cards. [37]

This particular tag covers all cards ever considered to be Items. It is the broadest possible meaning of the concept of “Item”.

Note

For tighter searches on specific kinds of Item cards, it’s recommended that you use the card subtype field or the G9_ITEM tag depending on the desired semantics of the search.

The ITEM tag is set on:

  • Any TRAINER card from the first three generations of the game, except for those subtyped as “Stadium”, “Stadium Card” or “Supporter”.

  • Any TRAINER card regardless of the subtype from the fourth generation of cards. STADIUM and SUPPORTER cards from this era did not say “TRAINER” at all, and were exempt from the B&W reclassification.

  • “Goldenrod Game Corner”, “Rocket’s Secret Machine”, “Rocket’s Secret Robot”, “Pokémon Tool”, and “Technical Machine” cards from the first four generations; these are “TRAINER” cards covered by the above errata and rulings.

  • Any TRAINER - ITEM type card from the fifth generation of cards onward, including those from the ninth generation. This includes certain iterations of “Pokémon Tool” cards from the fifth through eighth generation, as explained both above and below.

The ITEM tag is not set on:

  • Any TRAINER - TOOL type card from the ninth generation of cards. These cards were never at any point considered to be Items.

G9_ITEM

This is an ITEM card as understood in the 9th generation of cards (Scarlet & Violet) and presumably onwards.

When Scarlet & Violet cards were released, an errata was announced that revoked the “Item” status of Pokémon Tools in favor of reclassifying them explicitly as their own major category of Trainer cards. [38]

This tag, therefore, applies to every ITEM tag card except those also tagged as a TOOL, see below.

RFC

Given that G9_ITEM is just set(ITEM) - set(TOOL), do we even need this at all? My belief is that having it explicitly laid out like this in the data helps clue in the user that there’s something “fishy” at hand that may need to be carefully considered for the application being developed.

TOOL

This is a Pokémon Tool card.

When Scarlet & Violet cards were released, an errata was announced that revoked the “Item” status of Pokémon Tools in favor of reclassifying them explicitly as their own major category of Trainer cards. [39]

Owing to the fact that Pokémon Tool cards did not have their own subcategory from the fifth through the eighth generation of cards (where they were primarily categorized as Item cards), this tag provides a meta-classification convenience to identify all Pokémon Tool cards regardless of their actual stated subtype.

It is set on:

  • TRAINER cards that specify “Pokémon Tool” as a subtype in the 2nd through 4th generation of cards. (These cards will also be tagged as ITEM, but not G9_ITEM.)

  • TRAINER - ITEM cards that feature the “Pokémon Tool” rule text in the 5th through 8th generation of cards. (These cards will also be tagged as ITEM, but not G9_ITEM.)

  • TRAINER - “Pokémon Tool” cards from the 9th generation of cards (and presumably subsequent generations). (These cards are not tagged as ITEM nor G9_ITEM.)

PLAYABLE_TRAINER

This is a TRAINER card that can be played as a Pokémon under certain conditions. It has HP and may have attacks/abilities unlike most normal Trainer cards. Note that some trainer cards like Technical Machines may provide attacks without explicitly being playable.

SHINY

This card depicts a Shiny Pokémon. Most Shiny Pokémon cards published since Scarlet & Violet feature either the Shiny Rare rarity symbol or Shiny Ultra Rare rarity symbol rarity mark, but not all of them do. For example, Paldean Fates Mew ex 232/091 features a Shiny Mew, but has Special Illustration Rare rarity symbol rarity.

This tag is purely for convenience, owing to the many ways Shiny Pokémon have been presented over the years.

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 Double Rare rarity symbol, Illustration Rare rarity symbol and Ultra Rare rarity symbol 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 than SV_HOLO does. The defining characteristic is the addition of a prismatic “glitter” effect not present in the SV_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 Double Rare rarity symbol, Tera Pokémon ex Ultra Rare rarity symbol, Special Illustration Rare rarity symbol and Hyper Rare rarity symbol 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 Ace Spec Rare rarity symbol 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 Double Rare rarity symbol, Ultra Rare rarity symbol, Special Illustration Rare rarity symbol and Hyper Rare rarity symbol 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 Double Rare rarity symbol 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.

_images/pokemon_stage_basic_en.png
_images/pokemon_stage_basic_de.png
_images/pokemon_stage_basic_es.png
_images/pokemon_stage_basic_fr.png

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.

_images/pokemon_stage_stage1_en.png
_images/pokemon_stage_stage1_fr.png
_images/pokemon_stage_stage1_it.png
_images/pokemon_stage_stage1_de.png
_images/pokemon_stage_stage1_ptbr.png

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.

_images/pokemon_stage_stage2_en.png
_images/pokemon_stage_stage2_fr.png
_images/pokemon_stage_stage2_es.png
_images/pokemon_stage_stage2_de.png
_images/pokemon_stage_stage2_ptbr.png

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”

SVI Pawmo 075/198

"stage_text": "Evolves from Pawmi"

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.

Pikachu

Pikachu’s hp is 70.

Pamomamo

Pamomamo’s hp is 130.

Mew ex

Mew ex’s hp is 180.

Mélodelfe-ex

Mélodelfe-ex’s hp is 260.

Antique Helix Fossil

Antique Helix Fossil’s hp is 60.

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 energy symbolGRASS

  • Fire energy symbolFIRE

  • Water energy symbolWATER

  • Lightning energy symbolLIGHTNING

  • Psychic energy symbolPSYCHIC

  • Fighting energy symbolFIGHTING

  • Darkness energy symbolDARKNESS

  • Metal energy symbolMETAL

  • Fairy energy symbolFAIRY

  • Dragon energy symbolDRAGON

  • Colorless energy symbolCOLORLESS

Wartortle

Wartortle’s types field is [ "WATER" ].

This field is also defined for ENERGY - BASIC cards:

Basic {D} Energy

Basic Darkness energy symbol Energy’s types field is [ "DARKNESS" ].

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 Common rarity symbol, Uncommon rarity symbol, Rare rarity symbol and Illustration Rare rarity symbol; and sometimes Hyper Rare rarity symbol and Black Star Promo symbol cards.)

Other fields

images

FIXME

TODO

ext

FIXME

TODO

Appendix A

FIXME

TODO. There will be a localization table here.

References