BeerXML

An XML Standard

for Beer Brewing Data

Version 1.0

Created by:

Brad Smith – “BeerSmith”

Drew Avis – “Strangebrew”

Michael Taylor – “SUDS”

Andrew Perron – “DrewBrew”

David Johnson – “QBrew”

Purpose

The primary purpose for the standard is the exchange of recipes, but it could also be used for the exchange of other brewing data. For example a table of hops could be exported as a series of XML hop records in a single file.

The optional appendix adds tags for use in the display of brewing data using XML style sheets or XML compatible report generators. As the tags in the appendix are for display only and may include rounded values. We do not recommend relying on any of these tags for data import.

General

Brewing data will follow the XML standard as a basis. To be compliant the program must be able to import or export the required tags, recognize the data formats and units, and follow basic XML conventions. In addition the program may support optional tags that have “No” in the Required column.

For simplicity, the convention of using a separate tag for each data entry as in the following will be used:

<HOP>

<NAME>Cascade</NAME>

</HOP>

Though equivalent, the following XML format (i.e. XML Attributes) should NOT be used.

Each new tag will be put on a separate line, with the start and end of the tag surrounding the data. Tags starting and ending a record will be placed on their own line (see examples).

File Extension

The file extension “.xml” should be used for all BeerXML files. For example, a recipe file might be named “recipes.xml”.

Comments

Comments may be embedded per the XML standard, but all comments shall be ignored by importing programs.

Sample XML comment

Special Characters

The exporting and importing programs should recognize and translate the normal XML special character codes if they appear in any of the data strings. These include:

*Character*	*XML Code*
&	&
<	<
>	>
“	"
‘	'

XML Header

Per the XML standard, all files should begin with the following header line as the first line. After the XML header a record set should start (for example <RECIPES>…</RECIPES> or <HOPS> … </HOPS>).

Required XML Header Example with Recipes tag:

<?xml version="1.0" encoding="ISO-8859-1"?>

…

</RECIPES>

Tag Names

Tag names will be uppercase. For example "HOP" is acceptable, but "hop" and Hop" are not.

Version

All records have a required <VERSION> tag that denotes the version of the XML standard. All should be set to the integer 1 for this version of the standard. It is our intent that future versions of the standard will be backward compatible with the older versions, but the VERSION tag allows newer programs to check for a higher version of the standard or do conversions if required to be backward compatible.

Non-Standard Tags

Per the XML standard, all non-standard tags will be ignored by the importing program. This allows programs to store additional information if desired using their own tags. Any tags not defined as part of this standard may safely be ignored by the importing program.

Data Formats

- Record Set – A special tag that starts a particular set of data. For example an XML table that consists of a set of hops records might start with a <HOPS> tag to denote that this is the start of hops records. After the last record, a </HOPS> tag would be used.

- Record - Denotes a tag that starts or ends a particular record -- for example "HOP" might start a hops record or "FERMENTABLE" might start a fermentable record.

- Percentage - Denotes a percentage - all percentages are expressed as percent out of 100- for example 10.4% is written as "10.4" and not "0.104"

- List - The data has only a fixed number of values that are selected from the list in the description table for the tag. These items are case sensitive, and no other values are allowed.

- Text - The data is free format text. For multiline entries, line breaks will be preserved where possible and the text may be truncated on import if the text is too long for the importing program to store. Multiline entries may be split with either a newline (Unix format) or a carriage return – newline combination (DOS format). Importing programs should accept either.

- Boolean - May be either TRUE or FALSE, with TRUE and FALSE in capitals. A default value should be specified for optional fields - the default is used if the value is not present.

- Integer - An integer number with no decimal point. May include negative values - examples include ...-3, -2, -1, 0, 1, 2, 3,...

- Floating Point - A floating point number, usually expressed in its simplest form with a decimal point as in "1.2", "0.004", etc... Programs shall endeavor to store as many significant digits as possible to avoid truncating or losing small values.

Units

For this portion of the standard ALL units must be fixed. It is the responsibility of the importing or exporting program to convert to and from the units below if needed.

Weight Units

