• ArchaicOtdFormat

Object Type Definition - Original XML Format

What follows is the original (around s2 and s3) OTD documentation by Reed, from an early version of the "Creating Interreality" book (a/k/a "The Manual"). It is included here because it covers all the kinds of information that on OTD ought to include.

In the CVS 'attic' (archive) you can find some Perl scripts somewhere that do some really simple parsing of alpha-format OTDs to generate human-readable HTML documentation, as well as the beginnings of a C++ library (libotdutil).

Introduction

An Object Type Definition (OTD) defines a MetaObject type, which (possibly used in combination with other types) forms the type of a particular Vobject. An OTD essentially contains documentation, expected linked objects, and protocol actions associated witha particular type.

An OTD is encoded with a special markup language, defined using XML This document can then be easily translated into text, HTML, XML-Schema, a database, or program code stubs, as well as parsed and interpreted by authoring tools, applications, etc.

For the formal OTD XML syntax, see the DTD at http://interreality.org/otd/otd.dtd.

The OTD Repository

A repository of OTDs is maintained at http://interreality.org/otd.

Contents and Syntax

First, an XML header is required in all OTD documents:

• <!DOCTYPE otd SYSTEM "http://interreality.org/otd/otd.dtd">

Comments may be included at any point in comment tags:

• <!-- this is a comment -->

The root element for an OTD is _otd_. Within that element are elements defining various aspects of the type. Note that the elements must be included in the correct order in order to conform to the XML DTD.

Name and Version Info

• <otd name="NAME" group="GROUP" revision="REV" number="#NUM" extends="EXTENDS

LIST" replaces="REPLACES LIST">

This information is supplied as attributes to the root element. It indicates name, repository numbber and revision number of this OTD, and which OTD versions this OTD replaces. It also provides a mechanism for 'extending' an older OTD.

replaces

An OTD may "replace" one or more existing OTDs, in which case it should encompass all the functionality of the old OTDs, and for some reason be preferred over the old ones. An application could also try to use an implementation of an older OTD from this list if it can't handle this version.

extends

In addition, another OTD may be "extended", in which case this OTD automatically conatains all the elements from the extended OTD, and the elements appearing in this OTD simply override the same elements in the extended OTD. (This makes versioning alot easier)

Note that "replace" does NOT imply "extend" nor does "extend" imply "replace".

Typically, a new version of an old OTD will replace or extend the old version.

revision

A revision is a compatible or minor change to an OTD for example, editing documentation for grammar/spelling/clarity, or updating informative content such as author or history or replacedby info, or adding optional objects and message fields. Revision starts at 0.

A new OTD should be written when any major features are added, removed or changed, under a new name. The convention for naming new versions is to append a period and a version number to the name (e.g. "type"; "type.1"; "type.2"). The "extends" and "replaces" attributes are used to indicate new versions of old OTDs.

group

The group is used to group related types in code libraries, the repository and documentation, but is not required. The group name is used as a prefix for subobject and method names.

name

A type's full name is formed by appending this string to the group name, with a colon (if the object has a group): "group:name". This name should be one word (no spaces, commas, etc) of only alphanumeric characters. Underscore ('_') and dash ('-') are also allowed, but not as the first letter. Punctuation characters may be added in the future, with special meaning. Puncutuation characters appended or prepended to the type name may also have special meaning within the internals of an application but should not be considered part of the type name.

Types must have unique names.

