The BeerXML Beer Recipes Exchange Standard
Purpose:
BeerXML is a free, fully defined XML data description designed for the exchange of beer brewing recipes and other brewing data. Tables of recipes as well as other records such as hops can be represented using BeerXML for use by brewing programs.
It is our hope that BeerXML will eventually allow for the open exchange of recipes between different beer brewing software packages. Compliance is purely voluntary, however, so timelines for implementation of the proposed standard may vary.
The optional 'Appendix A' 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 and varying units. These appendix tags are intended for display and not for data impor
Contributors to BeerXML 1.0 Development
- Brad Smith, author of BeerSmith - BeerXML Compatible!
- Drew Avis, author of Strangebrew
- Michael Taylor, author of SUDS
- Andrew Perron, author of Drewbrew
- David Johnson, author of QBrew - New - Now BeerXML Compatible!
BeerXML Converters
Darren Robinson recently developed a Visual Basic script for WIndows to convert from Promash text file format to BeerXML:
Download/View BeerXML Version 1.0
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.
<HOP NAME="Cascade"> </HOP>
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
<!-- This is a comment line in the XML format -->
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>
…
</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 1 fields here -->
</HOP>
<HOP>
<!-- hop 2 fields here -->
</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>
<VERSION>1</VERSION>
<ALPHA>5.0</ALPHA>
<AMOUNT>0.100</AMOUNT>
<USE>Boil</USE>
<TIME>60</TIME>
</HOP>
Example dry hop for three days:
<HOP>
<NAME>Fuggles</NAME>
<VERSION>1</VERSION>
<ALPHA>4.5</ALPHA>
<AMOUNT>0.250</AMOUNT>
<USE>Dry Hop</USE>
<TIME>10080.0</TIME>
</HOP>
Example Mash Hops with All Fields - in shuffled order (acceptable):
<HOP>
<AMOUNT>0.050</AMOUNT>
<VERSION>1</VERSION>
<USE>Mash</USE>
<ALPHA>4.5</ALPHA>
<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>
<TIME>45.0</TIME>
<BETA>5.5 </BETA>
<NAME>Super Hops</NAME>
<ORIGIN>Planet Krypton</ORIGIN>
<SUBSTITUTES>Goldings, Fuggles, Super Alpha</SUBSTITUTES>
<MYRCENE>24.4</MYRCENE>
<HSI>30</HSI>
<FORM>Leaf</FORM>
<TYPE>Bittering</TYPE>
<COHUMULONE>13.2</COHUMULONE>
</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:
<FERMENTABLE>
<NAME>Pale 2-row Malt</NAME>]
<VERSION>1</VERSION>
<AMOUNT>5.0</AMOUNT>
<TYPE>Grain</TYPE>
<YIELD>73.4</YIELD>
<COLOR>3.0</COLOR>
</FERMENTABLE>
Example Hopped Extract:
<FERMENTABLE>
<NAME>Fustons Hopped Amber</NAME>
<VERSION>1</VERSION>
<AMOUNT>0.50</AMOUNT>
<NOTES>Hopped amber extract suitable as a base for english ales.
</NOTES>
<YIELD>78.0</YIELD>
<TYPE>Extract</TYPE>
<COLOR>13</COLOR>
<IBU_GAL_PER_POUND>16.6</IBU_GAL_PER_POUND>
</FERMENTABLE>
Sample Crystal Malt Specialty Grain with all applicable fields:
<FERMENTABLE>
<NAME>Crystal 40 L</NAME>
<VERSION>1</VERSION>
<AMOUNT>0.50</AMOUNT>
<TYPE>Grain</TYPE>
<YIELD>74.0</YIELD>
<COLOR>40.0</COLOR>
<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>
<MOISTURE>4.0</MOISTURE>
<DIASTATIC_POWER>0.0</DISASTATIC_POWER>
<PROTEIN>13.2</PROTEIN>
<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>
<VERSION>1</VERSION>
<TYPE>Ale</TYPE>
<FORM>Liquid</FORM>
<AMOUNT>0.100</AMOUNT>
</YEAST>
Example: Yeast with more popular fields
<YEAST>
<NAME>German Ale</NAME>
<TYPE>Ale</TYPE>
<VERSION>1</VERSION>
<FORM>Liquid</FORM>
<AMOUNT>0.250</AMOUNT>
<LABORATORY>Wyeast Labs</LABORATORY>
<PRODUCT_ID>1007</PRODUCT_ID>
<MIN_TEMPERATURE>12.8</MIN_TEMPERATURE>
<MAX_TEMPERATURE>20.0</MAX_TEMPERATURE>
<ATTENUATION>75.0</ATTENUATION>
<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>
<FLOCCULATION>Low</FLOCCULATION>
</YEAST>
Misc
The term "misc" encompasses all non-fermentable miscellaneous ingredients that are not hops or yeast and do not significantly change the gravity of the beer. For example: spices, clarifying agents, water treatments, etc…
Data tag
|
Required
|
Format
|
Description
|
MISC
|
Yes
|
Record
|
Starts a misc ingredient record -- any of the below tags may be included in any order within the <MISC>…. </MISC> record tags. Any non-standard tags in the misc will be ignored.
|
NAME
|
Yes
|
Text
|
Name of the misc item.
|
VERSION
|
Yes
|
Integer
|
Version number of this element. Should be “1” for this version.
|
TYPE
|
Yes
|
List
|
May be “Spice”, “Fining”, “Water Agent”, “Herb”, “Flavor” or “Other”
|
USE
|
Yes
|
List
|
May be “Boil”, “Mash”, “Primary”, “Secondary”, “Bottling”
|
TIME
|
Yes
|
Time (min)
|
Amount of time the misc was boiled, steeped, mashed, etc in minutes.
|
AMOUNT
|
Yes
|
Volume (l) or Weight (kg)
|
Amount of item used. The default measurements are by weight, but this may be the measurement in volume units if AMOUNT_IS_WEIGHT is set to TRUE for this record. If a liquid it is in liters, if a solid the weight is measured in kilograms.
|
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.
|
USE_FOR
|
No
|
Text
|
Short description of what the ingredient is used for in text
|
NOTES
|
No
|
Text
|
Detailed notes on the item including usage. May be multiline.
|
Example: Irish Moss misc with minimal fields
<MISC>
<NAME>Irish Moss</NAME>
<VERSION>1</VERSION>
<TYPE>Fining</TYPE>
<USE>Boil</USE>
<TIME>15.0</TIME>
<AMOUNT>0.010</AMOUNT>
</MISC>
Example: Coriander Spice with a typical set of fields
<MISC>
<NAME>Coriander</NAME>
<TYPE>Spice</TYPE>
<VERSION>1</VERSION>
<USE>Boil</USE>
<TIME>5.0</TIME>
<AMOUNT>0.025</AMOUNT>
<USE_FOR>Belgian Wit Spice</USE_FOR>
<NOTES>Used in Belgian Wit, Whites, and Holiday ales. Very good when used in light wheat ales. Often used with Bitter Orange Peel. Crack open seeds and add at the end of the boil to extract aroma and flavor.
</NOTES>
</MISC>
Water
The term "water" encompasses water profiles. Though not strictly required for recipes, the water record allows supporting programs to record the water profile used for brewing a particular batch.
Data tag
|
Required
|
Format
|
Description
|
WATER
|
Yes
|
Record
|
Starts a WATER ingredient record -- any of the below tags may be included in any order within the <WATER>…. </WATER> record tags. Any non-standard tags in the water will be ignored.
|
NAME
|
Yes
|
Text
|
Name of the water profile – usually the city and country of the water profile.
|
VERSION
|
Yes
|
Integer
|
Version of the water record. Should always be “1” for this version of the XML standard.
|
AMOUNT
|
Copyright 2003-2016 BeerSmith LLC
