BJCP Stlyes XML <--> BeerXML

[GregR]

I've recently started updated the BJCP XML for the BJCP to cincide with their 2008 updates to the style guidelines.

There's been a few comments on here about the BJCP Styles XML:

Concerning "styletype"....

jvetter wrote:
 BJCP breaks styles down based on the categories used for judging (aroma, apperence, mouthfeel, flavor, overall impression) in addtion to having comments, ingredients, history, and examples. The StyleType though only accounts for ingredients and examples. What was the intention of the StyleType? Was it to support a general purpose style record or specifically for BJCP styles. If its the latter then maybe the elements should be adjusted to better fit BJCP. Otherwise I would assume we should put the extra info under notes if we want to record it?

AntonW wrote:
The BeerXML StyleType hasn't changed much from the original 1.0 definition - which I believe was based on a condensed version of an early draft of the BJCP standard.  I did take a look at the most recent BJCP standard XML stylesheet and found it a bit too freeform in the way it handled the record data.  The best solution would be to refactor the BJCP standard and BeerXML StyleType so we may collaborate with the BJCP folks and share data between the standards.

Also, why are we requiring use of only xml 1.0 with latin-1 encoding type?  As specified here:

Code: [Select]

<?xml version="1.0" encoding="ISO-8859-1"?>
<RECIPES>
   …
</RECIPES>
This will preclude us from integrating the 2004 bjcp stylesheet.xml standards with anything beerXML, since their stuff is UTF-8.

There should be plenty of time for input.  No one is in any hurry with the 2008 updates to the style guide XML and I'm doing it fairly slowing, as checking every single sentence in the style guide for changes and then copying and pasting any changes over is quite mind-numbing, as you can imagine.   :-)

So, now's probably a good time to start thinking of any changes that might be beneficial to a better  BeerXML <--> BJCP Styles XML (+schema) fit.  I can't change the actual Style Info of course or the groupings in which that info is laid out, but there is some wiggle room to change things here and there -- even a couple things that I don't understand the intent for...  Changes to the schema can also be considered.  I just have to run by any changes, beyond minor tweeks, by Gordon Strong at the BJCP.

[AntonW]

Hi Greg,

Here are a few questions in regard to the BJCP style guideline XSD that I've had:

• Why does the BJCP XSD encode html list items and hyperlinks when they can be generated from normalized data via XSL?
• Why are beer, mead and cider structures defined within the same class?
• Why do <category> and <subcategory> store their values as attributes instead of within elements?
• For flexible stats, doesn't it make more sense to include flexible as an attribute for <low> and <high> instead of the root <stat-type> element?
• Why don't the stats have units?
• Why doesn't the revision have major and minor segments?

Since the BJCP owns the information contained within the BJCP styleguide, it probably doesn't make sense for BeerXML styles to be perfectly compliant with the BJCP information.  But it would be nice if the BJCP group would allow BeerXML consumer programs to allow their users to download, install and utilize the most recent BJCP XML styleguide information for free (like eclipse-plugins work with eclipse).

-Anton

[GregR]

Since the BJCP owns the information contained within the BJCP styleguide, it probably doesn't make sense for BeerXML styles to be perfectly compliant with the BJCP information.

Agreed.  But some extra similarities here and there will make it a little easier to work with both. ;-)

But it would be nice if the BJCP group would allow BeerXML consumer programs to allow their users to download, install and utilize the most recent BJCP XML styleguide information for free (like eclipse-plugins work with eclipse).

I think this is currently allowed, as long as you don't edit the files, and give BJCP credit when credit is due.


Why does the BJCP XSD encode html list items and hyperlinks when they can be generated from normalized data via XSL?

I don't know.  I've tried contacting the original author of the BJCP XML but to no avail.  He only give a domain name as a contact and it's an expired domain.  I've asked around but no one has his contact info.  But I wouldn't mind changing this...though it wasn't on my priority list as it wasn't bugging me too much - so far. ;-) 


* Why are beer, mead and cider structures defined within the same class?

Very good question. I'm planning on asking them if this can be changed. This has been bugging me too.

*Why do <category> and <subcategory> store their values as attributes instead of within elements?

This is one that I don't have a problem with.  The attributes are supplying meta-data in a way.  But I don't feel strongly about it either way. 

* For flexible stats, doesn't it make more sense to include flexible as an attribute for <low> and <high> instead of the root <stat-type> element?

