BeerXML 2.0 schema proposal

[KevinM]

But really, I would look at the XML file itself and see if there was a problem with it- if it fit the standards documented on this site. If it didn't, then I'd blame Jeff/promash.  If it did, then I'd fix my code.

But what if ProMash did fit the spec and so did your program? I believe the point here is that two people can implement the 1.0 spec "correctly" and still end up generating recipe files that aren't compatible with each other. This goes against the whole premise of BeerXML and must be fixed.

It's really not that uncommon for the second generation of anything to be extensively different from the first version. I think the first version is usually just a best-effort realization of the ideas floating about and serves to test the real-world usefulness of it and interest in it. Version two is about addressing the myriad issues which have arisen (many unforseeable) and redesigning it in a smarter way now that everyone's conviced it truly is a worthy, useful endevor. I think it's also not uncommon for software to break compatiblility with the initial version when this happens. Look at GNOME (the Linux desktop environment), for example. Version 1.0 to 2.0 was a heck of a change and flat out broke most software built for 1.0. I can still hear the reverberations of the people screaming bloody murder from when this happened. It's now quite a few years later and while some software was never ported to the new version and, thus, disappeared completely, the community as a whole has benefited greatly from the change by having a much better system IN THE LONG RUN.

I also agree that the current spec requires too many elements for the basic exchange of a recipe. I think there's a fine line between recipe formulation systems and recipe database systems but the line should exist. I'm the webmaster for a medium sized homebrew club and I would like our users to be able to enter and exchange recipes on our website without worrying about actually "formulating" a recipe. Through a series of pulldowns and entry boxes, I'd like a user to be able to enter basic information about the ingredients of the recipe and minimal steps involved for mashing and fermenting and nothing more if they don't want to. The ingredients and steps could then be saved to a BeerXML file, someone else would download that file, import it into their formulation software and come up with projected results for IBUs, SRM, OG, etc. The 1.0 spec seems to favor recipe formulation and evaluation in some spots rather than simple recipe creation and exchange. I also do some PalmOS development and would like to create the same type of minimalist recipe exchange system there. Certainly, I don't want to have to get into formulation details on an embedded platform like that.

3. Get rid of the caps

Oh please, please, please....camelCase/studlyCaps/all_lower/whatever - anything but ALL CAPS. The caps make my eyes bleed everytime I have to look at a BeerXML file 

Well, first I'd call hell to see if it was snowing, because the day Promash supports beerxml...

LOL...I with ya on that one. I've actually heard a rumor that he's considering adding support whenever/if ever he updates ProMash to bring it into the current century. Personally, I don't use it since it doesn't run on Mac OSX or Linux but it would be nice if the many people who do use it could exchange their recipes with the rest of us striving for a common format.

Kevin

[bperetto]

>>Well, first I'd call hell to see if it was snowing, because the day Promash supports beerxml...

LOL...I with ya on that one. I've actually heard a rumor that he's considering adding support whenever/if ever he updates ProMash to bring it into the current century. Personally, I don't use it since it doesn't run on Mac OSX or Linux but it would be nice if the many people who do use it could exchange their recipes with the rest of us striving for a common format.

Well, at least "considering adding it" is better than the last response I heard from him.

To be honest, my BeerXML recipe database (which just went public-alpha) was created primarily to "strongly encourage" ProMash to implement it.  It's only been a week and I know of one person (besides myself) who switched from ProMash to a BeerXML-capable application to utilize the database.

There's some smart people out there, so whatever you do with V2, I'm sure we'll somehow adopt. ..hopefully.

[AntonW]

Sorry for my extended absence - was shanghai'd into helping my parents reroof their house....

Ok, so made some updates to the hops section and will post the files here.  Please take a look at them and let me know what you think...  I took some liberties and moved things around a bit so let me know if you like the changes.  Also migrated the version.xsd to measurable_units.xsd which covers version and all the data types that can be used for measuring.

The file to pay attention to is the hop_additions.xml file, which currently represents the hop additions section within the beerxml2 recipe files.  I don't have the recipe.xsd finished yet, because it's the concatenation of all the subelements.  But please let me know if I'm on the right track...

-Anton

ps. The files are attached with the *.txt extension, so you'll have to rename them if you'd like to use them for validation.

[AntonW]

Here are the xml samples...

[AntonW]

I've updated the rest of the XSDs - they can be downloaded from here: http://www.speakeasy.org/~antonw/beer_xml/BeerXML_v2_01.zip

I'll attach some before and after snapshots of the recipe file to this message so you'll be able to see the differences side-by-side.  Within the next few days I'll also try to update the draft of the documentation for the second version to reflect the changes made.

Please let me know if you have any questions or comments!
-Anton

[AntonW]

Has anybody had a chance to take a look at the new recipe format and schema changes?

Any feedback would be greatly appreciated!!

-Anton

[BeerSmith]

