XML Schema

This document describes how to define country dances using XML. You should read this document if you want to write a description of a dance using XML. The information specified in the XML describes exactly how a dance is danced. This allows programs to animate the dance. A dance is fully described by a element. The dance element has a single attribute: name - the name of the dance The contents of the element describe both the dance and the music. The music is described in the element. A single element may exist inside the element. This element contains the music in abc format. The other elements describe the movements made by the dancers. The order of these elements is important as, for any dancer, the elements describing the movements of that dancer must be in order. The first element for each dancer must be a element. There must be one element for each person in the dance. These elements provide the number and names of the dancers who are participating in the dance. Usually the names are 'man1', 'woman1', 'man2' etc. However, you are free to use whatever names you like. The names are used to identify the dancers in other elements that describe movements. The element can also be used to specify the initial position of a dancer. The full list of attributes are: name - place - facing - gender - To explain the 'place' and 'facing' attributes, we must first understand the co-ordinate system. The 'place' attribute specifies a point on the dance floor using two co-ordinates. For example, "200, -100". The first co-ordinate is the distance down the dance floor. By convension, in a longwise set, first couple are 100 points down the set, second couple are 200 points down the set and so on. The second co-ordinate is the distance across the set with zero indicating the center of the set, negative numbers on the men's side (left side as one faces the top of the set), and positive numbers on the women's side (right side as one faces the top of the set). For example, "200, -100" is second man's position. The 'facing' attribute specifies the direction in which the person is facing. This is measured in degrees with zero being down the set, 90 facing the women's side, 180 facing up the set, and 270 (or -90) facing the men's side.

The Basic Movements of a Single Person

Having defined the dancers and their starting positions, you now want to define some moves for them. There are a number of different elements that define various types of movements, but perhaps the most common is the 'move' element. This element tells the dancer to move to another position. The movement is done with the dancer always facing in the direction in which the dancer is moving. No side stepping or stepping backwards. The animation program will determine a curve that will take the dancer from the starting position to the final position. The list of attributes for the 'move' element are: participant place direction bar The move is timed so that the dancer gets to the given point at the start of the given bar. There are two other basic movements that a single dancer can make. The 'rotate' element is used when a dancer turns on the spot to face a different direction and the 'shift' element is used when a dancer moves in a straight line to another position while staying faced in the same direction. An example of when a 'shift' might be used is when a dancer is stepping down the set to make room for another dancer. If you were to use a 'move' element to move a dancer one position down the set then you would see the dancer dance an 's' curve (forwards, back behind the line, then forwards into the new place because with a 'move' element the dancer is always moving forwards).


The above elements alone would enable you to specify a full dance, except that no hands would be taken. However you would find it very tedious to specify all but the simplest dances using just the above elements. You would find yourself duplicating many figures over and over. You would also find yourself doing a lot of math to calculate the co-ordinates of many positions. Often the same figure is danced multiple times in a dance. Either two or more groups of dancers dance the figure at the same time, or the figure is danced at different times in the dance. To avoid specifying the movements for the figure over and over again, you can use the 'define_figure' element to specify the moves once and then use the 'figure' element each time the figure is danced. When a figure is danced, you must specify the position and orientation of the figure. There are two ways of doing this. One way is to specify two points that fix the location of the figure. The second way is to specify one point and a direction. The first way allows the figure to be re-sized. The second way means every time the figure is danced, it is the same size. A figure may be reflected. For example, a figure of eight might be defined with the dancers dancing the first part to the right but then you want to use the figure definition for an eight where the dancers start by dancing to the right. If the coder writing the figure definition expects it to be danced sometimes in a lefthanded version and sometimes in a right handed version then the coder should define the chirality of the figure as defined. The chirality can be 'left' or 'right'. When the figure is used, the required chirality is specified. If this is the opposite of that for the figure definition then the figure is reflected. As an example, let's define a very simple figure. Two people start the figure facing each other. They take two bars to cross by the right shoulder and end facing out. They then both take another two bars to turn on the spot to face back towards each other. We want to be able to use this figure for people crossing across the set or diagonally, and maybe even up and down the set. The diagonal distance across the set (for example the distance between first corners) is more than the distance across the set. We must therefore allow the figure to be resized. We will use two fixes to specify the location of the figure. We could use any two points as the fix point. The simplest and most obvious two fix points would be the starting and ending positions of the two dancers. The co-ordinate system used inside the figure is also arbitary. For this example, we will define the figure with person1 starting at (340, 500) and person2 starting at (340, 700). These are of course strange points. A more sensible pair of points would be (-100, 0) and (100, 0). However we will use the strange points to demonstrate that the co-ordinate system used inside the figure definition is totally arbitary. Here is the figure definition: ]]> Note the 'turn' attribute on the 'rotate' elements. A value of -180 indicates that the dancer is to turn to the new direction by making half a turn to the right. This figure definition has three 'define_fix' elements. The first two are point fixes. By fixing two points, the postion, orientation, and size of the figure can be determined. The third 'define_fix' element specifies the chirality. You can use any name you like. In this example this name 'shoulder' is chosen because when telling two people to cross without giving hands, the instructions are usually given by saying something like 'cross giving right shoulders' or 'cross giving left shoulders'. Now suppose man1 is at (100, -100) and woman2 is at (200, 100). We want to use our figure definition to get the two people to cross and then turn back in towards each other. We can do this with the following element:
The placement attribute gives the values for the three fixes. Unless a default value is specified when the figure is defined, all fixes defined in the figure must have values set in the placement attribute. The figure will be shifted, rotated, re-sized and reflected as appropriate so that the fix values in the placement attribute match the values given when the figure is defined.