This one has vexed me ever since I took this on.  I can't for the life of me figure out where he pulled this "attribute" from.  It's not it the style guidelines as far as I can tell.  I "think" I understand what it's implying, but where he got the true vs. false for each value is beyond me.  I'd like to find out.

* Why don't the stats have units?

Oh, HOW I agree!  The original author implied the units (for the most part) in the tag names though.  <srm> <ibu> ...  I would've done it differently...  The way it's implemented you're stuck with those units (in a sense).

However, when looking through the text of the style guide, it's quite obvious that the whole thing is very American-centric.  For example, whenever a temperature is mentioned in the text (e.g. "...single rest at 149°F. Fermented at cool ale temperatures (59-65°F)...") it's always in ˚F. I think they should always list the ˚F with the ˚C, like 68˚F/20˚C or in parenthesis 68˚F (20˚C).  And it'd be nice if the XML used <temp unit="f"> or something similar as well.

Unfortunately, since I'm not supposed to be changing the text of the styles, I feel a bit locked in, but I'd like to put in a recommendation to them to internationalize the guidelines a bit.  And in turn internationalize the XML, by adding units. Maybe they'd let me change the temp text in the XML at least. ;-)  Though I kinda doubt it.

* Why doesn't the revision have major and minor segments?

I think this was the first odd thing I noticed.  The version/revision scheme doesn't make much sense at all.  Seems like there should be a BJCP version number and a version/revision number for the XML file itself.    Then when you look at the notes in the header, the XML "looks" to be on v3, but the tags say v1 ().   Again, I tried contacting the original author about this, and also one of the guys tat did some of the updates.  I did get a hold of the guy that did some updates on it, but he didn't remember messing with the revision #s, and said my guess was as god as his.   

I also don't understand why the revision tags are where they are in the XML...given that the BJCP doesn't revise individual categories at various times, but the whole document at once.  I'm sure the original author had a reason for doing it the way he did, but I can't figure out his logic.

I'll have to run all changes by the BJCP staff.  What might make this changes less painful is if not many people are using the BJCP XML as of yet.  This may be the case.   I'm hoping someone at the BJCP might have some idea if it's currently being utilized by anyone...

[AntonW]

Hi Greg,

It sounds like you're definitely on the right track!  If you can convince the BJCP Committee to allow you to slightly normalize their styleguide data into a format that more closely represents records of useful information then I'm sure everybody would be happy to give you major thanks and the BJCP full credits for their styleguide XML.  I'm not sure if transforms were popular/standardized when the original BJCP XSD was created, which would explain a lot of the inline stuff.

-Anton

[GregR]

* For flexible stats, doesn't it make more sense to include flexible as an attribute for <low> and <high> instead of the root <stat-type> element?

This one has vexed me ever since I took this on.  I can't for the life of me figure out where he pulled this "attribute" from.  It's not it the style guidelines as far as I can tell.  I "think" I understand what it's implying, but where he got the true vs. false for each value is beyond me.  I'd like to find out.

Aha, I figured it out.  I was reading the "summary of changes" for the 2008 updates and it commented that they had now removed the "+" that had been used in style parameters in order to "allow the style numbers to be used in databases or calculations".  Well that was nice of them. ;-)  So the flexible attributes were to denote the parameters that had a "+", such as for Schwarzbiers color, "SRM: 17 – 30+" (from the 2004 guidelines). 

So, I think I'll be removing this attribute altogether, as it no longer serves any purpose - I assume they'd agree to that.  ;-)

[GregR]

* Why doesn't the revision have major and minor segments?

Since many of us on here are interested in using the BJCP XML, a method of denoting BJCP version and revision number are important.  The current system doesn't make too much sense (well pragmatically, to me, at least) in the way it's been implemented.

To clarify which "revision" of the XML document and which version of the BJCP style guide the xml document is, what do you think of the following structure, labelling the BJCP version and update numbers and document revision number at the document root level only, using something like:
   

Code: [Select]

    <styleguide>
        <bjcp_version>2004-A</bjcp_version>
<bjcp_update>2008-A</bjcp_update>
<document_revision>4</document_revision>
Note that, the BJCP considers the 2008 "version" an update, officially titled, "2008 update to the 2004 guidelines". 

