The original BeerXML specification has some serious limitations hindering widespread acceptance so I have proposed to design a new specification which addresses these limitations and provides enough flexibility to serve the needs of the widest possible audience. I will describe below some of the limitations and issues which I see with the original specification but those readers who wish to participate in this discussion may wish to familiarize themselves with the relevant XML specifications and terminology used.
XML 1.0XML Schema Part 0: Primer Second EditionXML Schema Part 1: Structures Second EditionXML Schema Part 2: Datatypes Second EditionNamespaces in XML 1.0XML Path Language (XPath)XSL Transformations (XSLT)First, a major limitation of the specification is that element attributes are disallowed. This choice was apparently made to allow rudimentary custom parsers to easily read and create BeerXML files. The issue is that XML without attributes is ML, not XML. The extensibility in XML is provided by schema and namespaces which require the use of attributes. The following is a simple example of a schema being specified for an element.
<RECIPES xmlns:xsi="
http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="beerxml.xsd">
<RECIPE>
...
</RECIPE>
</RECIPES>
Aiming for a low entry barrier for acceptance of the specification is an important goal but limiting the specification to ML features which only the most basic text parser can understand circumvents the purpose of using XML entirely. If using custom parsers is a requirement of some stakeholders then I respectfully suggest that the name of the original specification should be changed to BeerML to clarify its purpose and allow a real XML specification to be developed.
Second, the specification was proposed without an XML schema, or even a document type definition. This severely limits the use and interoperability of documents produced and, in effect, the possibility that BeerXML could be used as a standard. For example, it is impossible to determine if a document is valid without parsing it and possibly encountering an error in the process. It is also impossible to create a document that is verifiably compliant with the specification.
Third, the specification defines elements with dubious relevance instead of allowing vendors to extend the specification (using namespaces). For example, "STYLE" contains elements suitable for describing nearly every detail of the range of statistics which define the beer style; information which is non-essential to brewing the recipe and which would be better described in an extended schema. Other elements like "DISPLAY_AMOUNT" are simply translations of data defined in other elements.
For example, with a minimal recipe schema specification a vendor could include proprietary elements by specifying their own schema namespace.
<RECIPES xmlns:xsi="
http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="
http://www.beerxml.com/schema/2.0/beerxml.xsd">
<RECIPE>
...
<STYLE>
<NAME>
<STYLESTATS xmlns:bs="
http://www.beersmith.com/beerxml-style.xsd">
<bs:History>
...
</bs:History>
</STYLESTATS>
</STYLE>
</RECIPE>
</RECIPES>
Forth, the specification defines element names which are duplicated at different levels and may, in some cases, contain conflicting data types. Element structure is also poorly organized with a large amount of elements existing directly under the RECIPE element instead of organized logically (e.g, Metadata, Ingredients, Process, ExpectedResults).
Fifth, the specification provides only limited support for localization. For some reason the specification mandates the use of an XML header which specifies a character encoding of "ISO-8859-1" which limits documents to a subset of latin based characters. Mandating a specific character encoding is counter-productive but if the specification must suggest a specific encoding then "UTF-8" may be a better choice. Further, some authors may desire to include multiple languages for some elements (e.g. notes, instructions). Due to the lack of a schema it is unclear if this is currently allowed. Many units are mandated to be in metric which may be more restrictive than necessary. Also, due to the fact that attributes are disallowed some elements contain a string including the units (e.g. "4 lb") instead of an integer or decimal number.
Finally, the naming convention chosen breaks with most industry recommendations. For reference the URL below lists a number of international organizations and standards bodies which have standardized on the use of camelCase for element names.
http://xml.coverpages.org/camelCase.htmlSpecifically, the use of UpperCamelCase is recommended for element names and lowerCamelCase for attribute names. The use of punctuation and non-alpha characters (e.g., "_") in element names is discouraged. While every schema implementor is free to choose their own conventions based on specific need, it seems counter-productive to break with industry practice.
For these reasons, I propose to design a BeerXML schema from scratch that does not attempt compatibility with the original specification. If the community approves this proposal I will outline some additional recommendations and seek further feedback on the requirements of the specification, if there are multiple audiences within the community, and any additional concerns with the existing specification.
--
Chris Cook
