W3C XML | Member-Confidential!

The XML Documentation Markup (XDM)

Massimo Marchiori (W3C/MIT)

XDM Namespace: http://www.w3.org/1999/09/ql/xdm

Created: 1999/09/22.
Last modified: $Date: 2002/05/29 15:19:27 $.

Index

  1. What is XDM?
  2. The <document>
  3. The five W's: <what>, <who>, <where>, <when>, <why>
  4. The building block: <event>
  5. The refinements: <issue>, <requirement> and <action>
  6. Stylesheets
  7. Examples
           document
              |
            event
              |
            issue
           /     \
   requirement  action

 what  who  where  when  why

What is XDM?

XDM is the XML Documentation Markup, and it is the experimental markup language that the XML-Query working group will use in its documentation reports, like minutes, issues lists, requirement lists and so on. The main purpose of XDM is to enable the XML-Query working group to be its own testbench: that is to say, to test and check the query language development with its own documentation. A secondary purpose is, along the way, to provide a powerful and efficient way to handle information management, monitoring and retrieval in the working group.

This initial version of XDM has been designed with these specific goals in mind:

Hyperlink support "a la Xlink" is to be added. Also, a DTD is on its way, due to major requests.

The <document>

Any document, besides the things it describes, is per se a piece of information. The document tag is used to "wrap up" some content and produce the final document to be published: this tag, is therefore supposed to be the root tag of any  XML document that uses only XDM tags.

<document>

A document. Text inside this tag contains the actual content of the document.

Can have the following optional attributes:

title
The title of the document
creator
The creator of the document
date
The date in which the document has been created/modified
publisher
The organization or person responsible for publishing the document (usually, "http://www.w3.org/", for W3C)
language
The language of the document (usually, "en" for English)

Note that these attributes directly correspond to Dublin Core information elements.

The five W's: <what>, <who>, <where>, <when>, <why>

Every argument of discussion, like in the best journalistic practicse, is documented by the following five axes (each of them can be used zero or more times for an argument):

<what>description</what>
A description of the argument.
<who>person</who>
A person or entity related to the argument;
<where>location</where>
The location (physical place, telefone bridge, irc channel or whatever) of the argument
<when>date</when>
The date of the argument. The format of the date should be YYYY/MM/DD.
<why>description</why>
A justification of the argument.

The building block: <event>

The event tag is the building block on which the five w's operates. It can be used as a generic grouping tag to indicate an object, or specialized into a particular event type like a meeting or a teleconference.

<event>

A generic event.

Can have the following optional attributes:

name
A string uniquely identifying the event.
type
"meeting", "teleconference", "generic". Default is "generic".

Semantic model rules:

The refinements: <issue>, <requirement> and <action>

While the event tag is extremely useful to denote generic event and discussion fora like meetings and teleconferences, W3C's working groups also deal with other particular kinds of arguments, that are used so often to deserve special treatment: generic discussion issues, particular issues like requirements, and action items.

<issue>

A discussion issue.

Must have the following mandatory attribute:

name
A string uniquely identifying the issue

Can have the following optional attribute:

status
"ongoing", "dropped", "resolved". Default is "ongoing".

Semantic model rules:

<requirement>

A requirement.

Must have the following mandatory attribute:

name
A string uniquely identifying the requirement

Can have the following optional attribute:

status
"ongoing", "dropped", "resolved". Default is "ongoing".
kind
one in "must", "should", "may"or "undefined". Default is "undefined".

Semantic model rules:

The same as for issues.

<action>

An action item.

Must have the following mandatory attribute:

name
A string uniquely identifying the action item

Can have the following optional attribute:

status
"ongoing", "dropped", "resolved". Default is "ongoing".

Semantic model rules:

The same as for issues, with the following two exceptions concerning the <who> and <when> tags:

Stylesheets

So far there are two XSLT stylesheets for XDM:
xdmgeneric
An all-purpose XSL stylesheet for generic XDM documents.
xdmquerywg
An ehnancement of xdmgeneric tailored for the XML-Query wg, with hypersearch.

Examples

XDM has been in place at the XML-Query working group for some time. Here are some sample minutes taken from that Working Group:
Last modified on $Date: 2002/05/29 15:19:27 $ by $Author: massimo $.