XML Format (Version 2.2)

Date: Sept 14, 2025 - Minor update/clarifications with Bravo Release

BJCP Database XML Interface Specification 2.2.

Introduction

The BJCP database accepts competition organizer reports in an XML format. The database doesn’t presently use XML, but rather parses the data in XML format. Since the parsing is done using scripting language within the database, it is important that all programs that write XML data use the standard format described in this specification. Future versions of the BJCP database may import the data directly using XML.

The standard BJCP online competition organizer’s reporting system creates an XML file in the format described in this specification. Any other program that wishes to interface with the BJCP database must follow similar rules, enforce BJCP business logic, and perform necessary field validation. The back-end does limited error checking; the frontend program is responsible for formatting data and enforcing validation rules and business logic.

The XML file is simply a text file with XML data that can be copes and pasted or uploaded at the competition report page at https://app.bjcp.org/competitions/report. Before this, the developer must coordinate with the BJCP IT Director to ensure the data file meets the specification provided in this document and imports properly into the BJCP database.

XML File Format

The organizer’s report is delineated by <OrgReport> </OrgReport> tags. Anything not within these tags will be ignored. b. Six major sections are contained within the organizer’s report:
1. The competition data section contains overall information about the competition. There is one of these data sections per report. It is delimited by <CompData></CompData> tags.
2. The BJCP points section contains judging and non-judging points assigned to BJCP judges. There is one BJCP points section, and it can contain multiple judge records. It is delimited by <BJCPpoints></BJCPpoints> tags.
3. The Non-BJCP points section contains judging and non-judging points assigned to people not in the BJCP. There is one Non-BJCP points section, and it can contain multiple judge records. It is delimited by <NonBJCP></NonBJCP> tags.
4. The comments section contains free-format text comments that may be passed to the program administrator. One possible use of the field is to contain the name of the person entering the data, discrepancies or problems encountered in entering the data, or notes to the database administrator. There is one comments section, and it only contains data. It is delimited by <Comments></Comments>tags, and contains free format text data. It is highly encouraged that this section contain the email address of the person submitting the report. It is also highly encouraged that this section contain the name and version of the software which created this report.
5. The IP Address section contains the IP address of the host system where the data was collected. This is a rudimentary auditing feature in case the authenticity of the data is questioned. There is one IP address section, and it only contains data. It is delimited by <IPAddress></IPAddress> tags, and contains data in the format nnn.nnn.nnn.nnn, where n is a digit (leading zeroes suppressed).
6. The submission date section contains a date- and time-stamp when the data was collected and transmitted. This is a rudimentary auditing feature in case the authenticity of the data is questioned. There is one submission date section, and it only contains data. It is delimited by <SubmissionDate></SubmissionDate> tags, and contains data in the format Day, dd month yyyy hh:mm am/pm, where Day is the day of the week (e.g. Tuesday), dd month yyyy is the date (e.g. 20 April 2004) and hh:mm am/pm is the time in 12-hour format (e.g. 5:22 pm). c. The Competition Data section contains seven data elements:
7. Competition ID: the six-digit competition registration number. There is one competition ID per section and is delimited by <CompID></CompID> tags.
8. Competition Name: the free-format text name of the competition. There is one competition name per section and is delimited by <CompName></CompName> tags.
9. Competition date: the date the competition was held in the format yyyymm- dd where the yyyy, mm and dd fields are numbers representing the year, month and day (leading zeroes retained). There is one competition date per section and is delimited by <CompDate></CompDate> tags.
10. Competition entries: the number of entries the competition has. There is one competition entries per section and is delimited by <CompEntries></CompEntries> tags.
11. Competition days: the number of days the competition judging was held. There is one competition days per section and is delimited by <CompDays></CompDays>tags. Note this is NOT the number days elapsed between first day or judging and last day of judging - but actual number of days judging was held for the competition.
12. Competition sessions: the number of judging sessions (periods or rounds in which judging was held, not counting the best of show round). There is one competition sessions per section and is delimited by <CompSessions></CompSessions> tags. Note that this is not number of flights judges by each judge panel during a session (i.e., Morning, Afternoon, etc.) but actual sessions. Maximum 3 sessions per day are allowed.
13. Competition flights (This tag is deprecated in favor of BOSData and BOSBeers, BOSCiders, BOSMeads tags as described below): the number of beers in the best of show round (usually the same as the number of flights; but the number of entries on the BOS table is the actual metric desired). There is one competition flights per section and is delimited by <CompFlights></CompFlights> tags. If there are multiple BOS rounds, this field should contain the sum of all entries in all BOS panels. The information on number/type of entries on each BOS panel should be stored in the Comments section.
The BOS Data section contains number of Best of Shows for the competition, their beverage type and number of entries on each of those BOS Judging panels.
1. <BOSData></BOSData> tags will identify the BOS Data Section
2. Within BOS Data section <BOSBeer>number_of_entries</BOSBeer> will be used to report a Beer BOS where "number_of_entries" is an integer number reporting number of entries on that best of show panel.
3. Within BOS Data section <BOSMead>number_of_entries</BOSMead> will be used to report a Mead BOS where "number_of_entries" is an integer number reporting the number of entries on that best of show panel.
4. Within BOS Data section <BOSCider>number_of_entries</BOSCider> will be used to report a Cider BOS where "number_of_entries" is an integer number reporting the number of entries on that best of show panel.
5. One can report more than one BOS or same type.
6. Maximum number of BOS is limited to FIVE.
The BJCP points section contains one or more judge data records, each delimited by . Each of the judge data records contains five elements:
1. Judge ID: the BJCP ID of the judge (see field validation rules). Structured text. Delimiting tags are . The Judge ID MUST be provided for a BJCP judge to receive credit.
2. Judge Name: the full name of the judge. Free-format text. Delimiting tags are .
3. Judge Role: the specific duty the judge performed in the competition (see field validation rules; there are only certain values that can be used). Delimiting tags are .
4. Judge Points: the judging points assigned to the judge (see field validation rules). Numeric data. Delimiting tags are .
5. Non-Judge Points: the non-judging points assigned to the judge (see field validation rules). Numeric data. Delimiting tags are .
The Non-BJCP points section contains one or more judge data records, each delimited by . Each of the judge data records contains four elements:
1. Judge Name: the full name of the judge. Free-format text. Delimiting tags are .
2. Judge Role: the specific duty the judge performed in the competition (see field validation rules; there are only certain values that can be used). Delimiting tags are .
3. Judge Points: the judging points assigned to the judge (see field validation rules). Numeric data. Delimiting tags are .
4. Non-Judge Points: the non-judging points assigned to the judge (see field validation rules). Numeric data. Delimiting tags are

