.recomp.json

A small file at the root of a recomp or decomp repository that says what the project is: which game, from which release, how far along, who to talk to. The project writes it once. Any site, launcher or list can read it, and nobody has to guess from a README.

Version 1, draft. Read today by recomp.board. JSON Schema: recomp.fyi/schema/v1.json. Comments and proposals: open an issue.

Why a file in the repository

Lists of recomps and decomps are built by reading repositories from the outside, and they get titles, platforms and statuses wrong. Whoever can commit to a repository wrote this file, so it outranks any listing made about the project by someone else. There is nothing to register and no account to create: the file is read from wherever the code lives (GitHub, GitLab, Codeberg, Gitea, Forgejo, a server of your own).

The file

Named .recomp.json, at the root of the repository’s default branch, UTF-8 JSON, one object. Every field is optional: a field left out means the project has not said, never “none”. A list needs game, system and type to add a project it doesn’t know yet.

The file follows the project. When the status changes (playable, released, paused), or a maintainer joins or leaves, edit the file: every list that reads it updates. A stale file is worse than none, since it says something with the project’s own authority.

{
  "$schema": "https://recomp.fyi/schema/v1.json",
  "game": "Wave Race 64",
  "wikidata": "Q3142278",
  "system": "N64",
  "type": "recomp",
  "original": { "region": "USA", "revision": "1.0" },
  "project": "Wave Race 64 Recompiled",
  "status": "playable",
  "targets": ["Windows", "Linux", "Steam Deck"],
  "toolchain": "N64recomp",
  "approach": "Static recompilation, RT64 renderer",
  "maintainers": [{ "name": "yourhandle", "link": "https://your-profile" }],
  "links": [{ "label": "Discord", "url": "https://discord.gg/..." }],
  "help": ["Audio timing", "Controller mapping on Linux"],
  "notes": "What works, what's next, what hurts."
}

With the $schema line, editors such as VS Code check the file and complete the field names as you type.

Fields

`game`	The game’s title as it shipped.
`wikidata`	The game’s Wikidata item, `Q` followed by digits, from the address of its page on wikidata.org. Two lists can then agree on the game without comparing titles.
`system`	The platform of the binary the project recompiles or decompiles, not where the result runs: a PS3 re-release of a Neo Geo game is PS3. One name, or a list when the project works from several. Use the common short name (N64, PS1, GameCube, Xbox 360); recomp.board’s list is a good reference.
`type`	`"recomp"`: static recompilation of the original binary. `"decomp"`: source code rebuilt from the binary. `["decomp", "recomp"]` when one repository delivers both. A native port built on a decompilation is a recomp.
`original`	The release the project works from, the one a user must own: `region`, `revision`, `serial` (the product code on the disc, cartridge or box) and `sha1` (of the file the project expects, so users can check their copy). All four optional. A list when several releases are supported.
`project`	The project’s own name.
`status`	`"exploring"` feasibility, tooling, no promises yet. `"in-progress"` actively being worked on. `"playable"` runs start to finish, rough edges remain. `"released"` a public build, still maintained. `"complete"` finished: a decomp whose source fully rebuilds the original, or a recomp with no further work planned. `"paused"` on hold. Better said than left to silence.
`targets`	Where the project’s build runs: Windows, Linux, macOS, Steam Deck, Android, a browser, the original console.
`toolchain`	The recompiler or decomp toolkit the project is built on.
`approach`	The method in one line.
`maintainers`	A list of `{ "name": "…", "link": "https://…" }`, the link optional.
`links`	A list of `{ "label": "…", "url": "https://…" }`: devlog, Discord, forum thread.
`help`	Short phrases, one per thing the project would welcome a hand with.
`tags`	Short words.
`notes`	Free text: what works, what is next.
`x-…`	Any field starting with `x-` is an extension for one reader or tool. Others ignore it.

Release tags, commit dates and download counts are not in the file: the repository host already says them, and a copy would go stale.

Never in the file

A game file, a ROM or disc image, or where to get one. The sha1 of original lets a user check a copy they own; it is not a way to find one. A reader may refuse a file that breaks this.

For sites and tools that read it

Read .recomp.json at the root of the default branch. .recomp-board.json, the file’s first name, holds the same fields: read it when the new name is absent.
Treat the file as the project’s own word on every field it sets. Never fill a field it leaves out with a guess and present it as the project’s.
Ignore fields you don’t know. A reader may shorten or drop values under its own rules, and should say which.
The content comes from someone else’s repository: cap what you read, and make links only from https addresses.
Never write to the repository.

Versions

The $schema address names the version. Within version 1, changes only add optional fields, so a version 1 reader keeps working. A change that would break a reader becomes version 2 at a new address, and schema/v1.json stays where it is.

Licence

This specification and schema/v1.json are under CC BY 4.0: use them, implement them, adapt them, and credit recomp.board. The board’s data keeps its own terms.