**Draft**

Interactive Fiction XML metadata format

Version 1.0 (Draft) August 3, 2005 by Andrew Hunter Contents

1 Introduction 2 1.1 Who should use this format? ...... 2

2 The format 3 2.1 The root element: ifindex ...... 3 2.2 The story tag: story ...... 3 2.3 The story identification tag: identification ...... 3 2.3.1 Example ...... 4 2.3.2 Z-Code identification tag: zcode ...... 4 2.3.3 Glulx identification ...... 4 2.3.4 MD5 identification ...... 5 2.4 The metadata tags ...... 5

3 Optional modules 7 3.1 The feelies module ...... 7 3.2 The comments module ...... 7 3.3 The resources module ...... 7 3.4 The review module ...... 8

4 Parsing notes 9

5 Attaching metadata 10 5.1 To z-code games ...... 10 5.2 In filesystem metadata ...... 10 5.3 To archive sites ...... 10 5.4 To review sites ...... 10

1 1 Introduction

The original inspiration of this format is an improvement on the existing interactive fiction cataloguing system in Zoom. The original design for this used a text file with an arbitrary format, mainly designed for storing interpreter settings. It was also capable of storing some limited metadata along with stories, in particular a full title for the story, which was used in the interpreter’s title bar, and also to provide a simple menu of stories. This format is intended to provide a more advanced indexing system for stories. It deals specifically with metadata aspects of stories, leaving interpreter configuration issues up to specific interpreters. This release (1.0) will be implemented in the 1.0.2 release of Zoom. The initial emphasis is on Z-Code stories, but the intention is to allow the indexing of stories in any of the formats currently in use. A simpler format (0.9) was originally used by Zoom. This new version is based on the results of a discussion on the Inform-developers mailing list.

1.1 Who should use this format?

Initially, this format will be used by Zoom to provide a searchable list of stories. However, I hope eventually to encourage archive maintainers and other interpreter authors to make use of the format. In addition, story authors may want to provide an XML description file along with their stories.

2 2 The format

All metadata index files are in XML format, and so begin with a line. The namespace URI is http://www.logicalshift.org.uk/IF/metadata. The metadata may be extended by addi- tional modules, which must have their own unique namespace. Parsers must always identify namespaces by URI and not by prefix. The metadata for a story may come from many different files. For example, an archive site may provide an index of games, a review site may provide reviews, the game author may provide ’feelies’ (resources associated with the story), and the user may provide notes and comments. Modules are intended to be ’functionally unique’, providing the data for one of these specific domains. Therefore, when an application fetches metadata from multiple locations, it might use the entire resources module from one place and the review module from another, but won’t merge parts of the resources section from one site with those provided by another.

2.1 The root element: ifindex

This tag specifies the version of the IF metadata format with the ’version’ attribute (0.9 for a file con- forming to this document). Usually, this should also specify the namespace URI and XML schema location. (2.1)

The tag contains tags, one for each story that is defined in the file.

2.2 The story tag: story

The tag is used to specify the data associated with a particular story. It must contain at least one section, and may contain one or more metadata tags. It appears only as a child of the ifindex tag. The section may be omitted if the metadata is associated with a game in some other fashion (for example if it is contained in a Blorb file).

2.3 The story identification tag: identification

The tag appears as part of a section, and must contain a tag identifying the format of the story, and some data providing a unique ID for the story. It appears only as a child of , which must contain at least one of these tags, but may contain many if a story has several different versions. The tag is a synonym for the tag. The tag contains textual data identifying the format of the story. This version of the specifica- tion defines identification tags for the following formats:

zcode A Z-Code story of the type released by Infocom in the 1980s, or, more recently, compiled with the Z-Code version of Inform.

glulx A glulx story of the type compiled by the Glulx version of Inform.

The following additional types are reserved for other existing formats, and may have identification tags defined in the future:

3 tads A TADS story compiled by the TADS compiler. hugo A HUGO story compiled by the HUGO compiler. alan An Alan story adrift An Adrift story level9 A story in the Level 9 format AGT A story in the AGT format magscrolls A story in the magnetic scrolls format advsys A story in the advsys format

2.3.1 Example

zcode 871125 52 (2.2) 4b37 d82484e664a8c328364e9814d1f73c60

2.3.2 Z-Code identification tag: zcode

The tag is used only when the value is ’zcode’. In that case, it must appear exactly once as a child of an tag. It should contain the following elements:

The textual serial number of the story. This is usually a six-digit string specifying the date of release, such as 871125. The release number of the story (for example, 52). (Optional, but recommended) The checksum of the story, in hexadecimal format, as spec- ified in the header of the story (for example, 4b37). This field is optional, but note that the se- rial/release numbers are not guaranteed to be unique, especially with more recent stories.

2.3.3 Glulx identification

ULX format files do not contain any specific story identification information. However, those compiled by Inform may contain a short ’Info’ section located after the header. The section is therefore optional, and only applies to stories compiled with Inform. An section should be used to more precisely identify a Glulx story. The section may contain the following tags:

The textual serial number of the story. This is usually a six-digit string specifying the date of release, such as 030501. The release number of the story (for example, 2).

4 2.3.4 MD5 identification

Any story format may have an MD5 section. This is a hexadecimal representation of the MD5 checksum of a story file. In the case of a Blorb file, this is the MD5 checksum of the executable portion of the file (the Z-Code or Glulx code file that it contains) rather than the entire file. There are several utilities available for generating MD5 checksums, for example the ’md5’ utility that comes with OpenSSL. Any story may have an section, although the format-specific identification should be used for preference as it will be easier to write for a story author.

2.4 The metadata tags

Each metadata tag may appear zero or one times as a child of the tag. The following tags are defined: