.recomp.json

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. A repository that holds several games describes the first in .recomp.json and each other one in its own file, .recomp-2.json up to .recomp-9.json, with the same fields.

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

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

Names

system and targets are free text, so a platform nobody listed can still be named. For the platforms below, use these spellings: two files that mean the same machine then say it the same way. A console in targets takes its system name. A reader should still expect other spellings ("PlayStation", "Nintendo 64") and read them as the same platform.

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. Next to it, .recomp-2.json up to .recomp-9.json each describe one more game in the same repository.
• 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 or widen what a field accepts ("port" as a type, a list in toolchain), each dated in the table above. 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.