Welcome to the BeerJSON repository

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.

Software supporting BeerJSON

Applications and libraries that read or write BeerJSON are listed on the wiki. To add one that is missing, open an issue or a discussion.

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 discussion
• A schema change: open an issue with the schema change template first, so the working group can weigh it before code is written
• A bug in the schemas, docs, types, or tooling: open an issue
• A pull request: follow SCHEMA_STYLE.md for anything under json/, run npm run gen-docs, keep the tests green, and add a CHANGELOG.md entry

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

To pin an exact release without going through the registry, install the tarball attached to it, or the git tag directly:

npm install https://github.com/beerjson/beerjson/releases/download/v1.1.0/beerjson-beerjson-1.1.0.tgz
npm install github:beerjson/beerjson#v1.1.0

Both give the same package contents as the published one. The schemas themselves need no package manager at all: each carries a $id under raw.githubusercontent.com/beerjson/beerjson/main/json/, and a git submodule of this repository works well if you want them pinned and offline.

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 = {
  name: 'Pale Ale',
  type: 'all grain'
  // ...
}