[Cache from http://xfml.org/spec/0.1.html; please use this canonical URL/source if possible.]

Archived: Official XFML specification version 0.1.

Status of this document.

This is not the final version of this spec.

This is version 0.1 of this document, published on May 30, 2002. The latest version can always be found at this url http://xfml.org/spec/, which will eventually point to the final version. This version (0.1) is archived at http://xfml.org/spec/0.1.html We hope to publish the final version soon, after initial feedback on this document. We don't expect any substantial changes to the specification, just more preciseness . If you have any comments or ideas please contact Peter Van Dijck at peter@poorbuthappy.com

Background.

The EXchangeable Facet Map Language is an XML format that allows websites to publish a lot of their core metadata information. A website will typically use this metadata to organize its navigation. If it is published in XFML format, other websites can use this information to generate links to pages about related topics on this website.

There is an annotated example document further down this page.

XFML was designed to be simple yet powerful. It borrows many ideas from Topicmaps, a format you should check out if you like the ideas behind XFML but are frustrated with its limitations (see http://topicmaps.org). Unlike Topicmaps, XFML is designed to be easy to code for, and easy to understand. It trades power for ease, yet retains some extremely powerful.

Publishing XFML is conceptually similar to publishing RSS: you get many of the same advantages: it is easy, and you get a lot of incoming links and additional functionality possibilities that would otherwise be extremely difficult to obtain.

XFML is based on the idea of faceted metadata. Faceted metadata schemes are generally more powerful, flexible and useful for websites than more classic hierarchical taxonomies.

Taxonomies published as XFML can (unless there are license restrictions) be reused by other people. XFML maps are designed so they can be easily merged.

For more information, including a tutorial and links to software, see XFML.org

XFML specification.

An XFML map is a well formed XML document, but doesn't have to be valid (ie. conform to a DTD). (Please tell us if this is a bad idea.) It does have to follow this specification.

An XFML map contains (in random order, but we recommend the following order):

  • <XFML> tags. (Required)
    • Attributes:
      • url (optional, but Required for published maps. One only.).
      • version (required, like this: "1.0")
      • language (optional, like this: "en-us")
      • copyright (optional, like this: "2002, Peter Van Dijck, http://petervandijck.net")
    • Subelements:
      • <occurrencetype> (optional)
      • <publisher> (optional)
      • <facet> (optional)
      • <topic> (optional)
      • <page> (optional)
  • <occurrencetype> Occurrencetypes (Optional, multiples.)
    • If no occurrencetype is indicated with an occurrence, the type "webpage" is assumed by default. We recommend using the following occurrencetypes by default: mailing list archive, blog, discussion, article, picture, website, webpage.
    • Subelements:
      • <name> A name (Required, one only, unique.)
      • <ordername> An ordername (Optional, one only.)
  • <publisher> Publishers. (Optional, multiples.)
    • Subelements
      • <name> A name (Required, one only, unique.)
      • <ordername> An ordername (Optional, one only.)
      • <url> A URL (Optional, one only.)
  • <facet> Facets. (Optional, multiples.)
    • Subelements:
      • <name> A name (Required, one only, unique.)
      • <ordername> An ordername (Optional, one only.)
  • <topic> Topics. (Optional, multiples.)
    • Subelements:
      • <facet> A facet. (Required, one only.) So if you have topics you must have at least one facet.
      • <name> A name (Required, one only, unique.)
      • <ordername> An ordername (Optional, one only.)
      • <parent> A parent (Optional, one only.)
      • <merge> A mergerule (Optional, multiples.) A mergerule consists of the URL of another XFML map, with an additional # and the name of a topic on that map.
  • <page> Pages. (Optional, multiples.) A page contains:
    • Subelements:
      • <url> URL (Required, one only, unique.)
      • <name> A name (Required, one only.)
      • <ordername> An ordername (Optional, one only.)
      • <publishdate> Publishdate (Optional, one only.) The date format is Required like this YYYY-MM-DD, for example 2002-05-22.
      • <publisher> Publisher (Optional, multiples.)
      • <occurrence> Occurrences. (Optional, multiples.)
        • Subelements:
          • <topic> A topic (Required, one only.)
          • <occurrencetype> An occurrencetype (Required, one only.)

Names of elements have to be unique for that element only. So you can have a topic and a facet with the same name, but not two topics with the same name, even if they are in a different facet.

Publising an XFML map.

A "published map" is an XFML document that has been made available on the web, ie. has a unique URI. An XFML map can be published, but doesn't have to be; you could also just use it internally in your and never publish it.

In general, the mimetype for an XFML document (when accessed over HTTP) should be text/xml. This allows Web browsers to use XML formatting conventions to display an XFML document. The extension we recommend is .xml

Mergerules.

One of the more powerful things with XFML is that you can merge maps: you can relate a topic on one map to a topic in a different map, so the system knows they are the same. The following mergerules must be obeyed when merging topics:

  1. Two topics can only merge if their parent topics (if any) have been merged.

When merging topics, the meaning of the topic is derived by the person doing the merging from its name, its existing occurrences and mergerules and its facet. Automatic merging based on names is possible but risky.

License.

XFML is a format created by Peter Van Dijck. It can be freely used by anyone.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copies and derivative works.

This document may not be modified in any way, such as by removing the copyright notice or references to XFML.org or other organizations. Further, while these copyright restrictions apply to the written XFML specification, no claim of ownership is made by XFML.org or Peter Van Dijck to the format it describes. Any party may, for commercial or non-commercial purposes, implement this protocol without royalty or license fee to XFML.org or Peter Van Dijck. The limited permissions granted herein are perpetual and will not be revoked by XFML.org or Peter Van Dijck or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and XFML.org and Peter Van Dijck DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Annotated example XFML document.

Here is a short annotated example of an XFML map. You can find it in XFML format at http://xfml.org/spec/example.xml.

<xmfl url="http://xfml.net/spec/example.xfml" version="0.1"> <!-- language and copyright attributes are optional -->

# Occurence types can be added at will, but we recommend using these standard types as a default. When a page is connected with a topic, an occurrence type can be used to explain what kind of occurrence it is: is the page a discussion about the topic, or does it contain pictures about the topic?
<occurrencetype> # Optional
   <name>Mailing list archive</name>
</occurrencetype>
<occurrencetype> # Optional
   <name>Blog</name>
</occurrencetype>
<occurrencetype>
   <name>Discussion</name>
</occurrencetype>
<occurrencetype>
   <name>Article</name>
</occurrencetype>
<occurrencetype>
   <name>Picture</name>
</occurrencetype>
<occurrencetype>
   <name>Website</name>
</occurrencetype>
<occurrencetype>
   <name>Webpage</name>
</occurrencetype>

# an XFML map can contain unlimited amount of publishers. Webpages always have at least one publisher. The publisher can be a webpage, a person, whatever you want.
<publisher> # Optional
   <name>XFML.net</name> # Required
   <ordername>xfml</ordername> # Optional
   <url>http://xfml.net</url> # Optional
</publisher>

<publisher> # Optional
   <name>poorbuthappy</name> # Required
   <url>http://poorbuthappy.com</url> # Optional
</publisher>

# Facets are the basic building blocks of a map. Every topic belongs in one facet. Facets must be constructed to be clearly mutually exclusive, ie. something that belongs to one facet can never belong to another facet. In this example, a "place to stay" will never be a "thing to do".
<facet> # Required
   # A facet must have a name. It can optionally have a ordername. If no ordername is present, the name is used to order it.
   <name>places to go</name> # Required
</facet>
<facet>
   <name>things to do</name>
</facet>

# Topics are the building blocks of the map. Topics can be arranged in parent-child hierarchies. One topic always belongs to one facet.
<topic> # Optional
   <facet>places to go</facet> # Required
    <name>Colombia</name> # Required
   <ordername>colombia</ordername> # Optional
</topic>
<topic>
   <facet>places to go</facet>
    <name>Bogota</name>
   <ordername>bogota</ordername>
   <parent>Colombia</parent>
# Mergerules tell the map which topics on other maps are really the same topic. You can have many mergerules for one topic.
   <merge>http://xfml.net/spec/example_merge.xfml#capital of colombia</merge>
</topic>
<topic>
   <facet>things to do</facet>
    <name>Diving</name>
   <ordername>diving</ordername>
</topic>

<page> # Optional
   <url>http://poorbuthappy.com/colombia</url> # Required
   <name>Guide to Colombia</name> # Optional, you can also add an ordername.
   <publishdate>2002-02-21</publishdate> # Optional (format is Required though!)
   <publisher>poorbuthappy</publisher> # Optional, you can have multiple publishers for one page (in case of multiple authors of an article for example)
# An occurrence says which topics a page is related to. The occurrence type says in which way the page is related to the topic. You can have multiple occurrences for one page.
   <occurrence> # Optional
      <topic>Bogota</topic> # Required
      <occurrencetype>Picture</occurrencetype> # Optional
   </occurrence>    
   <occurrence>
      <topic>Diving</topic>
      <occurrencetype>Discussion</occurrencetype>
   </occurrence>  
# So this page contains pictures of "Places to go: Colombia: Bogota" and a discussion of "things to do: diving"
</page>

</xfml>