Field Validation Rules

Judge ID is a five character text field: [A-G][0-9][0-9][0-9][0-9], or A0001 to G9999.
Comp ID is a six digit number: 100000 and greater.
Judge Role is a text field that can accept only certain values:
1. "Judge"
2. "Judge + BOS"
3. "BOS Judge"
4. "Steward"
5. "Organizer"
6. "Staff"
7. "Staff + Judge"
8. "Staff + BOS"
9. "Staff + Judge + BOS"
10. "Staff + Steward".
The quotes aren't part of the field values, but the spaces within the quotes should be preserved.
Judge Points and Non-Judge Points are non-negative numbers with one decimal place (i.e. 0.0 and greater).
Each person can appear only once in a report.
An organizer can only receive organizer points - organizers is not allowed to receive judging points.

Business Logic

The full set of rules describing competition reporting can be found at http://www.bjcp.org/rules.html. Much of the data contained in the Competition Data section is used to validate certain assignment of points.

Stewards receive 0.5 non-judging points per day, up to a maximum of 1.0 points per competition. Steward points are awarded separately from any staff points, although they may be combined. Steward points awarded never detract from allowable staff points.
Judges generally get 1 judging point per competition, but the actual rules are:
1. 0.5 points per session
2. 1.5 points per day maximum
3. 1.0 points per competition minimum
[b and c combine to give 1 point for most competitions since it is rare to have 3 sessions per day; max points per comp are per the table at the end]
BOS judge rules (BOS judges earn judging points)
1. BOS judges get an extra 0.5 points if they also judged at least one normal flight
2. BOS judges get 1.0 points if they only judge BOS
3. Multiple BOS tables are allowed, but only for separate purposes (i.e., not for doing a multi-round BOS). Examples include homebrewed beer, commercial beer, mead, cider, and mead/cider.
4. Each BOS table is subject to the overall BOS rules
5. Up to 3 judges can get BOS points for 5-14 entries on a BOS table containing beer
6. Up to 3 judges can get BOS points for 3-14 entries on a mead/cider BOS table
7. Up to 5 judges can get BOS points for 15+ entries on any BOS table
8. 30 entries and either 5 BOS beers or 3 BOS meads/ciders are needed to award BOS points at all
9. A single judge can only receive the BOS bonus once per competition.
Maximum points per competition for organizers, staff, and judges:

Entries

Organizer

Staff

Judge (Not including BOS Points)

1-49

2.0

1.0

1.5

50-99

2.5

2.0

100-149

3.0

2.5

150-199

3.5

4.0

3.0

200-299

4.0

5.0

3.5

300-399

4.5

6.0

4.0

400-499

5.0

7.0

4.5

500-599

6.0

8.0

5.5

600+

6.0

Additional 1 per each 100 entries over 600

5.5

For each competition that has 600 or more entries, an additional 1.0 staff points are available for each 100 additional entries (600 = 9, 700 = 10, etc.).
The organizer and judge points are maximums allowed, regardless of competition size (i.e., they do not scale up as do staff points).
Staff points are the sum of all staff points that can be awarded, not the number to be awarded to each person
Staff points must be awarded in 0.5 point increments
Judge points are maximums, but must be earned according to (2) above
No individual participant can earn more total points (judging and non-judging, combined) than the organizer, although others can earn the same number of points as the organizer.
Only the Roles listed in the field validation rules [3] are allowed. For example, organizer points cannot be combined with other points, and judging and stewarding points cannot be combined.

Sample XML File

<OrgReport> <CompData> <CompID>101440</CompID> <CompName> Gambrinus Challenge</CompName> <CompDate>2003-11-15</CompDate> <CompEntries> 82 </CompEntries> <CompDays> 2</CompDays> <CompSessions> 3</CompSessions> <CompFlights>19</CompFlights> </CompData> <BOSData> <BOSBeer>14</BOSBeer> <BOSMead>5</BOSMead> </BOSData> <BJCPPoints> <JudgeData> <JudgeID>D0646</JudgeID> <JudgeName>Dave Neilly</JudgeName> <JudgeRole>Judge + BOS</JudgeRole> <JudgingPoints>1.5</JudgingPoints> <NonJudgingPoints>0</NonJudgingPoints> </JudgeData> <JudgeData> <JudgeID>D0491</JudgeID> <JudgeName>Rod Savoie</JudgeName> <JudgeRole>Judge</JudgeRole> <JudgingPoints>1.0</JudgingPoints> <NonJudgingPoints>0</NonJudgingPoints> </JudgeData> <JudgeData> <JudgeID>D0642</JudgeID> <JudgeName>Walter Martin</JudgeName> <JudgeRole>Staff + Judge</JudgeRole> <JudgingPoints>1.0</JudgingPoints> <NonJudgingPoints>1.0</NonJudgingPoints> </JudgeData> </BJCPPoints> <NonBJCP> <JudgeData> <JudgeName>Blake Rooks</JudgeName> <JudgeRole>Steward</JudgeRole> <JudgingPoints>0</JudgingPoints> <NonJudgingPoints>0.5</NonJudgingPoints> </JudgeData> <JudgeData> <JudgeName>Cal Soloway</JudgeName> <JudgeRole>Judge</JudgeRole> <JudgingPoints>1</JudgingPoints> <NonJudgingPoints>0</NonJudgingPoints> </JudgeData> </NonBJCP> <Comments> Competition data entered by Al Boyce C0428 on 4/3/2004. Submitter Email:[email protected] </Comments> <IPAddress>24.163.210.193</IPAddress> <SubmissionDate>Saturday, 03 April 2004 07:23 pm</SubmissionDate> </OrgReport>

Change History

Changes since Version 1.0

The BJCP Board of Directors approved a change to the competition point award structure in July 2005. Following is a summary of the changes for those who have already implemented version 1.0 of the interface specification.