Anton,
  Overall I liked the new format, but I have not yet had time to look it over in detail.  Personally I have no big problems with going to flexible units and lower case names.

  However, I would probably need to go through item by item to make sure the data is consistent and actually complete.

  Have you made any progress on the actual standards document?  A schema is a very good start, but we need to be able to explain what each data element is and what it does.  Also we need agreement on units, basic formats, etc...before we implement the schema.

  When we did the original standard we started with the front matter, got agreement on that, and then started going through the data types (hops, grains, etc...) one at a time to get agreement on each. 

  These are just my initial thoughts...I would certainly like to hear from others.

Cheers!
Brad

[AntonW]

I've updated and synchronized both the Standards Document and the Schema, so everything should be consistent throughout.  When you guys have a chance, please take a look at both and give me some feedback about your thoughts on the changes for the new format.

The Version 2 Standards Document is attached at: http://beerxml.com/forum/index.php?action=dlattach;topic=21.0;id=24

The Version 2 Schema files and examples are at: http://www.speakeasy.org/~antonw/beer_xml/BeerXML_v2_01.zip

Thanks!
-Anton

[BeerSmith]

Anton,
  It looks like you did a great job with the new proposal.  I have not yet had a chance to go through it line by line, but plan to spend some time with it this weekend.  Obviously the changes are substantial (many of the old data fields are now elements), so the transition is far from seamless, but I could probably support the new standard (as well as the old) without a monsterous amount of work.

  One question I had was the ability to support optional fields.  The new proposal requires the import of optional tags, but does not appear to allow any vendor specific tags or extensions.  Obviously most programs support additional fields besides the ones in the standard.

  Also minor points - like why did you separate the water from the ingredients (I think it was part of the ingredients list before in the recipes).  One could use more than one water type (i.e. some people blend waters with bottled water to get softer profiles for example).  You even redefined Waters in the recipe profile rather than just reusing the previous template.

More later...but thanks for your efforts to date.

Brad

[AntonW]

Hi Brad,

Thanks for taking a first look at the new proposal!  While adding support for units I made an attempt to simplify some of the material, so please let me know where these changes work and where they don't work.

Regarding elements in the XML which are not represented in the schema, it's true that a validated standard does not typically allow vendor-specific extensions.  But validation against the XSDs buys us a lot in terms of error checking that a non-validated standard just won't catch.  I'll investigate if a vendor-specific section could be added to allow for extensions, but I'd still question whether it should be added or not.  In the meantime, could you provide an example so I'll have a point of reference to work from.

Water fell out of the ingredients section due to a cut and paste error.  A water addition in the recipe should also have an amount associated with it.  I'll make those changes and update the schema and examples in the document later today.  For recipes would it make more sense to just have a single (ideal) water addition that is correct for the style of beer?  Encoding how the recipe's contributor altered their water chemistry to approach the ideal is probably beyond the scope of a recipe.

With each of the ingredient addition types I gathered a subset of the elements that specify unique values such as name, origin, and other properties key to adding that ingredient into the recipe.  This subset of elements which uniquely specify ingredients is what was placed in the recipe schema for ingredient additions - along with the amount and other properties necessary for a successful addition (like time for hops).

Thanks again for the feedback and please let me know if you have additional questions or suggested changes!

-Anton

[AntonW]

The XSDs have been updated to reflect the changes for Water additions (moving them into Ingredients and adding amount).  I would like to get your feedback before making any updates to standards document, since there will probably be several loops of feedback and updates that are necessary.

Please let me know if you have any questions,

-Anton

[AntonW]

Does anybody have any questions or comments about the XSDs and/or standards document for the BeerXML version 2 standard?

-Anton

[BeerSmith]

Anton,
  Been swamped lately but this is still firmly on my "to do" list.  I'm even trying to come up with some basic machine generated examples for you.  Unfortunately it will probably still be a few weeks away.

Cheers!
Brad

[AntonW]

No problem.  If I get a BeerXML converter working I'll post the results ( preliminary version 2.0 files ) to provide more sample material.

-Anton

[AntonW]

I've made a few small updates to the XSDs, so please download a fresh copy if you haven't lately.  They can be found at:
http://www.speakeasy.org/~antonw/beer_xml/BeerXML_v2_01.zip 

If you would also like to try out a ProMash recipe file to BeerXML2 converter (the preliminary BeerXML2.0x standard anyway :^), you can find that at:

http://www.speakeasy.org/~antonw/beer_xml/ProMash2BeerXML.zip

The program requires a WinNT/2K/XP/Vista machine with Internet Explorer 5.5 SP2 or higher.  If you have problems using the program, please let me know.  The converter will spit out a big chunk of XML so you might need to transform it using an XML pretty-printer in order to read and make sense of it.

I'm thinking that removing the equipment-specific elements within the <mash> section, such as tun_temperature, tun_weight, tun_specific_heat and adjust_for_equipment elements would be a good idea.  If these elements need to be preserved we could always move them into a session XML file that deals with Brewing Session specific variables.

Also if you have any comments or questions regarding the preliminary BeerXML2.01 standard as it appears so far, please speak up and give us your feedback!

Thanks!
-Anton