All weights will be measured in Kilograms (kg). For small values the exporting program will make an effort to preserve as many significant digits as possible.

Volume Units

All volumes will be measured in Liters (l). For small values the exporting program will make an effort to preserve as many significant digits as possible.

Temperature Units

All temperatures will be measured in degrees Celsius.

Time Units

All times will be in minutes or fractions thereof – unless otherwise specified in the tag description.

Specific Gravity Units

Specific Gravity will be measured relative to the weight of the same size sample of water. For example “1.035”, “1.060”, etc…

Pressure Units

Pressures will be measured in kilopascals (kPa)

Record Sets

The following special tags are used to denote a set of records. This allows more than one record of a single type to be embedded within a recipe, and also allows separate XML tables to be exported and imported. For example a standalone collection of hops records might be exported as a “HOPS” table by starting the table with <HOPS>, continuing with a number of hops records and ending the table with </HOPS>

In a recipe, these record set identifiers are also used to separate records of different types. For example, all HOP records used in a recipe will be enclosed between <HOPS>…</HOPS> identifiers.

Data tag	Format	Description
HOPS	Record Set	Encloses a set of one or more Hop records.
FERMENTABLES	Record Set	Encloses a set of one or more Fermentable records.
YEASTS	Record Set	Encloses a set of one or more Yeast records.
MISCS	Record Set	Encloses a set of one or more Misc records
WATERS	Record Set	Encloses a set of one or more Water records
STYLES	Record Set	Encloses a set of one or more Beer Styles
MASH_STEPS	Record Set	Used within a MASH profile to record the steps
MASHS	Record Set	Used for a set of one or more mash profiles
RECIPES	Record Set	Encloses one or more recipe records.
EQUIPMENTS	Record Set	Set of one or more equipment records.

Example: A set of 2 hops

<HOPS>

<HOP>

</HOP>

<HOP>

</HOP>

</HOPS>

Hops

The “HOP” identifier is used to define all varieties of hops.

Data tag	Required	Format	Description
HOP	Yes	Record	Starts a hops ingredient record -- any of the below tags may be included in any order within the <HOP>….</HOP> record tags. Any non-standard tags in the hops will be ignored.
NAME	Yes	Text	Name of the hops
VERSION	Yes	Integer	Should be set to 1 for this version of the XML standard. May be a higher number for later versions but all later versions shall be backward compatible.
ALPHA	Yes	Percentage	Percent alpha of hops - for example "5.5" represents 5.5% alpha
AMOUNT	Yes	Weight (kg)	Weight in Kilograms of the hops used in the recipe.
USE	Yes	List	May be "Boil", "Dry Hop", "Mash", "First Wort" or "Aroma". Note that "Aroma" and "Dry Hop" do not contribute to the bitterness of the beer while the others do. Aroma hops are added after the boil and do not contribute substantially to beer bitterness.
TIME	Yes	Time (min)	The time as measured in minutes. Meaning is dependent on the “USE” field. For “Boil” this is the boil time. For “Mash” this is the mash time. For “First Wort” this is the boil time. For “Aroma” this is the steep time. For “Dry Hop” this is the amount of time to dry hop.
NOTES	No	Text	Textual notes about the hops, usage, substitutes. May be a multiline entry.
TYPE	No	List	May be "Bittering", "Aroma" or "Both"
FORM	No	List	May be "Pellet", "Plug" or "Leaf"
BETA	No	Percentage	Hop beta percentage - for example "4.4" denotes 4.4 % beta
HSI	No	Percentage	Hop Stability Index - defined as the percentage of hop alpha lost in 6 months of storage
ORIGIN	No	Text	Place of origin for the hops
SUBSTITUTES	No	Text	Substitutes that can be used for this hops
HUMULENE	No	Percent	Humulene level in percent.
CARYOPHYLLENE	No	Percent	Caryophyllene level in percent.
COHUMULONE	No	Percent	Cohumulone level in percent
MYRCENE	No	Percent	Myrcene level in percent

Example with required fields only:

<HOP>

<NAME>Cascade</NAME>

