Topic: IFData

Format of the gamejson.txt file

The current name of my IFData file is gamejson.txt. It uses UTF-8 character encoding with a three-byte BOM at the beginning of the file. The basic structure of the file is JSON, a.k.a. JavaScript Object Notation. I edit the thing with Notepad. Really.

(Historical note: When I first started collecting data about IF games, the data was only about games and there was just one record line per game. Delimited with or-bars. And it was all in ASCII. The original purpose of the file was to help me create index pages that linked to my walkthroughs. It was already getting rather unwieldy when I finally discovered JSON and switched over as soon as possible.)

The main data object has the following key-value pairs:

{
  "languages":[ array of language records ],
  "urlabbrs":[ array of abbreviation-definition records ],
  "lists":[ array of gamelist-definition records ],
  "tags-info":{ the tags-info object },
  "authsystems":{ hash of authoring-system-definition records },
  "extensions":{ hash of extension-definition records },
  "events":{ hash of event-definition records },
  "people":{ hash of person-definition records },
  "games":{ hash of game-definition records }
}

languages

The "languages" field takes an array value, an array of language records. It's used for listing which human languages are used by the games.

Language records are very simple. They have two-fields each, both required:

  {"lang": language-code, "en": English-name }

For example:

  {"lang":"nl", "en":"Dutch"}

urlabbrs

The "urlabbrs" field takes an array value, an array of abbreviation-definition records. It's used for defining abbreviations that I use at the beginning of some URLs. This bit of nonsense lets me shorten some URLs and lets me associate some other information with the URLs. This may be more trouble than it's worth, but I do it anyway.

Abbreviation-definition records are short, from two to four fields each:

  {"as": abbreviation, "url": partial-url, "at": site-name, "by": site-owner}

For example:

  {"as":"[dsw]", "url":"www.plover.net/~davidw/", "by":"David Welbourn"}

lists

The "lists" field takes an array value, an array of gamelist-definition records. This was invented to help me generate various game lists for IFWiki; see Category:Game lists.

Gamelist-definition records look like this:

  {"h1": shortname, "ifwiki": IFWiki-article-name,
   "head": header-text, "foot": footer-text,
   "h2s": { hash of subsection records }
  }

lists / h2s

The "h2s" field takes a hash value, a hash of subsection records. They look like this:

   "key": {
      "name": replacement-name, "sort": sort-string,
      "head": header-text, "foot": footer-text
   }

tags-info

The "tags-info" field takes a hash value of tag-list records. I use a lot of tags elsewhere in the datafile, so I look at this field when I need to remember what tags I defined and what they all mean. None of my programs makes any direct use of this.

There's only three subfields: events/tags, extensions/tags, and games/tags. They're all very similar; events/tags is about tags in event-definition records, extensions/tags is about tags in extension-definition records, and games/tags is about tags in game-definition records.

  "tags-info":{
    "events/tags":[ array of tag-definition records ],
    "extensions/tags":[ array of tag-definition records ],
    "games/tags":[ array of tag-definition records ]
  }

A tag-definition record is a simple two-field thing; both fields are required string values:

  {"tag": tag-name, "meaning": tag-description}

For example, the "cover" tag for a game is defined thusly:

  {"tag":"cover", "meaning":"The game has cover art."}

authsystems

The "authsystems" field takes a hash value of authoring-system-definition records. I've collected very little information for this section, but sometimes I come across a snippet of info about an authoring system that I want to remember later, so here's where it goes. An authoring-system definition record looks like this:

  "key":{
    "by": author,
    "ifwiki": IFWiki-article-name,
    "links":[ array of link-records ],
    "notes":[ array of note-records ]
  }

extensions

The "extensions" field takes a hash value of extension-definiton records. Again, I've collected very little information for this section as yet. An extension-definition record looks like this:

  "key":{
    "by": author,
    "tags":[ array of tags ],
    "links":[ array of link-records ]
  }

events

