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.
- 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 prefixdb:
. - The standard namespace is associated to the
xsi:
prefix; this is only used for thexsi:nil
attribute which is sometimes used to indicate that elements have nil values. For more information, see the W3C’s documentation on XML Schema.
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 thepage=
query option. - The
db:pagesize
attribute shows how many methods were requested per page of results in thepagesize=
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 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:
- 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 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
year
attribute identifies which version of the CC Framework or Decisions this classification relates to. It is currently always 2022, which represents version 2.0 of the Framework. - 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
If the
class
attribute is missing, then the method is not classified by the CC Framework or Decisions. - The
little
attribute istrue
orfalse
and shows whether the method is a Little method. - The
differential
attribute istrue
orfalse
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.