The XML file format, tags and data types are unchanged. However, it is now encouraged that the comments section of the XML file also include the email address of the person preparing the report (in case there are questions about the data). The discussion also clarifies where to send the final report ([email protected] and [email protected]).
The business rules for validating data have changed. However, there are no new “roles.” Only the point award schedule has changed, as well as treatment of stewards, judges and BOS judges.
The daily maximum point award for judges has changed from 1.0 to 1.5 points. The following two rules remain unchanged: (1) judges earn a minimum of 1.0 points per competition, and (2) judges earn points at a rate of 0.5 points per session. BOS points are in addition to any judging points, as they are today.
Multiple BOSs can be held in a single competition. This is not meant to allow a multi-stage BOS, but rather to allow homebrew vs. commercial beer BOS, and separate mead, cider, or mead/cider BOSs.
BOS judges earn an extra 0.5 judging point, in addition to any other points earned. If they only judge BOS, they earn the 1.0 competition minimum.
The number of BOS judges that can earn points is based on the number of entries in the BOS round. The limits apply to each BOS flight.
- 5-14 entries including beer = 3 BOS judges
- 3-14 mead/ciders (only) = 3 BOS judges
- 15+ entries (any combination) = 5 BOS judges
The database does not distinguish types of BOS. The validation rules should simply enforce the total number of BOS judges based on: (1) the number of BOSs, (2) the number of entries in each BOS, and (3) the type of beverage judged in each BOS. The number of BOS entries are reported the same, although if there are multiple BOS rounds only the homebrewed beer BOS should be listed in<CompFlights>.. The rest should be listed in the section <Comments>. (This has since been modified).
The award schedule for organizer points has changed. The same minimum (2) and maximum (6) exist, but the number of entries for each has changed. There is also more granularity (half points can be awarded).
The award schedule for staff points has changed. Staff points can still be awarded to any program participant (except the organizer), and they still must be awarded in 0.5 point increments. The schedule uses the same levels as the organizer schedule. However, there is no cap on the number of staff points. In the new table, 8 staff points are earned for 500-599 entry competitions. At 600 entries and every 100 entries thereafter, an additional 1.0 staff points are available.
The maximum number of judging points that can be awarded to any individual in a competition has changed. Likewise, it is based on the same levels as organizer and staff points. Judging points must be earned using the rules for sessions, days and competitions previously stated.
Following is the maximum point table by number of entries. Except for the organizer, these points are not automatic. They must be earned (for judges) or assigned (for staff).
Entries
Organizer
Staff
Judge (Not including BOS Points)
1-49
2.0
1.0
1.5
50-99
2.5
2.0
2.0
100-149
3.0
3.0
2.5
150-199
3.5
4.0
3.0
200-299
4.0
5.0
3.5
300-399
4.5
6.0
4.0
400-499
5.0
7.0
4.5
500-599
6.0
8.0
5.5
600+
6.0
Additional 1 per each 100 entries over 600
5.5
Organizers may award a combination of staff and steward points. Steward points must be earned. Staff points are allocated. They come from different point pools.
Stewards can now earn a maximum of 1.0 non-judging points per competition. Rather than 0.5 points per competition, they earn 0.5 points per day up to a maximum of 1.0 points. Stewarding points are in addition to any staff points that might be awarded (i.e., they do not come from the same pool of non-judging points).
No individual may earn more total points (sum of judging and non-judging points) in a competition than the organizer. Other individuals may earn an amount equal to the points earned by the organizer. This rule previously existed, but is now explicitly stated in case it was not implemented.

Changes since Version 2.0

Minor clarifications based on comments.

Judges may only receive the BOS bonus once per competition (i.e., a judge can not earn extra points by judging in two or more BOS panels in a single competition).
The section should include the sum of all BOS entries in all BOS panels. Individual BOS details (type, entries) should be put in the section.
At least three BOS mead/ciders are needed to award BOS points in a mead/cider competition or BOS panel.
Clarified composition of BOS panels to award BOS judge points.

Changes since version 2.1

These are technically not really changes as this was supported before but only BJCP internal tool was using this and it was not published. This clarification is needed due to migration to Bravo

<CompFlights> tag will be deprecated in favor of <BOSData> tag to report number of Best of Shows (BOS), type of BOS and number of entries on each BOS panel
<BOSData></BOSData> tag is used to indicate BOS Data section
Within BOSData tag - upto FIVE Best of Shows can be reported.
Type of BOS is determined by <BOSBeer>, <BOSMead> and <BOSCider>
Number of entries on each BOS panel is reported within BOSBeer, BOSMead, BOSCIder tags.
See below example for illustration: <BOSData> <BOSBeer>25</BOSBeer> <BOSMead>5</BOSMead> <BOSCider>3</BOSCider> <BOSBeer>8</BOSBeer> </BOSData> The above example shows a case where there were 4 BOS for a competition with two beer BOS with 25 and 8 entries on BOS panel, a Mead BOS with 5 entried on BOS Panel and a Cider BOS with 3 entries on BOS Panel. As per BJCP rules - the above example will allow 5 + 3 + 3 + 3 = 14 BOS judge credits.

PreviousPay Exam Fees (Admin Only)

Last updated 1 hour ago