an object model for cataloging vintage computer material

[jonnosan <jonnosan@gmail.com>]

So what happened was, I bought an Apple II and some games on ebay and
have had fun learning how to crack. Now I want to collect together all
the info I have about these games, along with the DSK created at the
end of the process, and put them somewhere online as my own personal
trophy cabinet. Yes, I know, I'm 30 years late, but I'm a slow
learner.

But it seems that while the Apple II community has a couple of good
repositories of disk images, they are all pretty much the disk image
only, with no metadata, so no easy way to browse for particular
applications, or know the history of any particular disk. And also no
obvious way for someone who wants to document more info about their
collection to structure and publish that information.

So I've put together an object model (incorporating feedback from
people on this newsgroup) that I plan to use to store information
about my own collection. I am currently working on an XML
representation of that object model (tentatively titled VCMML -
"Vintage Computing Material Markup Language") and some ruby tools to
create, validate and use VCMML documents.

At the least, I hope to catalogue my own collection in VCMML, and then
publish that to my own website. But it occurs to me that this might
also be useful for other people to catalogue their own collections
(including collections of non-Apple material), and it would be nice to
see support for using this metadata in emulators and other tools (in
the same way MP3 player applications can show you the album cover for
the song you are listening to, and show you a link to the band's
website).

If this sounds interesting enough that you'd like to help define the
object model and XML schema, please leave a comment here or send me an
email ( jonnosan at gmail dot com) and I will set up a wiki and/or
mailing list to facilitate that discussion.

As of today, the VCMML object model looks like this:

A MANIFEST consists of one or more records about different types of
computing material

a SYSTEM MODEL is a record about a single model of computer sold by a
computer vendor. The Apple ][, Apple //e and Apple //c are all
seperate system models.

a PERIPHERAL is a hardware device that attaches to a computer. A
single peripheral may be usable with many system models. An example of
a peripheral is a Mockingbird sound card, or a Disk ][ disk drive, or
a joystick.

An APPLICATION is a record about a single version of a single program
running on a single computer system.

a MEDIA record contains information about a single physical store of
digital data. A media record will specify a MEDIA TYPE (e.g. floppy
disk, hard disk, EPROM, tape) and MEDIA FILE SYSTEM (e.g. ProDOS), and
will contain a one or more applications.

a MEDIA SET is a collection of related media records. In the case of a
manifest representing a multi-disk application, there will be a single
application record, a single media set record, and many media records.

a DOCUMENT is a record about additional documentation (including
pictures) about an application, system model or peripheral.

A document record will contain the URL of the actual document, along
with a short description.

Any object can have zero or more ANNOTATION records. An annotation is
a comment, which may be (for example) notes made by the

person preparing a copy-protected game for archiving, or personal
recollections left by visitors to a web site about a particular game.

My expectation is that there will need to be a single centrally
managed "common objects" manifest, which will assign cannonical IDs to
ubiquitous records such as the system models and common peripherals
(so it's easy to merge info from different people's collections and
know that everyone is referring to the same "Apple //c" record).

More detailed definition of each  object type:

- Manifest
	- * ID

- Application
	- * ID (GUID/URN/something else - needs to be globally unique)
	- * Name (free form text)
	- Description
	- Version
	- Author(s) (list of free form text entries)
	- Publisher (free form text entry)
	- Category (constrained list - will use the "Topic" list from the
Trove Software Map)
	- Minimum RAM
	- Required Peripherals (list)
	- Optional Peripherals (list)
	- Incompatible Peripherals (list)
	- Known Compatible System Models (list)
	- Known Incompatible System Models (list)
	- Documents (list)
	- Other References (list of URLs - e.g. Wikipedia articles)
	- Original License (free/shareware/commercial)
	- Current License (free/shareware/commercial)
	- Annotations (list)
	- Related Applications (list) - e.g. other versions of same
application, sequels, etc


- Media
	- * ID
	- * URL (local or absolute)
	- * Media Type (constrained list e.g. 5.25/3.5/ HD / Cassette)
	- * Original File System (constrained list e.g. DOS/PRODOS/Pascal/CP/
M/RDOS/Custom)
	- * Applications (list)
	- Annotations (list)
	- Known Issues (free form text)

- Media Set
	- * ID
	- Original packager (cracking group etc - free form text)
	- Repackager (free form text)
	- * Media (list)
	- Annotations (list)

- System Model
	- * ID
	- * Name
	- Description
	- Documents (list)
	- Other References (list of URLs - e.g. Wikipedia articles)
	- Annotations (list)

- Peripheral
	- * ID
	- * Name
	- Description
	- Documents (list)
	- Other References (list of URLs - e.g. Wikipedia)
	- Annotations (list)

- Document
	- * ID
	- Name
	- Type (Screenshot/cover art/original manual/cracker dox)
	- URL (relative or absolute)
	- Annotations (list)

- Annotation
	- Author (free form text)
	- Timestamp
	- Annotation (free form text - HTML allowed)


EXCLUSIONS / FUTURE ENHANCEMENTS
- RDF (it looks to be easy to map this object model in/out of RDF, but
adds a layer of indirection that makes the resulting  markup look more
confusing)
- Atom (may look to use APP to edit entries online in a future
revision)
- object model for people/organisations (i.e. authors/publishers etc)
- Free form text will do for now, may look at Dublin Core in a future
revision
- Better definition of types of relationships between related records
(e.g. linking records for the same game across multiple platforms,
such as the C64 and BBC versions of Elite). No need for this for quite
some time I think.