</HOP>

Example dry hop for three days:

<HOP>

<NAME>Fuggles</NAME>

</HOP>

Example Mash Hops with All Fields - in shuffled order (acceptable):

<HOP>

<NOTES> This hop is a really cool hops - you can use it for anything.

It leaps over buildings in a single bound, is faster than

a speeding bullet and makes really bitter beer.

</NOTES>

<NAME>Super Hops</NAME>

<ORIGIN>Planet Krypton</ORIGIN>

<SUBSTITUTES>Goldings, Fuggles, Super Alpha</SUBSTITUTES>

<TYPE>Bittering</TYPE>

</HOP>

Fermentable

The term "fermentable" encompasses all fermentable items that contribute substantially to the beer including extracts, grains, sugars, honey, fruits.

Data tag	Required	Format	Description
FERMENTABLE	Yes	Record	Starts a fermentable ingredient record -- any of the below tags may be included in any order within the <FERMENTABLE>…. </FERMENTABLE> record tags. Any non-standard tags in the fermentable will be ignored.
NAME	Yes	Text	Name of the fermentable.
VERSION	Yes	Integer	Should be set to 1 for this version of the XML standard. May be a higher number for later versions but all later versions shall be backward compatible.
TYPE	Yes	List	May be "Grain", "Sugar", "Extract", "Dry Extract" or "Adjunct". Extract refers to liquid extract.
AMOUNT	Yes	Weight (kg)	Weight of the fermentable, extract or sugar in Kilograms.
YIELD	Yes	Percent	Percent dry yield (fine grain) for the grain, or the raw yield by weight if this is an extract adjunct or sugar.
COLOR	Yes	Floating Point	The color of the item in Lovibond Units (SRM for liquid extracts).
ADD_AFTER_BOIL	No	Boolean	May be TRUE if this item is normally added after the boil. The default value is FALSE since most grains are added during the mash or boil.
ORIGIN	No	Text	Country or place of origin
SUPPLIER	No	Text	Supplier of the grain/extract/sugar
NOTES	No	Text	Textual noted describing this ingredient and its use. May be multiline.
COARSE_FINE_DIFF	No	Percent	Percent difference between the coarse grain yield and fine grain yield. Only appropriate for a "Grain" or "Adjunct" type, otherwise this value is ignored.
MOISTURE	No	Percent	Percent moisture in the grain. Only appropriate for a "Grain" or "Adjunct" type, otherwise this value is ignored.
DIASTATIC_POWER	No	Floating Point	The diastatic power of the grain as measured in "Lintner" units. Only appropriate for a "Grain" or "Adjunct" type, otherwise this value is ignored.
PROTEIN	No	Percent	The percent protein in the grain. Only appropriate for a "Grain" or "Adjunct" type, otherwise this value is ignored.
MAX_IN_BATCH	No	Percent	The recommended maximum percentage (by weight) this ingredient should represent in a batch of beer.
RECOMMEND_MASH	No	Boolean	TRUE if it is recommended the grain be mashed, FALSE if it can be steeped. A value of TRUE is only appropriate for a "Grain" or "Adjunct" types. The default value is FALSE. Note that this does NOT indicate whether the grain is mashed or not – it is only a recommendation used in recipe formulation.
IBU_GAL_PER_LB	No	Floating Point	For hopped extracts only - an estimate of the number of IBUs per pound of extract in a gallon of water. To convert to IBUs we multiply this number by the "AMOUNT" field (in pounds) and divide by the number of gallons in the batch. Based on a sixty minute boil. Only suitable for use with an "Extract" type, otherwise this value is ignored.

Example Fermentable Record with required fields only:

<NAME>Pale 2-row Malt</NAME>]

<TYPE>Grain</TYPE>

</FERMENTABLE>

Example Hopped Extract:

<NAME>Fustons Hopped Amber</NAME>

<NOTES>Hopped amber extract suitable as a base for english ales.

</NOTES>

<TYPE>Extract</TYPE>

<IBU_GAL_PER_POUND>16.6</IBU_GAL_PER_POUND>

</FERMENTABLE>

