Schema specification

If you want to write a scraper that emits Native Game DB-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	Multilingual 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	ISO 639-1 language code: `ja`, `en`, `ko`, `zh`, `es`, `fr`, `de`, `it`, etc.
`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 Native Game DB 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	スーパーマリオブラザーズ
`Hang`	Korean hangul	별의 커비
`Hans`	Chinese, simplified	星之卡比
`Hant`	Chinese, traditional	星之卡比
`Latn`	Latin script	Kirby's Dream Land
`Cyrl`	Cyrillic	Кирби
`Arab`, `Hebr`, `Thai`	Arabic, Hebrew, Thai	—
`Zyyy`	Undetermined	Use as last resort.

Description objects

Each entry in descriptions[] has text (string), lang (ISO 639-1), and an optional source (same enum as titles).

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
/search-index/all.json — minimal index for client-side search

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