I’m attempting to work on a new open format for defining brewing recipes in a simpler (less verbose) manner than BeerXML, while also supporting features such as arbitrarily complex fermentation profiles.
Please bear in mind the current examples are very rough. I’m thinking how best to represent things such imperial/metric units, along with time for aspects such as fermentation profiles.
I’ve created a channel on freenode #beerjson, if anyone wants to have a chat about ideas for a new spec.
Right off the bat, I’d say that encoding units in property names is a bad idea, since code will then have to parse these, and also means you don’t have a unique name for each property.
I can imagine a couple of alternatives:
make each quantity an object with sub-properties for the value and unit.
"temperature": { "v":12.3, "u":"C" }
add a -unit property, so each value is a pair of properties - one for the value itself and one for the unit.
"temperature": 12.3
"temperature-unit": "C"
This is really just a workaround for the fact that json doesn’t have separate text and attributes.
To my mind, the biggest issue with BeerXML isn’t verbosity - no-one writes these things by hand! The problem was interoperability and false assumptions.
Thinking of the unit issue we talked about above, the separate properties could be normalized as a single range object, so the unit is repeated only once:
Ranges are almost as common as single values, so representing them like this means that once you know how one range works you know how the all work. Having the range as an object also means you can add additional properties, such as a “typical” value where that makes sense.
That could work - I was thinking of suggesting making everything SI units, so the problem disappears entirely. However, this means we can get some crazy numbers when talking about small quantities of some ingredients. E.g. You might need to add 1.5g of gypsum for some recipes - is writing 0.0015 clear enough, compared to 1.5 grams?
If the json format isn’t meant to be human readable then sure, adopting a global units could be the way forward. And IMHO, I would say that the need interoperability far outweighs the need for readability, so the choice is probably best guided by what is most easy to interpret by machine.
I am not a big fan of the verbosity of units being spread as separate entities all over the place, but I also see the risk of misinterpretation, if units are kept separate.
I also would like the option of switching between kg and gram for different kinds of ingredients.
One unorthodox solution could be to have different ‘tag’ names according to the unit, ie. “time-m”, “time-h”, “temperature-c”, “temperature-f”, “weight-kg”, “weight-g” etc.
This will sacrifice a bit of ease while parsing the JSON, but improves readability without sacrificing explicit unit specification.
I’m a big fan of standardising the unit in the JSON and post processing to whatever unit you need when you need it.
Configuring units or orders of magnitude (unless your range is wide enough to extend beyond type sizes) is information a computer doesn’t need and is thus redundant.
There’s no reason for such a format to be human readable, it should be simple enough to wrap it in a human editor for the customizable stuff.
If we use SI units, then we’ll have to specify quantities of ingredients in moles and temperatures in Kelvin!
But seriously, while I feel interop is more important than readability, some people will definitely argue the format has to be readable, and I think it’s important to set a line in the ground and say, “it doesn’t matter”. Tooling can help with converting units at presentation time. So someone in the US and Europe can view the same recipe and it will be automatically converted to their local units preferences on presentation.
