IF XML Metadata Format
Total Page:16
File Type:pdf, Size:1020Kb
**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 <?xml version="1.0"?> 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. <ifindex version="1.0" xmlns="http://www.logicalshift.org.uk/IF/metadata"> (2.1) The <ifindex> tag contains <story> tags, one for each story that is defined in the file. 2.2 The story tag: story The <story> tag is used to specify the data associated with a particular story. It must contain at least one <identification> section, and may contain one or more metadata tags. It appears only as a child of the ifindex tag. The <identification> 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 <identification> tag appears as part of a <story> section, and must contain a <format> tag identifying the format of the story, and some data providing a unique ID for the story. It appears only as a child of <story>, which must contain at least one of these tags, but may contain many if a story has several different versions. The <id> tag is a synonym for the <identification> tag. The <format> 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 <story> <identification> <format>zcode</format> <zcode> <serial>871125</serial> <release>52</release> (2.2) <checksum>4b37</checksum> </zcode> <md5>d82484e664a8c328364e9814d1f73c60</md5> </identification> </story> 2.3.2 Z-Code identification tag: zcode The <zcode> tag is used only when the <format> value is ’zcode’. In that case, it must appear exactly once as a child of an <indentification> tag. It should contain the following elements: <serial> The textual serial number of the story. This is usually a six-digit string specifying the date of release, such as 871125. <release> The release number of the story (for example, 52). <checksum> (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 <glulx> section is therefore optional, and only applies to stories compiled with Inform. An <md5> section should be used to more precisely identify a Glulx story. The <glulx> section may contain the following tags: <serial> The textual serial number of the story. This is usually a six-digit string specifying the date of release, such as 030501. <release> 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 <format> may have an <md5> 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 <story> tag. The following tags are defined: <title> The title of the story (for example, Zork 1, Solid Gold Edition) <author> The author of the story <genre> The genre of the story (Fantasy) <published> The date the story was first published in YYYYMMDD format (19810505) <revision> The revision number of the game <headline> The headline of the story (Infocom interactive fiction - a fantasy story) <group> The ’group’ the story is in (for example, ’Infocom’, ’Competition 1998’, etc) <zarfian> The story’s rating according to the ’Zarfian’ scale (’Merciful’, ’Polite’, ’Tough’, ’Nasty’, ’Cruel’) <teaser> The story’s teaser text <series> Specifies the series that a game is part of <seriesnumber> Specifies the number in the series the game is <serieslength> Specifies the length of the game series The ’Zarfian’ rating system is described by Andrew Plotkin as follows: Merciful cannot get stuck Polite can get stuck or die, but it’s immediately obvious that you’re stuck or dead Tough can get stuck, but it’s immediately obvious that you’re about to do something irrevocable Nasty can get stuck, but when you do something irrevocable, it’s clear Cruel can get stuck by doing something which isn’t obviously irrevocable (even after the act) Comments and teasers may contain newlines, specified by a <br /> tag: all other tags are single line values. No tag may appear more than once. The genre can be any textual value, but Zoom suggests the following list of ’standard’ genres: • Fantasy 5 • Science fiction • Horror • Fairy tale • Surreal • Mystery • Romance • Historical • Humour • Parody • Speed-IF • Arcade • Interpreter abuse 6 3 Optional modules 3.1 The feelies module This module can be used to specify ’feelies’: additional media associated with a game. The namespace URI for this module is http://www.logicalshift.org.uk/IF/metadata/feelies The tags supported by this module are: <icon> A miniature picture associated with the game. This should be a base 64 encoded PNG file of 128x128 size, and can be used by an interpreter to display an image associated with a game file.