There are two ways of indicating that hands should be taken:
  • 1. When people take hands while forming a unit
  • 2. When people take hands while they are not in a unit.
1. When people form a unit, all the people in the unit must remain in exactly the same position relative to each other although the unit as a whole is free to move around. When hands are taken within a unit, the location of the hands must also be fixed within the unit.

An example is when a couple are forming a unit using the 'two hand hold' in the pousette in the Flowers of Edinburgh. You will see that the hands are held at positions that are equidistant from each person and 20 grid points out to the side. The hands are maintained in this position from the time the unit is formed to the time it is disbanded.

2. When people are not in a unit, hand taking is a little more complicated. The people who are taking hands may be moving relative to each other. The position of the hands is going to move, both relative to the dance floor and relative to the dancers. This would make it difficult for the XML coder to specify the location of the hands. Therefore we do not allow the location of the hands to be specified. The hands are assumed to be held at a comfortable position. This means hands cannot be held in, say, an allamande position. However, hand holds such as the allamande are, in practice, only done when the participants are forming a unit so this is not a practical limitation.

It may also be difficult for the XML coder to determine the exact time at which hands should be taken. Take, for example, mirror reels on the sides, taking hands with partners when near the center line. It would be inconvenient for the XML coder to have to specify the exact times at which hands should be taken and the exact times at which hands should be dropped. The XML coder would find it easier if she could simply indicate that two people should take hands whenever they are close enough to comfortably do so, and drop hands when they become too far apart. Therefore this is just what the element indicates. To indicate that couples should take hands on the mirror reels, just indicate that they should take hands for the entire 8 bars.

Consider rights and lefts (cirular hay with hands, to English dancers) involving two couples, each couple starting by crossing with the right hand. You can specify this by telling man 1 that he takes right hand with woman 1 for all eight bars and left hand with man 2 for all eight bars. Hands will only be taken when 'in range' so this will work.

Consider a grand chain (cirular hay with hands, to English dancers) involving three couples. Couple 1 start facing each other, couple 2 start facing down, couple 3 start facing up. So man 1, woman 2, and man 3 are travelling clockwise while woman 1, man 2, and woman 3 are travelling counterclockwise. The same trick will not work here because man 1 gives right hand to woman 1 the first time and give left hand the second time they pass. They would be trying to give both hands on both passes! Hands have to be specified for each passing (i.e. for each period of 2 or 4 bars).

Consider a couple making an arch. To get other couples through the arch, the two people making the arch must be positioned at such a distance apart that they may be out of the range in which hands would be taken. When people are too far apart to take hands, hands are completely withdrawn. They are not reached as far as possible. The solution in this case is to create a unit for the arch. In units, hands are always taken when indicated, regardless of the distance. The arms just get very long!