Sample Crystal Malt Specialty Grain with all applicable fields:

<NAME>Crystal 40 L</NAME>

<TYPE>Grain</TYPE>

<ORIGIN>United Kingdom</ORIGIN>

<SUPPLIER>Fussybrewer Malting</SUPPLIER>

<NOTES>Darker crystal malt.

Adds body and improves head retention.

Also called caramel malt.

</NOTES>

<COARSE_FINE_DIFF>1.5</COARSE_FINE_DIFF>

<DIASTATIC_POWER>0.0</DISASTATIC_POWER>

<MAX_IN_BATCH>10.0</MAX_IN_BATCH>

<RECOMMEND_MASH>FALSE</RECOMMEND_MASH>

</FERMENTABLE>

Yeast

The term "yeast" encompasses all yeasts, including dry yeast, liquid yeast and yeast starters.

Data tag	Required	Format	Description
YEAST	Yes	Record	Starts a yeast ingredient record -- any of the below tags may be included in any order within the <YEAST>…. </YEAST> record tags. Any non-standard tags in the yeast will be ignored.
NAME	Yes	Text	Name of the yeast.
VERSION	Yes	Integer	Version of the standard. Should be “1” for this version.
TYPE	Yes	List	May be “Ale”, “Lager”, “Wheat”, “Wine” or “Champagne”
FORM	Yes	List	May be “Liquid”, “Dry”, “Slant” or “Culture”
AMOUNT	Yes	Volume (liters) or Weight (kg)	The amount of yeast, measured in liters. For a starter this is the size of the starter. If the flag AMOUNT_IS_WEIGHT is set to TRUE then this measurement is in kilograms and not liters.
AMOUNT_IS_WEIGHT	No	Boolean	TRUE if the amount measurement is a weight measurement and FALSE if the amount is a volume measurement. Default value (if not present) is assumed to be FALSE – therefore the yeast measurement is a liquid amount by default.
LABORATORY	No	Text	The name of the laboratory that produced the yeast.
PRODUCT_ID	No	Text	The manufacturer’s product ID label or number that identifies this particular strain of yeast.
MIN_TEMPERATURE	No	Temperature (C)	The minimum recommended temperature for fermenting this yeast strain in degrees Celsius.
MAX_TEMPERATURE	No	Temperature (C)	The maximum recommended temperature for fermenting this yeast strain in Celsius.
FLOCCULATION	No	List	May be “Low”, “Medium”, “High” or “Very High”
ATTENUATION	No	Percent	Average attenuation for this yeast strain.
NOTES	No	Text	Notes on this yeast strain. May be a multiline entry.
BEST_FOR	No	Text	Styles or types of beer this yeast strain is best suited for.
TIMES_CULTURED	No	Integer	Number of times this yeast has been reused as a harvested culture. This number should be zero if this is a product directly from the manufacturer.
MAX_REUSE	No	Integer	Recommended of times this yeast can be reused (recultured from a previous batch)
ADD_TO_SECONDARY	No	Boolean	Flag denoting that this yeast was added for a secondary (or later) fermentation as opposed to the primary fermentation. Useful if one uses two or more yeast strains for a single brew (eg: Lambic). Default value is FALSE.

Example: Yeast with required fields only

<YEAST>

<NAME>Ole English Ale Yeast</NAME>

<FORM>Liquid</FORM>

</YEAST>

Example: Yeast with more popular fields

<YEAST>

<NAME>German Ale</NAME>

<FORM>Liquid</FORM>

<LABORATORY>Wyeast Labs</LABORATORY>

<PRODUCT_ID>1007</PRODUCT_ID>

<MIN_TEMPERATURE>12.8</MIN_TEMPERATURE>

<MAX_TEMPERATURE>20.0</MAX_TEMPERATURE>

<NOTES>Crisp dry flavor with a hint of mild flavor.

Great for many continental ales.

</NOTES>

<BEST_FOR>German Ales, Alts, Kolsch, Dry Stouts </BEST_FOR>

</YEAST>

Misc

The term "misc" encompasses all non-fermenta