The "events" field takes a hash value of event-definition records. They describe IF competitions, mostly, but can include other events related to interactive fiction. An event-definition record looks like this:

  "key":{
    "ifwiki": IFWiki-article-name,
    "sort": sort-value,
    "organizers":[ array of person-ref records ],
    "dates":[ array of schedule-event records ],
    "links":[ array of link-records ],
    "reviews":[ array of link-records ],
    "notes":[ array of note-records ],
    "year": calendar-year,
    "of": number-of-entries,
    "h1": event-category,
    "h2": event-subcategory,
    "tags":[ array of tag-names ]
  }

people

The "people" field takes a hash of person-definition records. Basically, if I want to remember something about IF people other than what events they organized or what games they wrote, it goes here. The info in this section is still rather sparse. The person-definition record looks like this:

  "key":{
    "birth": birthdate,
    "nicks":[ array of nicknames ],
    "links":[ array of link-records ],
    "notes":[ array of note-records ]
  }

games

The "games" field takes a hash of game-definition records. This is the bulk of the IFData file, by far, and also the most complicated. The "titles" and "year" fields are required; all other fields are optional. The game-definition looks like this:

  "key":{
    "titles":[ array of titles ],
    "ifwiki": IFWiki-article-name,
    "authors":[ array of person-ref records ],
    "adaptors":[ array of person-ref records ],
    "contribs":[ array of person-ref records ],
    "publishers":[ array of person-ref records ],
    "testers":[ array of person-ref records ],
    "genres":[ array of genre-names ],
    "license": licence-name,
    "color": color-comment,
    "graphics": graphics-comment,
    "sound": sound-comment,
    "cruelty": cruelty-name,
    "versions":[ array of version-records ],
    "notes":[ array of note-records ],
    "seealso":[ array of link-records ],
    "reviews":[ array of link-records ],
    "spoilers":[ array of link-records ],
    "lists":[ array of list-ref records ],
    "sline":{ status-line record },
    "exts":[ array of extension-ref records ],
    "tags":[ list of tag-names ],
    "ifro": ifro-code,
    "ifratings": ifratings-code,
    "baf": baf-code,
    "year": calendar-year,
    "xayear": calendar-year,
    "tuid": tuid,
    "series": series-name,
    "seriesplace": series-place
  }

Yeah, I know. That's a lot of fields. Here's the breakdown:

games / versions

Version records are similar to game records in that they share a lot of the same fields. Where fields overlap, version-records inherit their game's field values and can override them. For example, a version's "title" field overrides the game's "titles" field, so a version can have a different title than usual.

It is expected that version records are listed in release date order, from earliest version to latest version.

Version records look like this:

  { "vername": version-name,
    "title": title,
    "headline": headline,
    "authors":[ array of person-ref records ],
    "adaptors":[ array of person-ref records ],
    "contribs":[ array of person-ref records ],
    "publishers":[ array of person-ref records ],
    "testers":[ array of person-ref records ],
    "authsys": authoring-system,
    "platform": platform,
    "lang": language-code,
    "reldate": release-date,
    "relline": release-line,
    "license": licence-name,
    "color": color-comment,
    "graphics": graphics-comment,
    "sound": sound-comment,
    "nrooms": number-of-rooms,
    "ifids":[ array of IFIDs ],
    "tuid": tuid,
    "events":[ array of event-ref records ],
    "notes":[ array of note-records ],
    "downloads":[ array of link-records ]
  }

games / versions / events

Event-ref records specify which events a version participated in, and how, and what awards (if any) it earned. An event-ref record has two fields: "event" and "honors", both of which are required:

  { "event": event-name, "honors":[ array of honor-records ] }

The event-name should be specified exactly the same as the key used for that event's event-definition record.

Honor-records have this format:

  { "cat": category, "place": number, "tie": true, "of": number, "rank": rank, "nb": comment }

Multi-use records

person-ref records

TODO

TODO

note-records

TODO