CoffeeJSONBrowseShowcaseImplementationsValidatorGenerateGitHub

A coffee recipe that opens anywhere

Write it in one app, open it in the next. Print it on a bag, paste it in a message, keep it as a file. Dose, water, temperature and every timed pour arrive as numbers — in the reader’s own units and language.

Browse the recipes Make your app read it

A recipe that travels

A recipe here is a file, not a picture of one. It rides inside a link, prints as a QR code on a bag, and exports out of one app into the next — with the dose, the water, the temperature and every timed pour still readable as numbers.

So a roaster can put the brew guide on the bag. A creator can publish a routine a timer follows, instead of a viewer pausing the video to write it down. And a library outlives whichever app made it — including this one.

What a document looks like

Everything past the three required fields is whatever you happen to know — this one states its water both ways, as a weight and as a ratio.

{
  "coffeejson": "1.1",
  "recipes": [
    {
      "title": "Everyday V60",
      "coffee": { "value": 15,  "unit": "gram" },
      "water":  { "value": 250, "unit": "gram" },
      "ratio":  16.7
    }
  ]
}
Open it in the viewer Validate your own
QR code — scan to open Tetsu Kasuya’s 4:6 recipe
A real one: Tetsu Kasuya’s 4:6, every timed pour, inside the square. Scan it and your phone brews along.

It already ships

64
recipes, each attributed to its source
51
bags, from 20 roasters
3
packages — TypeScript, React, Swift
1
app on the App Store

One implementer so far, and more are wanted — tell us what you are building, or where the format is wrong.

What it takes

Two functions: JSON in, your recipe type out, and back again. Required: a title, a dose, and either the water or the ratio. A reader ignores the rest — and is required to, so what you write this month still reads next year.

Mapped field by field against Visualizer’s and BeanConqueror’s public models: on the bean side, one field in sixteen had no home. Either could read it tomorrow. No account, no endpoint, no SDK you have to take.

Read the integration guide

Why it’s safe to build on

The shape of the format is answering bugs that already happened, in public trackers: a value read in the wrong unit, a category compared as a display string, corruption nothing validated for months. Hence canonical units, machine ids, and a schema to fail against.

What it doesn’t do

Dose, water, temperature and timing travel exactly; grind and espresso dialing still need your gear. There’s no cup-score field yet — a score without its scale is worse than no score.

Questions

What is CoffeeJSON?

CoffeeJSON is an open file format for coffee recipes and bean identity. One JSON document carries the dose, the water, the temperature, the grind and the timed pour schedule, together with the bean the coffee was made from — so an app can read a recipe another app wrote, instead of an importer written per vendor.

Where can I use a CoffeeJSON document?

Anywhere a file or a URL goes. A document moves between two apps, rides whole inside a share link, prints on a bag of coffee as a QR code, publishes on a web page as schema.org Recipe, and sits on your own disk as plain JSON. There is no server to call and no account to make.

How do I add CoffeeJSON to my app?

Validate documents against the published JSON Schema, then read them with a reference package or with your own code. Packages exist for TypeScript, React and Swift, and a document is plain JSON, so any language can read one. The integration guide carries the consumer and producer checklists.

Is CoffeeJSON free to use?

Yes. The specification, schema, fixtures and registries are CC0 — public domain, no attribution required and no conditions attached. The reference packages are Apache-2.0, patent grant included. There is nothing to sign up for and no organization to join: disagree with a decision and you can fork the format.

Who is using CoffeeJSON today?

One app on the App Store, and it is the author's own: BrewSmart, which has read and written the format since July 2026. More are wanted. If you build a coffee app, a roaster's site or a brewing service, get in touch — help writing the importer and exporter is yours for the asking, and so is a conversation about what the format gets wrong.

Read the spec