Schema specification

If you want to write a scraper that emits Retronian GameDB-compatible JSON, this page is the contract. The authoritative machine-readable definition lives at schema/game.schema.json (JSON Schema Draft 2020-12).

File layout

One JSON file per game, stored at:

data/games/{platform}/{id}.json

The id field inside the file must equal the file name without the .json extension. The platform field must equal the directory name.

Top-level fields

Field	Type	Required	Description
`id`	string	yes	Slug, lowercase ASCII with hyphens. Matches the file name.
`platform`	string (enum)	yes	Platform identifier. See the home page for the current list.
`category`	string (enum)	no	`main_game` (default), `dlc`, `expansion`, `bundle`, `remake`, `remaster`, `port`, `compilation`.
`first_release_date`	string	no	ISO 8601 date or partial date (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`).
`titles`	array	yes	At least one entry. See below.
`descriptions`	array	no	English and Japanese descriptions, see below.
`developers`	string[]	no	Developer slugs.
`publishers`	string[]	no	Publisher slugs.
`genres`	string[]	no	Genre slugs.
`external_ids`	object	no	Cross-references to other databases.

Title objects (the core)

Every entry in titles[] has these fields:

Field	Type	Required	Description
`text`	string	yes	The title as it appears.
`lang`	string	yes	Public API language: `en` or `ja`.
`script`	string (enum)	yes	ISO 15924 script code. See the table below.
`region`	string	no	ISO 3166-1 alpha-2 country code, lowercase.
`form`	string (enum)	no	`official`, `boxart`, `ingame_logo`, `manual`, `romaji_transliteration`, `alternate`.
`source`	string (enum)	no	`wikidata`, `igdb`, `mobygames`, `screenscraper`, `no_intro`, `community`, `manual`.
`verified`	boolean	no	Whether the entry has been confirmed against a primary source.

The `script` field (ISO 15924)

This is what makes Retronian GameDB different from every other game DB. The language tag ja alone cannot tell katakana-only titles apart from kanji-mixed titles, but in retro game metadata that distinction often matters. The valid values are:

Code	Meaning	Example
`Jpan`	Japanese with kanji and kana mixed	星のカービィ
`Hira`	Japanese, hiragana only	くにおくん
`Kana`	Japanese, katakana only	スーパーマリオブラザーズ
`Latn`	Latin script	Kirby's Dream Land
`Zyyy`	Undetermined	Use as last resort.

Description objects

Each public descriptions[] entry has text, lang (en or ja), and an optional source.

External IDs

external_ids is an object mapping a source name to its identifier. Recognized keys:

wikidata — Wikidata QID, e.g. "Q1064715"
igdb — IGDB game ID (integer)
mobygames — MobyGames game ID (integer)
screenscraper — ScreenScraper.fr jeu ID (integer)
thegamesdb — TheGamesDB game ID (integer)
openvgdb — OpenVGDB release ID (integer)

Example

{
  "id": "hoshi-no-kirby",
  "platform": "gb",
  "category": "main_game",
  "first_release_date": "1992-04-27",
  "titles": [
    {
      "text": "星のカービィ",
      "lang": "ja",
      "script": "Jpan",
      "region": "jp",
      "form": "boxart",
      "source": "wikidata",
      "verified": true
    },
    {
      "text": "Kirby's Dream Land",
      "lang": "en",
      "script": "Latn",
      "region": "us",
      "form": "official",
      "source": "wikidata",
      "verified": true
    }
  ],
  "developers": ["hal-laboratory"],
  "publishers": ["nintendo"],
  "genres": ["platformer"],
  "external_ids": {
    "wikidata": "Q1064715",
    "igdb": 1083
  }
}

API endpoints

The static API mirrors the on-disk layout:

/api/v1/platforms.json — list of platforms with counts
/api/v1/stats.json — aggregate statistics
/api/v1/{platform}.json — all games on a platform, as a JSON array
/api/v1/games/{platform}/{id}.json — a single game entry
/api/v1/rom-index/{platform}.json — ROM lookup indexes by hash, exact filename, exact No-Intro name, and stripped base name. The included match policy marks exact filename matches as processable even when hashes differ.
/search-index/all.json — minimal index for client-side search

Everything is cache-friendly static JSON. There is no rate limiting and no authentication.