The XML format

This page describes the format of the response that the database sends when replying to a query. When the query has been successful, this is an HTTP response containing an XML document (with MIME type application/xml).

How official is this format?

At the time of writing (May 2005), the Methods Committee of the Central Council are considering ideas for a possible official XML standard for sharing information about methods. No concrete proposal has yet been published, and it may be some time before this happens. For this reason, we have decided to go ahead and make this database available using an XML format which we have designed.

If and when the Central Council does agree a standard, this database will quickly change to adopt that standard. The design will make this easy to do. We hope that any Central Council standard would be similar to our XML format. However, the database would continue to support the current format to avoid breaking existing software. In particular, the libraries that you can download from this site for accessing the database from various programming languages will continue to work even after the database starts supporting a future new standard.

Background

All definitive information about XML can be found in the W3C web pages; there are also links there to many other pages about XML. There are several free libraries available for manipulating XML, including LibXML from the GNOME project and Xerces from the Apache project. These libraries have bindings to various languages including C, C++, Perl and Java.

The particular format of the XML documents returned by this database comforms to a slightly more general XML schema which is available here. A description of that schema is here. In the event of the Central Council Methods Committee deciding on a standard XML schema for representing methods, this database could very easily be changed to conform to that standard.

Absence of elements and nil values

As a database user, you can choose what information you are given about each method which matches your query. For example, you could ask to receive just the title of each matching method; or you could retrieve just the place notation for a method for which you already knew the title. For more information on how this works, see the fields= query option.

This means that it is perfectly possible to get back from the database a method which, for example, has no lead head code information. Nothing should be deduced from the absence of this information. On the other hand, if a method is returned which has the lead head code explicitly specified to be nil, by setting the xsi:nil attribute on the method's <lhcode> element, then this means that the method has irregular lead heads. The same applies to several other elements within the method information.

Sample document

Here is a sample XML document returned from the database, in this case coming from the query string name=Pudsey&classes=Surprise&stage=8. It has been reformatted slightly to aid readability. Note that it is not necessary to retrieve all this information about each method; what information is returned can be controlled by the fields= query option.

<?xml version="1.0"?>
<methods xmlns="http://methods.ringing.org/NS/method" 
         xmlns:db="http://methods.ringing.org/NS/database"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="0.1" 
         db:page="0" db:pagesize="100" db:rows="1">
  <method id="m8457">
    <name>Pudsey</name>
    <stage>8</stage>
    <classes>Surprise</classes>
    <title>Pudsey Surprise Major</title>
    <pn>
      <symblock>-58-16-12-38-14-58-16-78</symblock>
      <symblock>12</symblock>
    </pn>
    <lead-head>15738264</lead-head>
    <classification>
      <cc-class year="2002" 
                class="treble-dodging/surprise" 
                little="false" 
                differential="false"/>
      <lhcode code="b"/>
    </classification>
    <refs>
      <rwref>63/372</rwref>
    </refs>
    <performances>
      <firsttower>
        <date>1924-03-15</date>
      </firsttower>
      <firsthand>
        <date>1963-05-05</date>
      </firsthand>
    </performances>
    <meta>
      <db:timestamp>2004-01-13T22:57:30</db:timestamp>
    </meta>
  </method>
</methods>

Description of the elements

We will now describe each of the elements appearing in the sample document in detail.

The <methods> element

<methods xmlns="http://methods.ringing.org/NS/method" 
         xmlns:db="http://methods.ringing.org/NS/database"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         version="0.1" 
         db:page="0" db:pagesize="100" db:rows="1">
  <!-- ... -->
</methods>

The <methods> element is the root element of the document. It contains one <method> element for each method found by the database query.

The first feature of the <methods> element is that it declares several namespaces, including a default namespace.

• The default namespace, with URI http://methods.ringing.org/NS/method, is the namespace in which most of the XML elements live. It contains all the elements which describe the methods returned by the database, including the <methods> element itself.
• The namespace with URI http://methods.ringing.org/NS/db is for a few attributes and elements which contain not information strictly about the methods, but rather extra information which the database adds. This namespace is associated to the prefix db:.
• The standard namespace is associated to the xsi: prefix; this is only used for the xsi:nil attribute which is sometimes used to indicate that elements have nil values. For more information, see the XML Schema documentation on the W3C site.

There are several further attributes on the <methods> element:

• The version attribute identifies the version of the method XML schema to which this document conforms. At the moment it is always 0.1.
• The db:page attribute shows which page of results this is; it corresponds to the page= query option.
• The db:pagesize attribute shows how many methods were requested per page of results in the pagesize= query option.
• The db:rows attribute gives the total number of methods in the database which satisy the query. This can be divided by the page size to find out how many pages of results there are in total.

The <method> element

<method id="m8457">
  <!-- ... -->
</method>

Inside the <methods> root element, there is one <method> element for each method in the result set.

The <method> element has one attribute, id. This contains a unique ID for the method within the database. It can be useful when, for example, going back to get further information about a method which was found in a previous query.

The <method> element contains several child elements which give all the information about the method. Which of these elements are present is controlled by the fields= query option.

The <name> element

<name>Pudsey</name>

This element contains the name of the method, without classes or stage. If this element is nil (i.e. has the attribute xsi:nil='true') then the method is unnamed.

The <stage> element

<stage>8</stage>

This element contains the stage of the method, as a decimal number.

The <classes> element

<classes>Surprise</classes>

This element contains the Classes of the method, as defined by the Central Council Decisions. If the method is not classified by the Decisions, this element is nil (i.e. has the attribute xsi:nil='true').

The <title> element

<title>Pudsey Surprise Major</title>

This element contains the title of the method. As specified in the Decisions, the title of a method consists of its Name, Classes and Stage. If the method is unnamed then this element will be nil (i.e. have the attribute xsi:nil='true').

The <pn> element

<pn>
  <symblock>-58-16-12-38-14-58-16-78</symblock>
  <symblock>12</symblock>
</pn>

This element contains the place notation of the method. It will always be of one of two forms:

• If the method is symmetrical about a change, then the place notation may be divided into two symmetrical pieces. The first half of each piece is put into a <symblock> element. The place notation for the whole lead consists of: the contents of the first <symblock> element; the same, omitting the last change, backwards; the contents of the second <symblock> element; and the same, omitting the last change, backwards. As is seen from the example above, this is exactly how place notation for methods symmetrical about the half lead is usually given.
• Otherwise, the place notation consists of a single <block> element containing the place notation for an entire lead of the method.

In either case, place notation follows these conventions: a cross change is indicated by a dash `-'; external places are included.

The <lead-head> element

<lead-head>15738264</lead-head>

This element contains the first lead head of the method.

The <classification> element

<classification>
  <!-- ... -->
</classification>

This element contains child elements, each of which describes some classification of the method. Currently these are <cc-class> and <lhcode>.

The <cc-class> element

<cc-class year="2002" 
          class="treble-dodging/surprise" 
          little="false" 
          differential="false"/>

This element describes the classification of the method according to the Central Council decisions. It has four attributes:

• The year attribute identifies which version of the CC decisions this classification relates to, and is currently always 2002.
• The class attribute gives the method class. This is one of the following.
  • principle
  • plain/bob
  • plain/place
  • treble-dodging/treble-bob
  • treble-dodging/surprise
  • treble-dodging/delight
  • treble-place
  • alliance
  • hybrid
  • slow-course

  If the class attribute is missing, then the method is not classified by the CC decisions.

• The little attribute is true or false and shows whether the method is a Little method.
• The differential attribute is true or false and shows whether the method is a Differential method.

The <lhcode> element

      <lhcode code="b"/>

This element has one attribute, code, which contains the Central Council standard lead head code for the method. If it has no code attribute but instead has the xsi:nil attribute set to 'true', then the method is irregular. (Note that we're using a slightly unusual definition of regular here: the method must have Plain Bob or Grandsire lead heads and have lead end change 1 or 12 (for Plain Bob lead heads) or first change 1 or 3 (for Grandsire lead heads).)

The <refs> element

<refs>
  <rwref>63/372</rwref>
</refs>

This element contains child elements which describe references to the method. Currently, only one such child element is defined: the <rwref> element, which contains one or more Ringing World page references.

The <performances> element

<performances>
  <firsttower>
    <date>1924-03-15</date>
  </firsttower>
  <firsthand>
    <date>1963-05-05</date>
  </firsthand>
</performances>

This element contains information about one or more performances of the method. At the moment it has up to two child elements, <firsttower> and <firsthand>. Each of these has a single child element, <date>, giving the date of the performance in year-month-day format. In the future we hope to include the locations of the performances as well.

The <meta> element

<meta>
  <db:timestamp>2004-01-13T22:57:30</db:timestamp>
</meta>

This element contains information which is not part of the method, but instead pertains to the way the method is stored in this particular database. At the moment there is only one child element, the <db:timestamp> element, which contains the time the database entry for the method was last modified.