This is a repository for development of BeerJSON interchange format specification. It is based on yet unfinished BeerXML 2 standard (PDF).

Overview of significant changes from BeerXML 1.0

• Addition timing object supports any ingredient being added to any process step on a basis of time, temperature, or gravity.

• Ingredient addition property of time is now duration to improve clarity, and decrease confusion with new timing object properties.

• All process steps include temperature, pH, and gravity.

• Grain absorption rate is a property of the mash tun.

• Sparge, and wort run offs are treated as mash steps.

• Explicit boil steps to support production of more complex boil procedures such as raw ales, and common whirlpooling processes.

• Yeast schema becomes culture schema, for clearer support for non\*yeast cultures.

• Extensive ingredient properties, such as hop oil content, culture floculation, pof, glucoamylase production, and full support for maltster spec sheet properties.

• Explicit integrated support for common sour wort, and sour beer production. Souring steps can be included in mash, boil, or fermentation.

• Explicit support for different chilling methods, forced vs passive, in line vs batch chilling.

• Explicit support for all efficiency types, conversion, lauter, mash, and brewhouse.

• Explicit support for fermenting under pressure.

Structure of the repository

| Path | Contents | | -------- | ----------------------------------------------------------------------------------------------------- | | json/ | The JSON Schema files. This is the specification. | | docs/ | Generated reference, published to beerjson.github.io/beerjson | | types/ | Generated TypeScript and Flow declarations | | js/ | Documentation and type generators, validator, BeerXML importer | | tests/ | Sample documents validated against the schemas in CI | | xsd/ | BeerXML 1.0 schemas, kept for reference by the importer | | adr/ | Architecture Decision Records for format decisions |

Current development happens on main. Each published version has a tag. docs/ and types/ are generated from json/ and are never edited by hand.

CI and tests

The test suite validates every document under tests/ against the schemas, converts the BeerXML fixtures and validates the result, checks the generators against snapshots, and enforces the authoring conventions in SCHEMA_STYLE.md.

npm ci
npm test

The project targets Node's active and maintenance LTS lines. CI runs the suite on Node 22 and 24; a version is dropped once it goes end-of-life.

Documentation

Documentation is autogenerated from JSON schema files.

It is published at https://beerjson.github.io/beerjson/

Rebuilding documentation

npm run gen-docs

Version

This branch contains the BeerJSON 1.0 specification. Released changes are recorded in CHANGELOG.md.

The schemas are JSON Schema 2020-12, so a validator supporting that draft is required.

How to contribute

See CONTRIBUTING.md for the full guide. In short:

• A question, or an idea that is not yet a concrete proposal: start a

• A schema change: open an

• A bug in the schemas, docs, types, or tooling: open an issue
• A pull request: follow SCHEMA_STYLE.md for anything

Participation is governed by our Code of Conduct. Security reports go through the security policy rather than a public issue.

NPM package

The schemas, the generated TypeScript and Flow declarations, and a validator are published as @beerjson/beerjson.

npm install @beerjson/beerjson

const beerjson = require('@beerjson/beerjson')
const { valid, errors } = beerjson.validate(document)
// errors: [{ path: '/beerjson/hop_varieties/0', message: "must have required property 'name'", params: {...} }]

validate accepts a parsed document or a JSON string, and reports every error rather than stopping at the first.

To drive your own validator, the schemas are exported as a map and are also importable individually:

beerjson.schemas['hop.json']
beerjson.rootSchema // beer.json, the document entry point
require('@beerjson/beerjson/json/hop.json')

Register every schema under its filename so that cross-file $refs such as measureable_units.json#/$defs/VolumeType resolve.

TypeScript declarations are included, no @types package needed:

const recipe: BeerJSON.RecipeType = {
  / ... /
}