Aims behind the design
----------------------

- The XML schema must be able to represent all information in the 
Central Council method collections.

- The XML schema should be able to represent much more information than
in the current method collections.  An XML format for presenting methods
may have many uses other than as a static collection.  In order that users
may see this as a suitable data format for their own applications, we
should not limit the information which could be included to that which
is currently available.

- The schema must be extensible.  This applies particularly to method
classification:  method classification has changed in the past, and
will continue to do so.  Also, some users will want to add other
classifications to methods, such as symmetry information.  It is therefore
important to allow arbitrary classification information to appear in
each method element.  We have also applied this idea to references.  In
addition, there should be a way of including arbitrary XML from other
namespaces so that application-specific data may be added.

- The schema must support incomplete data.  Although we allow for all
sorts of information to be present, none of it is required.  A method
may not have a name.  The date of a peal may not be known.  When
querying a database, the user might only want to know a subset of the
information available.  The example below shows an example containing
much information; but typically method elements may contain only some
of this information.

-------- SAMPLE METHOD ELEMENT --------

<method xmlns="http://cccbr.org.uk/NS/methods"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xlink="http://www.w3.org/1999/xlink">

  <name>Pudsey</name>
  <stage>8</stage>
  <classes>Surprise</classes>
  <title>Pudsey Surprise Major</title>

  <pn>
    <symblock>x58x16x12x38x14x58x16x78</symblock>
    <symblock>12</symblock>
  </pn>

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

  <refs xmlns:mc="http://cccbr.org.uk/NS/collections"
        xmlns:fb="http://fred.bloggs.org/NS/id">
    <rwref>63/372</rwref>
    <mc:ref collection="surprise-major">3738</mc:ref>
    <fb:ref format="extended">2453-A-63</fb:ref>
  </refs>

  <classification xmlns:s="http://methods.ringing.org/NS/symmetry">
    <cc-class year="2002" class="treble-dodging/surprise"/>
    <lhcode code="b"/>
    <s:symmetry>
      <!-- some elements describing symmetry -->
    </s:symmetry>
  </classification>

  <performances>
    <performance xlink:arcrole="http://cccbr.org.uk/relations/firsttower">
      <date>1924-03-15</date>
      <location>
	<place>Bolsover</place>
        <county>Derbyshire</county>
        <country>UK</country>
      </location>
    </performance>

    <firsthand>
      <date>1963-05-05</date>
    </firsthand>

    <performance xlink:arcrole="http://cccbr.org.uk/relations/record-length"
                 xlink:type="simple"
                 xlink:href="http://www.peals.net/database.xml#395"/>
  </performances>

  <meta>
    <m:timestamp xmlns:m="http://methods.ringing.org/NS/method">
      2003-07-15T20:15:39Z
    </m:timestamp>
  </meta>

</method>

-------- ANALYSIS OF SAMPLE ELEMENT --------

| <method xmlns="http://cccbr.org.uk/NS/methods"
|         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|         xmlns:xlink="http://www.w3.org/1999/xlink">

The <method> element, and all the other elements we will define,
belong in a namespace which, for the sake of argument, might be called
  http://cccbr.org.uk/NS/methods .
We also declare prefixes for the XML Schema Instance and XLink
namespaces, as they will be used later.

We make use in this schema of the `nil' mechanism.  This allows an element
to be declared `nil' by putting the an xsi:nil='true' attribute on it.  In
this schema, an empty or absent element means simply that the relevant
information is not given; a nil element has a specific meaning, such as the
method being unnamed.

|   <name>Pudsey</name>
|   <stage>8</stage>
|   <classes>Surprise</classes>
|   <title>Pudsey Surprise Major</title>

These are self-explanatory.  Note that the title can't be deduced from
name, classification and stage for "Grandsire, Union and their related
methods."

The <name> and <title> will be nil if the method is unnamed.  The <classes>
will be nil if the method is not classified by the CC Decisions.

|  <pn>
|    <symblock>x58x16x12x38x14x58x16x78</symblock>
|    <symblock>12</symblock>
|  </pn>

The place notation for this method consists of two symmetrical blocks.  The
same is true for any symmetrical method.  An asymmetrical method is written
with a single <block> element rather than two <symblock> elements.

Place notation contains no whitespace.  Either x, X or - may be used for a
cross change.  Dots may be put next to x, X or - if desired; some applications
may wish to do this to make searching on bits of place notation (e.g. a
given work below the treble) easier.


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