In the examples above there are two hands involved at each hand hold. You may specify more hands. For example, in 'three hands across' you would have three hands involved at a single hand hold. There is no limit to the number of hands that may be involved in a single hand hold though it is unlikely that any dance would have more than four hands at a single point. You may not have a hand hold with a single hand (country dances do not have moves that involve hold out hands without taking someone else's hand). A person is not allowed to have both of his/her hands participating in the same hand hold (this does not happen in country dances so would likely indicate an error by the coder of the XML).


In many dances a group of people act as a unit, all moving together while staying in the same position relative to each other. An example is a couple taking a two-hand hold and reeling with two other persons such as in ... A less obvious use of a unit is when defining the pousette.

The persons within the unit must remain in the same position relative to each other although the unit as a whole may move, rotate, or shift just like a person. Persons in the unit may take hands. Although in most cases hands are taken, there are cases where hands are not taken. For example, in some Scottish and English dances a couple will dance a reel or hey 'in tandem', or 'as a unit'. One dancer will follow the other closely behind. Note that the first couple in the Pelorous reels in Pelorous Jack do not form a unit. Even if the first couple always maintain the same distance from each other, they are not facing the same direction relative to each other - sometimes the man is facing the woman's back and sometimes the woman is facing the man's back.

Once a unit is formed it may be moved around as a single entity. A unit may moved, rotated, shifted, and may participate as a single participant in a figure. In fact a unit may do anything a person can do except that

  • A unit may not in turn participate in another unit
  • A unit may not take hands (the persons within the unit may take hands with each other but neither the unit as a whole nor anyone within the unit may take hands with any participant outside the unit).

A unit may be specified in the list of participants of a figure. However, a unit may not be specified as a participant in a figure if that participant is required by the figure to either take hands or to form a unit.

People in a unit may take hands with other people in the unit. The hand holds are part of the unit definition. If people in a unit take hands then they must take hands in the same way whenever the unit is formed.


Each movement (or rotation, or shift) starts where the previous movement left the person. This ensures that no one suddenly 'jumps' from one position to another. However, where standard figures are used, one figure may end with a person in one position and the immediatly following figure may start with the person somewhere else. For example, consider the Flowers of Edinburgh where the 'lead down and back' leaves the first couple at their original postions on the sides but the pousette starts with them positioned in the middle already taking hands. There is no time in the middle to transition from one figure to the next. When dancing the dance, dancers adjust the end of the 'lead down and back' figure so that they end in the middle. They never actually go back to their positions on the sides.

One way of dealing with this in the XML would be to change the 'lead down and back' figure so that it leaves the couple positioned in the center. This would mean many definitions of 'lead down and back' and the XML coder would have to select the appropriate one depending on which figure followed. Also, the start of the 'lead down and back' figure may also have to be varied depending on the preceding figure causing the number of variation of 'lead down and back' to multiply.

Another solution would be to define the 'lead down and back' figure for just the middle 6 bars, say. The movements for the first and last bar are not considered part of the figure and must be made before and after the figure is used. This is still not ideal. In some uses of a figure there may be a long transition needed and in other cases a short transition. Figures would have to be defined for the uses that require the longest transitions, sometimes leaving half the figure to be specified outside the figure definition. This is not great when in most uses of the figure there may be no transition necessary.

The solution is to allow two figures to be used where the first figure leaves someone in one place and the second figure starts with that same person in a different place. A transition will be calculated. The XML coder must place a element between the uses of the two figures. The element will contain a list of all the people to whom the transition rule applies. It specifies specifies the transition period. The transition period may extend before the transition point (the time that one figure ends and the next starts), it may extend after, or it may extend both before and after. At least one of the 'before' attribute and the 'after' attribute must be specified. These attributes take a bar count (fractions of a bar are allowed). In the Flowers of Edinburgh example, the pousette must start on time, this means we want the transition period to be only before, going into the 'lead down and back' figure.

The animator program will calculate where the person is at the start and at the end of the transition period. It will then effectively replace the movements that would have occured during the transition period with a single 'move'.

If a person is forming a unit then no transition period can extend into the time in which a person forms a unit. That means, for example, if a figure starts with a unit then any transition for people in that unit cannot have the 'after' attribute specified. Likewise if a figure ends with a unit then the 'before' attribute cannot be specified. The reason for this is that no one can form a unit on their own and they would be left dangling if the other person were transitioning when supposed to be in the unit.

This is the planned implementation of transitions. There will almost certainly need to be improvements to this. For example, if figures start or end with shifts and rotations then a move may not be the best form of transition.