Element Reference
note
A note element can be a child element of nearly every other element, and is used to describe any additional information that isn’t explicitly quantified by the element or its attributes or other child elements.
Attributes
None
Children
None
Content
A textual representation of what additional information is recorded.
Discussion
note elements are catch-all elements to record any sort of information, scribble on margin, explanation of weirdness, etc...
venue
venue is used to describe a location where roller derby is played. It is a superset of the location information (venue name, city, state/provence). venue can be a top level element. It is based on “address” elements of DocBook
Attributes
| url | A url of the website of the venue |
Children
The following elements occur in venue: city, country, email, fax, otheraddr, phone, pob, postcode, state, street, note, name, alias.
bout
bout elements represent a game - all its participants (skaters and officials) and the events that happen. It should have a venue, two teams rosters (this first information corresponding to the IBRF pages of the stat-book), and then two periods (which contain all the rest of the stat-book data).
Attributes
| sanctioned | “yes” or “no” (defaults to “no” if not present) |
| ruleset | An optional string giving either the name of the ruleset (base and optional modifiers) |
Children
The following elements occur in bout: venue, team, period, note, uuid
There should be two team elements, one for each team (one for the “home” team, one for the “away” team). period elements are in order of the period (normally a completed bout would have two period elements).
If ruleset attribute is not specified, it defaults to “MAR2014”. Simple modifications of the ruleset can be encoded into the string name by appending them after a “/”:
| ##p | Period length, in minutes |
| ##b | Duration of penalty box visit length in seconds |
| #f | Number of penalties until the skater fouls out |
| #t | Number of timeouts per team |
So, for example, the most common variation on the ruleset is the “20 minute” period that is normally used for home team bouts (with a limit of 5 box trips before fouling out). This would be encoded as “MAR2014/20p5t”.
ruleset
ruleset elements represent the rules used for the game.
Attributes
| version | Textual identifier of name of the rule set in the format: MMMYYYY |
| period-count | Number of periods (default “2”) |
| period | Length of period (default “30:00’) |
| jam | Length of jam (default “2:00”) |
| lineup | Length of lineup (default “0:30”) |
| timeout | Length of team timeout (default “1:00”) |
| timeout-count | Number of team timeouts, total in bout (default: “3”) |
| official-review-count | Number of official reviews per period (default: “1”) |
| official-review-retained | Is the official review retained if valid (default: “true”) |
| official-review-maximum | Limit on number of official reviews per period (default: “2”) |
| penalty | Length of penalty (default: “0:30”) |
| minors | Are there minor penalties? (default: “false”) |
| minors-per-major | How many minors are a major (default: “4”) |
| penalty-limit | How many box trips (not minutes) until the skater fouls out (default: “7”). |
Children
None.
Discussion
The ruleset element defaults to the current (March 2014) ruleset, with 30 second periods, and retaining official reviews (if the team has a valid objection).
period
period elements represent divisions of a bout. There is an implicit “period number” based on the order in which the period element occurs in the parent bout element.
Attributes
| timestamp | an integer representing (in seconds) when the period starts. All elements contained within this period is relative to this value (this allows for recording either a timestamp relative to the period, or an absolute timestamp) |
Children
The following elements occur in period: jam, time-out, official-review, note, action, error
Discussion
Lineup time isn’t explicitly declared here, since normally events do not happen during them (and those that do are recorded as happening in either the previous or next jam). Their duration should always be 0:30, which can be verified by subtracting the previous jams start timestamp plus its duration from the timestamp of the next jam’s start.
jam
jam elements represent jams within a period (from starting whistle until the fourth whistle that ends the jam). There is an implicit “jam number” based on the order in which the jam element occurs in the parent period element.
Attributes
| timestamp | a timestamp indicating when the jam starts |
| duration | the length of jam (in seconds) |
Children
The following elements occur in jam: line-up, pack-lap, penalty, pass, star-pass, action, error, lead, lost-lead, call, enter-box, exit-box, box-time, leave-track, return-track, injury, note,
Except for the line-up element (which should appear as the initial children elements), the other events should occur in the order in which they occurred on the track. This is, however, just preferred behavior, but should be followed if there is no timestamp.
line-up
line-up defines the skaters on the track for a given team.
Attributes
| skater reference | One of the various forms of skater references |
| start-in-box | boolean indicating that the given skater started in the box |
| position | One of the following possible values: “jammer”, “pivot”, “blocker” |
Children
note
Discussion
Line ups could be tracked in a variety of ways (one element for each team, and then five elements, one per position, for example), or the blockers could be enumerated (“blocker-1”,”blocker-2”, etc... unless the pivot is “blocker-1” in which case the first blocker would be “blocker-2”). By having one entry, despite having factorable team IDs, there are the fewest assumptions on how blocker information is processed (i.e., if a pivot isn’t fielded, is the skater “blocker-1” or “blocker-5”). This also slightly flattens out the structure (which could lead to a slight obfuscation), and also removes any ordering constraints of where line up information appears within the jam information. The team and skater attributes then mirror the same attributes in other jam events.
The start-in-box flag should be optional (there should be information that can be derived from the box trip events), but it is an imperfect world, and this flag will correspond directly to the “S” entry in the lineup sheet.
pack-lap
pack-lap records a lap of the pack (such as is recorded on the bout time sheet). There can be multiple pack-lap elements for each lap, or optionally a single element with the total.
Attributes
| timestamp | a timestamp indicating when the lap occurs |
| count | Optional number of laps (or fraction of a lap) - if missing, the default value is “1”. The total pack laps for jam are the sum of all pack-lap count attributes. |
Children
note
penalty
Corresponds to a penalty
Attributes
| timestamp | a timestamp indicating when the lap occurs |
| skater reference | One of the various forms of skater references |
| penalty | Letter code corresponding to the penalty |
| severity | Optional severity indication: “no” for no-pass/no-penalty or no-impact; “minor” for old minor penalties; “major” for major penalties (default if not specified); “expulsion” for expulsion penalties |
| rescinded | A boolean value that indicates that the penalty was rescinded due to either an official review or other official consultations |
Children
note, involved
Content
The verbal cue used for the penalty (to differentiate the various “illegal procedure” penalties, for example) as per the standard practice verbal cue. Additional details can be placed in a note element if needed.
Discussion
The skater reference is the person for whom the penalty is recorded (so for some illegal procedures, this may be a captain who actually was not involved in the incident). In such cases, additional information can be presented in note element. Record of other skaters directly involved in the penalty is presented in the involved children.
involved
Indicates optional information about other skaters involved in a penalty
Attributes
| skater reference | One of the various forms of skater references |
Children
note
Content
None.
Discussion
Penalties rare involve a single skater - for example, for contact related penalties, there is the recipient of the impact. Assuming this information can be gathered (for example, during bout footage review), it can be recorded in the involved child element of the penalty element. This includes both team mates as well as opposing skaters, depending on the penalty. For example:
• Contact penalty - opposing skaters that impacted by the contact
• Cutting the Track - the opposing skaters as well as the team mates who were passed while out of bounds
• Stop Assist - the team mate assisted
• Multi-player Block - the team mate involved with the block, as well as the opposing skater that was blocked
This element exists primarily to provide a more structured note-like element information
pass
Corresponds to a completed pass (either initial or scoring), or a pass that wasn’t completed when the jam ended.
Attributes
| timestamp | a timestamp indicating when the lap occurs |
| number | Indicates the pass number of a completed pass |
| score | Number of points scored in the pass |
| team | Team reference |
| completed | A boolean indicating if the pass was completed (defaulting to “yes”) |
Children
note, ghost-point
Discussion
pass elements are used to record both initial passes as well as subsequent scoring passes, and correspond to the point in time when the pass is completed (the skater exists the front of the engagement zone). Non-completed passes would be recorded by having a completed attribute set to “no”. A “no pass” can either be recorded as having no pass elements at all, or a single pass element with number set to “1” and completed set to “no”.
It is possible to record a (jammer lap) point in the initial pass by having a pass element with the number attribute set to “1” and the score attribute set to “1”. Note that this event is independent of the lead (or loss-lead) elements, since it is possible to get lead but not complete an initial pass. If the skater clear the pack before the other skater gains lead and is not lead (due to a no-pass/no-penalty) there would be both a loss-lead and a pass element.
In the extremely rare case of getting a jammer lap point but not completing the initial lap, using a pass element with a number attribute set to “1”, completed set to “no”, and a score attribute set to “1”.
ghost-point
Records a ghost point (point that is awarded without having physically passed a corresponding opposing skater).
Attributes
| skater reference | One of the various forms of skater references indicating the skater not passed |
| type | An optional record of ghost points - comma separated letters that correspond to the old stat-book ghost point codes: L - Jammer Lap Point J - Jammer in the Box B - Blocker in the Box P - Pivot in the Box N - Not on the track point O - Out of play points G - Unknown ghost point |
Children
note
Discussion
Since ghost points are not normally tracked anymore, that attribute is primarily used for importing older versions of the WFTDA stat book. Assuming all the other information is collected, it is also possible to derive this attribute from various other elements (assuming they have time stamps). The jammer lap would be the most difficult to deduce, other than there being five points, without the jammer leaving the track (and probably also based on the pass record of the two different jammers). There are possibly cases, however, where there was a jammer lap and a no-pass/no-penalty that is recorded as four points and the lap isn’t possible to deduce from pass completion timestamps.
Note that the element should have either a skater reference or type attribute - both aren’t always required if all other elements are recorded, but should be used if possible.
star-pass
Records an attempted or successful star pass.
Attributes
| timestamp | a timestamp indicating when the star pass occurs (ideally when the helmet cover is removed from the jammer’s head) |
| skater reference | One of the various forms of skater references indicating the skater jammer who initiated the star pass |
| failure | Present if the star pass fails, with either a value of “jammer” or “pivot” to indicate who was at fault for failing to perform the star pass (with a note describing more detail). |
Children
note
Discussion
There should be a corresponding loss-lead element for this if the jammer was lead. This element doesn’t quantify all the possible details of the star pass, but explicitly recording the reason for the failure is a first attempt. Obviously a failed star-pass can’t be easily determined by recreating a stat-book.
action, error
Record of action (as per “action and error” tracking).
Attributes
| timestamp | a timestamp indicating when the action occurs (if known) |
| skater reference | One of the various forms of skater references indicating the skater jammer who performed the action |
| count | When a child element of a period (as opposed to a jam), a count of the number of actions |
Children
note, involved
Content
The name/description of the action/error
Discussion
Records one of the actions found in the action sheet or the jammer action section of the error sheet (which are actually actions), or error. The name of the action/error is the content of the element. Actions/errors can be recorded as they happen (and include other involved in the action via the involved child element) in which case they are child elements of the jam element. Those elements should also have a timestamp attribute (and any count attributes should be ignored and treated as a single occurrence of the action). Otherwise, if used as a “summary” (as gathered from the stat-book), count elements refer to the total occurrence (and default to zero).
lead
Corresponds to a jammer obtaining lead jammer status.
Attributes
| timestamp | a timestamp indicating when the lead jammer status is awarded |
| skater reference | One of the various forms of skater references indicating the skater who gained lead |
Children
note
Discussion
While in theory one could simply use the a team reference, it is more efficient for latter analysis to explicit indicate the skater who gains lead. Note that this element is independent of the (initial) pass element, since lead jammer status occurs before the initial pass is completed.
lost-lead
Corresponds to a jammer obtaining losing lead jammer status (or the ability to gain lead jammer status).
Attributes
| timestamp | a timestamp indicating when the lead is lost |
| skater reference | One of the various forms of skater references indicating the skater who gained lead |
Children
note
Discussion
While in theory one could simply use the a team reference (or if a lead element is present in the jam, omitted all together), it is more efficient for latter analysis to explicit indicate the skater who lost lead.
call
Used to record when a jam is called off by a skater or official (as opposed to running to its natural conclusion at two minutes, or due to an injury)
Attributes
| skater reference | One of the various forms of skater references (optional) |
| official | used only if the jam was called by the official for special cases. Possible values include: “malfunction”, “major”, “interference”, “debris”, “too many skaters”, “fighting”, “unknown”, “other” |
| timestamp | when the call off happened (the end of the fourth whistle) |
Children
note
Discussion
If the skater/team reference attributes are missing, it is assumed that the jam has been called off by whomever was the lead. If the given skater/team isn’t lead, then this would normally also result in an illegal procedure penalty (and those attributes aren’t optional). If the jam ends with an injury, the injury element should be used. A jam that runs to the natural two minute conclusion would not have either element. If the jam ended due to one of the exceptional cases where an official can end the jam prematurely, the official attribute would be set with the possible case (as detailed in section 9.2.6 of the WFTDA 15 June 2012 ruleset), and the content of the element should include additional explanatory text.
enter-box
Corresponds to a when a skater is seated in the penalty box.
Attributes
| timestamp | a timestamp indicating when the skater sits |
| skater reference | One of the various forms of skater references indicating the skater who sat in the penalty box |
| duration | The number of seconds the skater should sit (defaults to “60”/”1:00” or some multiple of there of). |
Children
note, substitute
Discussion
This corresponds to the moment the skater sits (and the penalty box timer starts timing their penalty). If a skater enters between jams, this element will occur in the latter jam element (and the timestamp would correspond to jam relative “+0”). If the skater is waved off, this element does not occur until there is actually room for them to sit and they return.
Note that the duration element is normally one minute (or some multiple there-of). There are two notable exceptions:
• A skater left the box prematurely previously, in which case this would be the time remaining (plus any additional penalty time for illegal procedures)
• A jammer whose time will be reduced to match the time served by the opposing jammer already in the box.
exit-box
Corresponds to a when a skater is leaves in the penalty box.
Attributes
| timestamp | a timestamp indicating when the skater is released/leaves |
| skater reference | One of the various forms of skater references indicating the skater who sat in the penalty box |
| duration | The amount of time the skater actually spent sitting in the box (default to the duration attribute of the corresponding enter-box element) |
| premature | If the skater left the box prematurely: “official” to indicate if the official released them early by mistake; “skater” if the skater left early (and thus should have a corresponding illegal procedure call with the same timestamp); “rescinded” to indicate that the skater was released due to the underlying penalty being rescinded as a result of an official review or other official consultation; “mistake” if the skater was sitting in the box by mistake (such as hearing a warning and assuming it was a penalty) - this can also be used even if the entire penalty duration was served |
| no-skater | If the skater who was serving the time fouled out, was expelled, or injured (or otherwise was unable to serve the time), this indicates that there was no skater that actually returned to play at the end of the penalty. This will happen if the penalty is timed entirely within the jam (otherwise the enter-box will have a substitute child element) |
Children
note
Discussion
For blocker, this should occur sixty seconds from the corresponding enter-box element (or some multiple of that), unless the skater leaves the box prematurely. For jammers this can occur whenever they are released (potentially reduced by jammer swaps). The duration attribute should reflect the total duration.
substitute
Indicates that a skater was substituted for another skater in the penalty box.
Attributes
| skater reference | One of the various forms of skater references indicating the skater who actually will serve the penalty time in the box for the skater indicated in the parent enter-box element. |
| reason | Indicates a reason for the substitute: “injury”, “foul out”, “expulsion”, “other” |
Children
note
Discussion
If a skater fouls out, or is injured with a penalty due, this element indicates that another skater was substituted for this skater the start of the next jam (If a penalty finishes within the same jam without a skater substituting, this element will not be present). The reason attribute can normally be derived by looking at the most recent penalty element of the corresponding parent enter-box skater reference, but this explicitly indicates that they left the box due to an injury.
[ NB: This scheme still causes a few problems and will need to be addressed later ]
leave-track
Marks when a skater leaves the track for any reason.
Attributes
| timestamp | a timestamp indicating when the leaving occurs |
| skater reference | One of the various forms of skater references indicating the skater who left the track |
| reason | The reason for leaving the track: “penalty” (default if not specified), “injury”, “malfunction”, “other” |
| opposing-pass | The number of the pass the opposing jammer is on (as per lineup tracking) |
Children
note
Discussion
This can provide a more accurate reconstruction of various not-on-the-track points, since it reflects all instances of leaving the track (as opposed to just when the skater is seated in the penalty box).
return-track
Marks when a skater returns the track for any reason.
Attributes
| timestamp | a timestamp indicating when the return happens |
| skater reference | One of the various forms of skater references indicating the skater who left the track |
| opposing-pass | The number of the pass the opposing jammer is on (as per lineup tracking) |
Children
note
Discussion
This can provide a more accurate reconstruction of various not-on-the-track points, since it reflects all instances of returning to the track (as opposed to just when the skater is released from the penalty box).
injury
Indicates that a jam was stopped due to injury.
Attributes
| timestamp | a timestamp indicating when the jam ends |
| skater reference | One of the various forms of skater references indicating the skater who was injured |
Children
note
Discussion
A leave-track element should be used for a skater who can leave the track on their own power without forcing the jam to be called prematurely. This element can also be used as a child of the time-out element to indicate that an official time out was called to deal with an injury that did not require the jam to be stopped.
time-out
A time out was taken after the jam.
Attributes
| timestamp | a timestamp indicating when the time-out starts |
| team | A reference to the team taking the time out, or an official time out if not present |
| duration | The duration of the time out (defaults to “1:00” for team time outs) |
Children
note, injury
Discussion
Used for all time outs. If the time out was called due to an injury occurring after the jam (or an injury that did not require stopping the jam), an injury child element should be present. This is not used for an official review.
official-review
An official review was taken after the jam.
Attributes
| timestamp | a timestamp indicating when the official review starts |
| team | A reference to the team taking the official review |
| duration | The duration of the official review |
Children
note, resolution
Discussion
Used for officials reviews. The details of the review are recorded in the note element. The resolution of the review are recorded in the resolution element.
resolution
The resolution of an official review.
Attributes
None
Children
None
Content
A textual representation of what the results of the official review were.
timer
A timer.
Attributes
| id | The name of the timer. DerbyXML has several predefined timers: “period”, “jam”, “lineup”, “timeout”, “intermission”. |
| duration | How long, in seconds, the timer will run before it stops |
| counts-down | If ‘yes’, then the timer counts down from the duration value, otherwise it counts up |
| running | Is the timer currently running |
Children
-
Content
A textual representation of what the current timer value.
Discussion
DerbyXML uses the CRG scoreboard timer model for timers. Timers always count up from 0 - the “counts-down” attribute is used to indicate how the value should be formatted for display
label
An informative label displayed, usually on the scoreboard.
Attributes
| id | The name of the label |
|
|
|
|
Children
-
Content
A textual representation of what the label should display.
Discussion
This element is used primarily for “limited” clients (like scoreboards). Typical labels would include “home-score”, “away-score”, “home-team”, “away-team”, etc...