catalog.doc

The catalog format is meant for when you publish a game world using this
software, that it will then be indexed so that others can search, upload,
and download them (it is also intended that it would be possible to mirror
the game worlds and catalog data). This does not mean that anyone is
required to use the catalog service; you can just use disks, or you can
use an alternative catalog service, but regardless of which way you do it,
the catalog format may be helpful for storing metadata (although this is
not required if you are not using the catalog service, it can be helpful).
A game world can also be uploaded to multiple catalog services if desired.

(Note that the below is a DRAFT version and is not finalized yet. It is
likely to be changed in future before it is implemented.)

See oid.ter for a list of OIDs and some other notes.


=== Data types ===

The "Displayable text" type means a General string or PC string or TRON
string, with the specifications listed here. Some are single-line text, and
some are multi-line text; if it is multi-line text, then CRLF pairs are
allowed, for representing line breaks; otherwise, control characters should
not be used. CRLF pairs are treated as line breaks in multi-line PC
strings, but in single-line PC strings they are treated as a pair of
graphic characters. Character code zero (a null character) should not be
used at all in any string.

Some Displayable fields are also "bibliographic" fields, and allow the use
of ISO-IR-67 controls. The first instance of any one of the control
characters listed below must be preceded by three bytes <1B 22 42> to
designate the use of these controls. (These are not allowed in PC strings
or in TRON strings.)

<88> and <89> surround a part of a text which is ignored for sorting.

<95> and <96> surround a part of a text which is only used for collation.

<97> and <98> surround a part of a text with subordinate collation value.

<9C> and <9D> surround a part of a text which is to be treated as a keyword
for bibliographic purposes.

<9E> and <9F> surround a part of a text which is to be permuted to the
front of the element when references and indices are generated.

If DOCS is used to switch to other character encodings (such as TRON-8,
which uses <1B 25 23 40>), then you can still use the above control
characters but they must be made as 7-bit controls rather than 8-bit
controls, meaning <1B> followed by subtracting <40> from the above codes,
e.g. <1B 48> and <1B 49> for a part of a text which is ignored for sorting.


=== CATALOG.DER ===

The format of the CATALOG.DER lump is a ASN.1X DER sequence with fields:

* The type of catalog data, which is enumerated: 0 means inactive or draft,
1 means standard, and 2 means nonstandard. A catalog service should reject
it if the type is anything other than 1, and the client software should
refuse to send such a world file (possibly with a switch to override it,
although the server will probably reject it anyways if you do override it).
(Note that this type does not affect the format of the catalog data; if the
type is 2 (nonstandard), this means that it has a nonstandard use rather
than being a nonstandard format; the format is still standard.)

* A OID to identify the hash algorithm to use to identify this world file.

* A key/value list of extensions. The keys are OIDs and the values are
the values of those extensions (the type of the values depends on the
extension, and some extensions may allow more than one type).


=== Side file ===

The side file is also a DER file, and is a sequence with fields:

* Service identifier (a OID). This is null if not applicable.

* A OID to identify the hash algorithm. (This hash algorithm will be used
for this file as well as for the world file, and should normally be the
same as the hash algorithm specified in the CATALOG.DER lump.)

* The hash of the world file. The hash is stored as a octet string.

* The file size of the world file (integer).

* A sequence, which is a copy of the sequence in the CATALOG.DER lump of
the world file.

* A key/value list of extensions. The keys are OIDs and the values are
the values of those extensions. Some extensions are meaningful in both
the world file and side file, but some are only one or the other.

Object identifiers can be relative or absolute like CATALOG.DER; the
same rules are followed.


=== Service information file ===

The service information file can be used to obtain information about a
catalog service. The format is a sequence with fields:

* Service identifier (a OID). (This is the same OID that is mentioned
in the side file.)

* A sequence or set of Visible strings, which are absolute URLs for the
main URLs of this service (more than one is possible, in case some of
them are mirrors). If this is a sequence, the first one is preferred.

* A sequence or set of Visible strings, which are absolute URLs for
read-only access to this service. (If this is empty, then the same URLs
are used as the main URLs of this service.)

* A bit string to indicate which cases authentication is required. The
first bit means downloading world files, second means downloading metadata
files and side files, third means querying, fourth means uploading worlds,
and fifth means adding comments and other stuff like that.

* A key/value list of extensions.

(This section is incomplete and is likely to be changed in future)


=== Protocol ===

The URL for the service may start with "scorpion:" or "scorpions:". It
should end with a slash, and should not include a query string or a
fragment name. A user name and password is allowed but it is not
mandatory and is not recommended for announcing services, although the
user may add it manually if necessary.

User authentication types:

* Username/password (included in the URL, before the domain name)

* HMAC (only for write access; cannot be used to restrict read access)

* X.509 (only for secure connections; recommended)

What authentication types are acceptable, how to register new accounts,
what hash algorithm to use for HMAC, and what criteria are used to decide
which X.509 certificates are acceptable, depends on the server. This
document does not impose any requirements about such things.

Two request types are used, R for receiving data and S for sending data.
Range requests are allowed for some operations; some implementations may
also allow range requests for some other operations as well.

All requests will use the URL with something added on the end, which is
the specific operation.

The operations for receiving are:

* _info = Download the service information file. (You might already have
it, which will be used to connect to this service. However, this can be
used if you want to download a new version of the file.)

* _side/ = Followed by some kind of identifier to download the side file.
This identifier is specific to the service being used.

* _world/ = Followed by the hash of the world file in lowercase hexadecimal
format, to download the world file.

(This section is incomplete and is likely to be changed in future)


=== Extensions ===

Note that it is possible to use extensions other than the ones listed here,
but these are a "standard" set of extensions. All extensions are optional.
Some extensions are only meaningful or only recommended in the CATALOG.DER
lump, others are only meaningful or only recommended in the side file, and
some are suitable for both.

...3.0 (Author) [Set]
  Set of authors. Each item in the set represents one author, and is a set
  of author names. Each author name can be a Displayable text, a Visible
  string (representing a absolute URL using any scheme), or a OID.

...3.1 (Title) [PC string]
  The title of the world file.

...3.1.0 (Title, general) [Displayable text]
  Like ...3.1 but is not limited to PC characters.

...3.2 (Long description) [Displayable text]
  A multi-line Displayable text which is a long description of the world.

...3.3 (Positive and negative classifications) [Sequence]
  A sequence of two sets of OIDs. The first is the set of classifications
  which the author claims are applicable to this world, and the second is
  the set of classifications which the author claims are not applicable to
  this world. In the side file, they are the claims of the catalog service
  instead of the claims of the author.

...3.4 (Hash of previous version of world file) [Octet string]
  Should be used in the CATALOG.DER lump, if this is a new version of a
  world file which an older version was previously published. This is the
  hash of the previous version of the world file.

...3.5 (Downloads) [Set or Sequence]
  A set or sequence of Visible strings, which are URLs for downloading the
  world file (any schemes may be used). If it is a sequence, then the first
  URL listed has preference; if it is a set then there is no preference.

...3.6 (Publish date/time) [Date/time]
  Specifies when the world file is published.

...3.7 (Mandatory and optional feature sets) [Sequence]
  A sequence of two sets, which are the copy of the first two fields of the
  GENERAL.DER lump. (This is only useful in the side file; it should not be
  included in the CATALOG.DER lump, because it is redundant.)

...3.8 (World version) [Printable string]
  The world version. This should be different for each version of that
  world, and is the version for the world and is not the version number of
  Super ZZ Zero (which is separate). This specification does not make any
  interpretation of the specific value, so you can use it in your own way.