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 <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.
|