A type named "object-core" (Repository #000) will be defined by the developers to contain documentaiton and action definitions implicitly accepted by all MOS objects. In MOS, all objects implicitly implement "object-core", and it should not be included in object type lists.

The naming convention for types which extend other types is to prepend the name of the extended type with a dot (.). For example: "object3D.cube" is the name of a type which extends the "object3D" type.

New major versions should have new names to differentiate them from other versions. The convention for new types is the same as for extended objects: append the version number with a dot (.). For example: "foo.2" could be used for foo version 2.

number

This number is used to uniquely track and identify each OTD type in the repository. It is assigned by the repository editors uppon acceptance.

Description (required)

• <description>

  • Description of your type goes here.

  </description>

This description explains in detail the purpose and use of the type.

Authors list (required)

• <author>

  • <name>Reed Hedges</name> <organization>interreality.org</organization> <contact type="www">http://zerohour.net/~reed</contact> <contact type="email">nobody@zerohour.net</contact>

  • ..

  </author>

• ..

Authors or vendors for this type, with contact information.

For multiple authors, simply repeat the <author>_ element. For multiple methods of contact, repeat the _contact_ element, with different "type" attributes. Valid values for the "type" attribute are "www", "email", "phone", "fax", "post", "street", "icq", "aim", and "jabber".

The <organization> element is optional.

Child objects list

• <object name="NAME" type="TYPE LIST" optional="yes OR no">

  • <description>

    • Describe the purpose or meaning of this child object here.

    </description>

  </object>

• ..

Include an <object> element here for each child object this type expects. Include a contextual object name in the "name" attribute, or use a value of "*" (star) if the name is irrelevant. Include a list of types the child object must have inthe "type" attribute, seperated by commas. If the child object is not required, use a value of "yes" in the "optional" attribute. If omitted, optional defaults to "no".

Object names may contain any character, except "," (comma), '/' (slash), '^' (caret), '?' (question mark) and '#' (number or hash mark), '"' (quote), '&' (ampersand), '(' (left angle) or ')' (right angle).

Different OTDs may define subobjects with the same name. What this means, whether it causes any problems or conflicts, is entirely dependent on the types and their implementations. There probably won't be any major problems; the nature of metaobjects fits with this kind of combining.

To help avoid name conflicts between subobjects for different types, use the following naming convention: prepend the object name with your type's group name and a colon, like this:

• group:object_name

For example:

• a3dl:orientation

List of messages

• <message role="ROLE LIST" method="METHOD NAME">

  • <description>

    • Description of this message here.

    </description> <field name="FIELD NAME" optional="yes OR no">

    • <description>

      • Description of the field here.

      </description> <default>default value</default>

    </field>

  • ..

    <reply method="REPLY METHOD" />

    • ..

  </message>

Here list each message that this type understands and responds to. Use a <message> element for each message.

Method names may contain only alphanumeric characters, or dash ('-'). A colon may be also be used, but only in the way described below.

Different types may accept the same method name. While clients may control how messages are passed to metaobject handlers, in almost all cases the behavior should be to pass the message to all types which accept that method.

To help prevent method name conflicts between types, use this naming convention: prepend the method name with the type's group name and a colon:

group:action-name

The "role" attribute indicates how the message is used by this object. A role of "update" indicates that the message is always sent as a remote-update (an "update" message from local to remote objects). A role of "emits" indicates that this message is sent by this object. A role of "accepts" indicates that this message is accepted by this object. Seperate role tags with commas and/or whitespace (e.g. "emits, accepts").

The "field" element defines a message field. If the field is optional, use the value "yes" for the "optional" attribute. If omitted, optional defaults to "no". If a field is optional, you may supply a default value using the <default> element. Use a field element for each message field.

The <reply> element references a message defined in another message element, either before or after the current message. Include a <reply> element for each possible reply.

Application Support

• <application name="APP NAME" inforul="INFO URL" pluginurl="PLUGIN URL" />

This is a list of applications known to implement or understand this type. Probably only a couple will end up here, but it might be useful to have a few examples of this type in action. The "pluginurl" attribute references a plugin module (shared library/DLL for instance) which can be loaded into the named application in order to implement this type and version. The "infourl" attribute is a URL to more information about the application (e.g.. the application home page on the web).

History

• <history> <item revision="REVISION NUMBER" date="DATE">

  • Summary of changes.

  </item>

  • ..

  </history>

This section tracks the history of the OTD. Each <item> corresponds to a revision, given in the "revision" attribute. The "date" attribute should be in the format YYYY-MM-DD (e.g. "2002-06-27")

Wildcards

Generally, a star ("*") means "any value". To reference non-predetermined values in several places, you can use "named wildcards", which are written as: $(NAME), where "NAME" can be any alphanumeric string. (no punctuation except "_"). These "named wildcards" essentially mean the same as "*", but wildcards with the same name at different places in the OTD must share the same value. Named wildcards may be used anywhere in the OTD character data. (But NOT in the markup-- e.g. element and attribute names) You may escape the wildcard syntax with the standard XML escape code for dollar sign ($) If "(NAME)" does not immediatly follow a dollar sign, the dollar sign should be interpreted as a simple dollar sign, as if it were "$".