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.

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

elapsed: 3:30
water in: 300g

60 g120 g180 g240 g300 g

Drag a pour: its line of the file changes with it.

tetsu-kasuya-4-6-basic.json the whole file · brew it at real speed

{"coffeejson": "1.1","recipes": [{"title": "Tetsu Kasuya 4:6 Method (basic)","description": "Tetsu Kasuya's World Brewers Cup-winning 4:6 pour-over: five equal pours — the first 40% of the water tunes taste, the last 60% sets strength.","method": "pour_over","coffee": { "value": 20, "unit": "gram" },"water": { "value": 300, "unit": "gram" },"ratio": 15,"water_temp": { "value": 93, "unit": "celsius" },"grind": { "size": "medium_coarse" },"steps": [{ "at_s": 0, "to_water": { "value": 60, "unit": "gram" }, "instruction": "first pour — sweetness phase" },{ "at_s": 45, "to_water": { "value": 120, "unit": "gram" }, "instruction": "second pour" },{ "at_s": 90, "to_water": { "value": 180, "unit": "gram" }, "instruction": "third pour — strength phase" },{ "at_s": 130, "to_water": { "value": 240, "unit": "gram" }, "instruction": "fourth pour" },{ "at_s": 160, "to_water": { "value": 300, "unit": "gram" }, "instruction": "fifth pour" }],"finish_s": 210,"lang": "en","notes": "The original specifies a grind between medium-coarse and coarse; size carries the finer end of that range. Philocoffea publishes this method on a Japanese page and an English one, and they disagree on two pours: the Japanese original cues the fourth at 2:10 and the fifth at 2:40, the English translation at 2:15 and 2:45. This document follows the Japanese, which is the language the method was published in first.","author": { "name": "Tetsu Kasuya", "type": "person" },"based_on": "https://philocoffea.com/?mode=f3"}]}

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.

As a file

{
  "coffeejson": "1.1",
  "recipes": [
    {
      "title": "Everyday V60",
      "coffee": { "value": 15,  "unit": "gram" },
      "water":  { "value": 250, "unit": "gram" },
      "ratio":  16.7
    }
  ]
}

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.

Open it in the viewer Validate your own

In a link
coffeejson.org/r/?d=eyJjb2ZmZWVqc29uIjoiMS4xIiwicmVjaXBlcyI6W3sidGl0bGUiOiJFdmVyeWRheSBWNjAiLCJjb2ZmZWUiOnsidmFsdWUiOjE1LCJ1bml0IjoiZ3JhbSJ9LCJ3YXRlciI6eyJ2YWx1ZSI6MjUwLCJ1bml0IjoiZ3JhbSJ9LCJyYXRpbyI6MTYuN31dfQ
The same document as an address. Nothing is stored and nothing is looked up.
On a bag

The same document again, as a code to print. A whole recipe fits too: Tetsu Kasuya’s 4:6, every timed pour, inside one square.

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

Every pour schedule in the corpus, each drawn from its own steps and all to one scale — the longest brew is the full width, the largest the full height. 24 of the 64 recipes state one. One implementer so far, and more are wanted — tell us what you are building, or where the format is wrong.

Early. CoffeeJSON 1.1 is settled in shape and still being polished — tell us where the model 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

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.

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.

Forward-compatible reads — valid today, valid as the format grows.
Locale-neutral ids — every app renders its own language.
CC0 spec, schema and corpus; Apache-2.0 packages, patent grant included.
Nothing to join. Disagree and you fork it — that’s the guarantee.

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

Integration guideThe consumer and producer checklists
SpecificationEnvelope, Recipe, Bean, Tasting, vocabularies
JSON SchemaDraft 2020-12
TransportFile, share URL, QR
Fixture corpusValid and invalid, checked in CI

Write it in one app, open it in the next.