methods.ringing.org

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 this XML format was designed (May 2005), the Central Council were considering ideas for a possible official XML standard for sharing information about methods. No concrete proposal had been published, and looked likely to be some time before one was. For this reason, we decided to make this database available using an XML format which we have designed.

The Central Council did eventually produce their own XML format, but this site continues to use our XML format to avoid breaking existing software.

Background

All definitive information about XML can be found in the W3C’s web pages on XML. There are several free libraries available for manipulating XML, including LibXML from the GNOME project which has bindings to various languages including C, C++, PHP, 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.

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.

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

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 class descriptors of the method, as defined by the Central Council’s Framework for Method Ringing. Note that this will never include the Principle or Hybrid class names. If the method is not classified by the Framework, 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, which consists of its name, classes and stage name, except that the class Hybrid is not included in the title. 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:

In either case, place notation follows these conventions: a cross change is indicated by a minus sign -; 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="2022" 
          class="treble-dodging/surprise" 
          little="false" 
          differential="false"/>

This element describes the classification of the method according to the Central Council’s Framework for Method Ringing or the earlier Decisions. It has four attributes:

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.