And the above system does assume, that the BJCP sticks with the current standard of using years to specify versions and updates.  The letter designations included with the year in the version and updates tags are used to denote changes made in the same year (this is carried over from the current version of the xml).  For example, if the BJCP releases another update in 2008, the structure would change to correspond to the second update in 2008, or "2008-B":

   

Code: [Select]

    <styleguide>
            <bjcp_version>2004-A</bjcp_version>
    <bjcp_update>2008-B</bjcp_update>
            <document_revision>5</document_revision>
This simplifies the version, update, and revision designations (a bit) and I believe allows them to more closely correspond to how the BJCP deals with it's updates.  It also eliminates the redundant revision tag used in the current XML. 

A case could be made for having the version and update information included with each individual style, in case a software application pulls out a style and subsequently needs to check for a version.  However, the process of adding the version could be done with the software application, and doesn't necessarily need to be listed with each style within the XML, as this would create a huge amount of redundant code -- and BeerXML does contain style information itself.  (Anyone for making the BJCP style info the standard format for BeerXML as well? ;-)

Two options to the version and update formats as constructed above would be,

1.) to use a strict numeric format.  So instead of listing two updates release in the same year as update as "2008-A" and "2008-B", you could use, "2008.1" and "2008.2".   This could lead someone to believe that the decimals, .1 and .2 are months (i.e. Jan and Feb), so an additional alternative,

2.) could be to use "2008-Feb" and "2008-Nov" (i.e. if a second update were released in November), and stick to using a date only format for designating versions and updates. 

A final decision might require discussion within the BJCP on just how they want to deal with and designate formal versions and updates going forward.

Or something completely different?  What would work best for the software that's out there already to read the BJCP XML and pickup the version and update info?  Thoughts???

[GregR]

I'd like to suggest making the BeerXML <styles> tags a bit more like the BJCP for easier cross referencing.  I'd propose changing the BeerXML, since the BJCP format and breakdown of style info is so pervasive and often cited and used.   

Here's a comparison of the BJCP Styles and BeerXML breakdown of listing a style:

BJCP Styles	BeerXML Styles
category ----------- subcategory ----------- style name ----------- aroma appearance* flavor* mouthfeel* overall impression* comments ingredients - stats - og fg bitterness color abv ----------- examples	category category number* stylenumber styleguide* style name type* profile* ----------- ----------- ----------- ----------- notes ingredients - stats - og fg bitterness color abv carbonation* examples

* differences

Noted Differences:
The big difference is in how the BJCP styles breakdown what BeerXML calls "profile". 

The category and subcategory info is dealt with slightly different, but this shouldn't be a big deal.

BeerXML's <styleguide> maps to the root of the BJCP XML document:  <bjcp_styleguide>

BeerXML's <type> is somewhat implemented in BJCP_XML, but at a higher level.  However, I'll be suggesting that it is used more explicitly in the BJCP XML.  Currently, it is used one up from the root of the document, eg.  <class type="beer">   ....I'm not sure that's the best usage, and curently, everything in the BJCP document is in class=beer, which is not even logically correct.

Carbonation is missing from the BJCP Styles XML, but unfortunately it is not part of the BJCP guidelines, so, that'll just have to be left as-is.


Proposed Change Summary
I propose that BeerXML map "profile" into the following elements so that it aligns better with the BJCP and is better suited for more extensive and organized profile descriptions. 
Break down BeerXML's <profile> into  ====>  <aroma>, <appearance>, <flavor>, <mouthfeel>, <overall_impression>

[AntonW]

Hi Greg,

From my perspective there's not any problem with adding the tags to BeerXML 2.X style XSDs to get it to match up with the new XML version of the BJCP styleguide.  If the BJCP committee is comfortable with BeerXML users downloading their XML styleguide I'm sure everybody using the newest version of BeerXML will give the BJCP full credit for their continued efforts.  The BJCP should recognize that BeerXML may go into software products which may or may not be open source - so hopefully that won't be a sticking point for them.

You may want to contact Brad (aka Mr BeerSmith) and have a discussion about this.  Also, I think your proposed revision change (for BJCP XML) would help to increase readability.

Have you had a chance to look at the updated BeerXML XSDs (the ones with the namespaces)?  Unfortunately with work and other projects I haven't had much time to devote to BeerXML lately.

-Anton

[Michele]

Can anyone tells BJCP that they should use a STANDARD UTF8 ENCODING instead of what they actually using? 
I tryed to, but I recived no answer!