Self-explanatory.


|   <refs xmlns:mc="http://cccbr.org.uk/NS/collections"
|         xmlns:fb="http://fred.bloggs.org/NS/id">

The <refs> element is just being used as a container for the <ref>
elements, and as somewhere to bind some namespace prefixes.  We are
interested in two external namespaces: one for CC method collection
references, and one for Fred Bloggs' private collection.

    <rwref>63/372</rwref>
    <mc:ref collection="surprise-major">3738</mc:ref>
    <fb:ref format="extended">2453-A-63</fb:ref>
  </refs>

There is some subtle XML Schema stuff going on here.  The <refs> element must
contain a list of elements, each of which is of a type derived from our base
type or in a certain substitution group.  That means that the only things that
can appear here are elements which some schema author (either the CC or some
third party) has defined to be a type of method reference.  We have already 
defined a type for Ringing World references; others can define their own
types.

Here the <rwref> is a reference to the Ringing World; the <mc:ref> is what
an index to the Methods Committee collections might look like; and the 
<fb:ref> is one that Fred Bloggs has added, an index into his collection.
Because of the XML Schema typing system, it would be possible for Fred
Bloggs to specify in his own schema that his references always consist of
four digits, a letter and two digits, separated by dashes; and an XML Schema
validator would be able to check this.


|   <classification xmlns:s="http://methods.ringing.org/NS/symmetry">

Again, the <classification> element is just a container for the various
classification information.  Again, this is extensible.  We provide some
types for classification according to the Central Council scheme; third 
parties can define their own types for their own classification data.

|    <cc-class year="2002" class="treble-dodging/surprise"/>

This is the classification of the method according to the CC 2002 Decisions.
We have chosen to use a string containing a hierarchical representation
of the class.  Little methods would have little="true" and Differential
methods would have differential="True".  If the `class' attribute is absent, 
then the method does not conform to the Decisions.

|    <lhcode code="b"/>

This is the lead head code for the method, again in the CC namespace.

|    <s:symmetry>
|      <!-- some elements describing symmetry -->
|    </s:symmetry>

This could be a third-party classification for describing the symmetry of the
method.  Note that classifications may have element content, although all
the ones we have defined have empty content.

|   </classification>

|   <performances>

|     <performance xlink:arcrole="http://cccbr.org.uk/relations/firsttower">
|       <date>1924-03-15</date>
|       <location>
|         <place>Bolsover</place>
|         <county>Derbyshire</county>
|         <country>UK</country>
|       </location>
|     </performance>

This contains the details of the first tower bell peal in the method.  The
only thing which needs explanation here is the xlink:arcrole attribute.  This
has been borrowed from XLink as it provides exactly what we need:  a way of
describing the link between the method and the performance.  According to
XLink, the value has to be a URI, so we've made one up.

To save on typing, we have defined <firsttower> to be an element of a type
derived from that of <performance>, with the xlink:arcrole attribute fixed
at the value given above.  So the <performance ...> element here can be
replaced with <firsttower>.  Similarly for <firsthand>.

|     <firsthand>
|       <date>1963-05-05</date>
|     </firsthand>

This performance only has a date.  If somebody were to find out where the peal
was, then the other details could be added later.

|     <performance xlink:arcrole=
|                          "http://cccbr.org.uk/relations/record-length"
|                  xlink:type="simple"
|                  xlink:href="http://www.peals.net/database.xml#395"/>

This is a pointer to some other place where the details of a performance
may be found.  It is very important to support such indirection, so that the
method format would be able to interact with an XML peal database.

If a <performance> element is given with an xlink:arcrole specified, but
is nil, this indicated that there has been no such performance rung.  For
example,
  <firsthand xsi:nil="true"/>
indicates that the method has never been rung to a peal on handbells.

|   </performances>

|   <meta>
|     <m:timestamp xmlns:m="http://methods.ringing.org/NS/method">
|       2003-07-15T20:15:39Z
|     </m:timestamp>
|   </meta>

The <meta> element can contain *any* elements, as long as they belong in
a different namespace from ours.  Here is an example:  a timestamp which
has been added by a database.  It is not part of the `official' method 
data, but it will be interpreted by any application which understands it.
A ringing application program which decided to use this XML format for
storing methods might like to add things like standard calls here.

| </method>