Key & Compass Blog

February 9, 2016

Intro to my JSON datafile

Filed under: Interactive Fiction — davidwelbourn @ 5:22 pm

This post will be about my IF datafile, now in glorious JSON format. The top level of my datafile looks like this:

  "languages":[ ... ],
  "urlabbrs":[ ... ],
  "lists":[ ... ],
  "tags-info":{ ... },
  "authsystems":{ ... },
  "extensions":{ ... },
  "events":{ ... },
  "people":{ ... },
  "games":{ ... }

And here’s a brief description of each of these top-level sections:

  • The languages section is very simple and is mostly there to remind me what each 2-letter language code means, e.g. "en" means English, "fr" means French, and so on. Sometimes I forget what the code for Swedish is, y’know?
  • The urlabbrs section is for my list of URL abbreviations, for example, I’ll use [A] at the beginning of an URL to mean "". I was still worried about file size when I creating my datafile, and I thought the use of these abbreviations might reduce bloat. I’m now thinking that this is an added complexity I ought to do away with someday, if I ever want to make my datafile public in any way.
  • The lists section is for describing lists of works of IF, such as Holiday-themed works (where I want to subdivide into particular holidays), or works that take place in the United States (where I want to subdivide into individual States).
  • The tags-info section is more comments to myself, reminding me what tags I use in my data, in what contexts I use them, and what do they mean.
  • The authsystems section is for recording info about authoring systems. But it’s a very new section and doesn’t have much info in it yet.
  • The extensions section is for recording info about library extensions, particularly used by Inform 6 or Inform 7 authors. It’s also a new section.
  • The events section is for recording info about events, mostly competitions. It’s… okay, but it could be better.
  • The people section is for recording info about people, mostly authors of IF. This is a mostly threadbare section where I can record a link that I want to associate with someone, like their blog.
  • The games section is for recording info about works of IF, and it’s easily the largest and most complex section of all of them. When I have time to update my datafile, I’m mostly adding to this section, and sometimes the events section, and not much else. I want to rename this section to works; I just haven’t done that yet since I’d have to update all my programs that read the datafile as well.

I’ll assume if you’ve read this far, you’re mostly interested in the games section, so here’s the structure of a game entry:

  "titles":[ ... ], "ifwiki":"",
  "authors":[ ... ], "publishers":[ ... ],
  "contribs":[ ... ], "testers":[ ... ],
  "genres":[ ... ], "license":"",
  "color":"", "graphics":"", "sound":"", "cruelty":"",
  "versions":[ ... ],
  "sline":{ ... }, "exts":[ ... ], "lists":[ ... ],
  "seealso":[ ... ], "reviews":[ ... ], "spoilers":[ ... ],
  "notes":[ ... ],
  "year":"", "xayear":"",
  "series":"", "seriesplace":integer,
  "baf":"", "tuid":"", "ifratings":"", "ifro":"", "tags":[ ... ]

Fortunately, few of these fields are required; at minimum, I want the game-id, the title, and the year. Here’s what these fields are for:

  • The game-id is a unique short ID that I make up for each game. The full rules are complicated, but it’s usually the first five letters of the game’s title (not counting words like “the”, “a”, “an”) put into lowercase followed by the last two digits of the game’s original publication year.
  • The titles field is a list of the game’s titles, where the main title is first. What counts as the “main” title can be a bit of a judgment call.
  • The ifwiki field simply tells me what the game’s article name is on IFWiki, if different than the main title.
  • The authors field is a list of the game’s authors (including writers and programmers). These are not simple strings of the authors’ names, but name-records.
  • The publishers field is a list of the game’s publishers (including distributors). Again, more name-records.
  • The contribs field is a list of the game’s contributors (including illustrators, musicians, voice actors, etc.)
  • The testers field is a list of the game’s testers, usually beta-testers.
  • The genres field is a list of the game’s genres, which I try to standardize even though the genre info is coming from Baf’s Guide, IFWiki, and IFDB, each of which handles genres different ways.
  • The license field is a simple string naming the game’s license.
  • The color field attempts to answer the question, “Is text-colour usage in the game significant?”
  • The graphics field attempts to answer the question, “Are there graphics in this game, and does a player need to be able to see them?”
  • The sound field attempts to answer the question, “Is there music or sound effects in this game, and does a player need to be able to hear them?”
  • The cruelty field records where the game is rated under the Cruelty Scale.
  • The versions field is complicated; there’s a version-record for each version of the game. That’s where authoring system, platform, language, IFID, etc. is recorded.
  • The sline field describes the status line layout.
  • The exts field lists any library extensions that the game is known to use.
  • The lists field lists which game lists the game belongs to and how.
  • The seealso field lists links to webpages about the game, not including reviews or spoilers. I don’t know if I can justify why it isn’t called links.
  • The reviews field lists links to reviews of the game.
  • The spoilers field lists links to spoilers about the game (e.g.: walkthroughs, hints, maps, transcripts).
  • The notes field lists other things I want to note about the game that aren’t covered in other fields. There’s a wide variety of note types.
  • The year field states for the game’s original publication year.
  • The xayear field states for which year this game is eligible for an XYZZY Award.
  • The series field states which game series this game belongs to. I’m badly assuming a game can only belong to one series, so this needs to change.
  • The seriesplace field is an integer stating where in the series this game is; for example: 2 means it’s the second game in the series.
  • The baf field is the Baf’s Guide number that the game had on that site.
  • The tuid field is the TUID of the game that IFDB uses. Er, for the main version of the game.
  • The ifratings field is old IF Ratings number that the game had on that site.
  • The ifro field is the IF Review Organization number that the game has on that site.
  • The tags field is a list of tags like "cover" (meaning that the game has cover art) or "no-testers" (meaning that the game doesn’t credit any testers).

That’s probably enough to chew on for one post. Someday, I really need to make a webpage documenting the whole thing.

Oh, and why am I collecting all this info in the first place? Originally, it was to showcase my walkthroughs, but as I helping out with the XYZZY Awards and administrating IFWiki, I really did need at least some of this info collected somewhere. And I sensed that no one else was recording quite everything that I felt needed to be recorded. And I felt a more detailed approach would be more helpful down the line.

Unfortunately, I can’t claim my datafile is in any way superior; my records are quite spotty in places because I’ve been doing this mostly manually to date. Automating the process is something I  <em>really</em> want to do — if I can find the time for it.

1 Comment »

  1. By the way, if we’re talking automation, there is a way to make MediaWiki to load a template when you’re creating a page:
    It looks like a menu with options: “Game page”, “Engine page”, “Comp page” and so on.

    Comment by Oreolek — February 9, 2016 @ 8:58 pm

RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Create a free website or blog at

%d bloggers like this: