An OTD is a document that describes a MetaObject type. It can be used to generate human-readable documentation, used in a Vobject-edititng user interface, or generally by software. There were no OTDs in s4, but they have been used in the past, and will be used again in S5.
In the mean time, some hand-made object type documentation can be found here on this wiki-- see MetaObjectDocumentation.
History:
The original format was an XML vocabulary specific to OTDs. see ArchaicOtdFormat.
- Around that time that "s3" became "s4", we talked about using RDF for OTDs instead of a specialized XML format. This would allow any RDF library or tool to work with OTDs. However, we then decided to put OTDs on hold to concentrate on the software.
- It was planned that OTD files be hosted in a repository on the interreality.org website for download via HTTP, and also a VOS site extension be implemented to fetch OTDs for various object types used by that site.
In S5, Vobjects will be used to describe new type and component interfaces. You can store these Vobjects in a file like [XOD] of course, or any other medium, and any types a site is using are available directly from that site. (And so any object with a type will unambiguously be linked to the correct version of that type interface).
Discussion
Discovering OTDs
There is an object with a site name of "core:type-descriptions". It doesn't have any special type, but its children are expected to be OTDs ("core:type-description"). The contextual name should be the exact type string: "group:typename" (eg "misc:metadata"). This is the "local OTD repository". When a client finds a type it doesn't know how to handle, it may look for the appropriate OTD at that location on the remote site. When it knows how to handle it, but for some reason it's possible that version differences are critical, it may also look in both the local and remote site, and compare version numbers. --LaloMartins
The top level
The "name" and "group" attributes could stay; or we could just use the contextual name it has on the repository. (This might be better, if for some reason there is ever need for one type to be available under more than one name.) The "num" attribute may go; we have PCRs, which are better than indirect references. About "replaces" and "extends" I'm not sure. I'm tempted to have "extends" just be a child relationship to the other otd. "Replaces" could be useful in a central repository at interreality, but for a local repository, well, you'd more likely just not have the old otd... The versioning scheme could be more "normal"; I don't think people want to rename their types on new API versions. I'd keep the "revision" attribute (now property:int), and add a "version" property. -- LaloMartins
Child object entries
The type list could be stored in a property (one type per line?) or separate properties; I tend to think separate properties are cleaner. Either way, I suspect most entries will have zero or one type. -- LaloMartins
Naming binding methods and attributes
I'd like to have some hint of what to name autogenerated code. Probably add optional children to the child and message descriptions, with forms like "function-name", "function-name-c++", "attribute-name" (for cases where you want to use something similar to python properties to emulate simple attribute access -- my_metadata.title actually accesses the misc:title child object).
When there is no applicable such child, the language binding logic will choose one based on the method name or child contextual name, taking in account coding standards for the appropriate language. That would mean replace dashes, underscores and spaces with either underscores, dashes (if we ever have lisp bindings), or camel case. So the "misc:modification_time" property of "misc:metadata" could generate "getModificationTime" and "setModificationTime" in javascript, and a "modification_time" property on Python.
(Context: a Python property is something that looks and quacks like an attribute, but trying to get or set it actually invokes a getter/setter method. Since Python 2.2 we're encouraged to use them rather than explicit getters and setters, because they make the more to the point, and better express intent.)
-- LaloMartins