# CoffeeJSON

> CoffeeJSON is an open, locale-neutral JSON format for sharing coffee recipes and bean identity. A recipe stops being a screenshot and becomes data any app can read, validate, and brew from. The spec prose and the JSON Schema are CC0 — public domain, no attribution required, no conditions.

## Specification

- [Overview](https://coffeejson.org/docs/spec/01-overview.md): What CoffeeJSON is, the design rules, and how to read the spec
- [Document envelope](https://coffeejson.org/docs/spec/02-envelope.md): The top-level shape: the `coffeejson` version string, `recipes[]`, `beans[]`, `tastings[]`
- [Recipe](https://coffeejson.org/docs/spec/03-recipe.md): Recipe fields: quantities, `basis`, steps, grind, gear, attribution, scaling
- [Bean](https://coffeejson.org/docs/spec/04-bean.md): Bean identity: roaster, origin, process, roast level, altitude
- [Tasting](https://coffeejson.org/docs/spec/05-tasting.md): How a brewed cup turned out: the drinker's impression, and what an instrument read
- [Vocabularies & registries](https://coffeejson.org/docs/spec/06-vocabularies.md): The controlled value sets, how they extend, and the fallback rules
- [Versioning & conformance](https://coffeejson.org/docs/spec/07-versioning.md): Compatibility contract, reserved extensions, what conformance requires

## Guides

- [Integration guide](https://coffeejson.org/docs/integration-guide.md): The consumer and producer checklists: intake, decode, fallback rules, preservation, authoring lint, share links
- [Transport](https://coffeejson.org/docs/transport.md): Carrying a document in a URL or QR code: encoding, size limits, fallbacks

## Machine-readable

- [JSON Schema (v1.0)](https://coffeejson.org/schema/1.0): The normative schema, served at its `$id`. Validate any document against this
- [Authoring schema](https://coffeejson.org/schema/authoring/1.0): Stricter variant for generators: rejects unknown keys apart from the reserved `ext`, so a typo fails loudly instead of being ignored
- [Gear registry](https://coffeejson.org/registries/gear.json): Canonical equipment slugs (id · label · brand/model) for the Gear id field
- [Varietal registry](https://coffeejson.org/registries/varietals.json): Canonical varietal names plus aliases for common synonyms and breeding codes
- [Addition-type registry](https://coffeejson.org/registries/addition-types.json): Recommended values for an addition's type — an open set, so any other string is valid
- [Producer-role registry](https://coffeejson.org/registries/producer-roles.json): Recommended values for a party's role — an open set, so any other string is valid
- [Implementations registry](https://coffeejson.org/registries/implementations.json): Self-declared implementations — apps, services, libraries — and the transport surfaces each reads and writes
- [Full spec as one document](https://coffeejson.org/llms-full.txt): Every chapter concatenated, for loading into a single context
- [Agent instructions](https://coffeejson.org/agents.md): The canonical agent-facing description of this site: what it serves, how to emit and validate a document, and what the crawl policy asks

## Tools

- [Validator](https://coffeejson.org/validator/): Paste a document, URL, or file and check it against the schema — runs entirely in the browser
- [Recipe directory](https://coffeejson.org/recipes/): Transcribed real-world recipes as valid documents; each names and links its source. The same corpus by bag at ?view=beans — bean identity, roaster, origin, and the recipes brewed with it
- [Generator](https://coffeejson.org/generate/): Build a valid document from a form, then share it as a link, QR code, or file
- [For AI agents](https://coffeejson.org/agents/): How to emit valid CoffeeJSON: a system-prompt snippet, worked examples, the mistakes models make, and the validate-and-fix loop
- [Implementations](https://coffeejson.org/implementations/): The reference SDKs for TypeScript and Swift, the conformance corpus any implementation can run against its own code, and the self-declared registry of apps that read and write the format
- [Showcase](https://coffeejson.org/showcase/): The five places a CoffeeJSON document goes — between two apps, on a bag of coffee as a QR code, inside a share link, on a web page as schema.org Recipe or Product, and as a plain file you keep — plus the software that reads and writes the format today

## Agent skills

- [Agent skills](https://github.com/coffeejson-org/skills): Three skills, one per relationship to the format, for a coding agent that reads `SKILL.md`. Install with `npx skills add coffeejson-org/skills`, or as a Claude Code plugin
- [coffeejson-schema](https://github.com/coffeejson-org/skills/tree/main/skills/coffeejson-schema): Changing the format: validating the schema and its corpora, designing a field, rename or reshape, and landing it fixture-first
- [coffeejson-integration](https://github.com/coffeejson-org/skills/tree/main/skills/coffeejson-integration): Adding CoffeeJSON to an app, service, site or script: intake and export checklists, the failure vocabulary, the version gate, the transport bindings, and proving conformance
- [coffeejson-author](https://github.com/coffeejson-org/skills/tree/main/skills/coffeejson-author): Turning one published source into a document: faithful transcription, where each fact lands, the vocabularies and registries, and the authoring lint

## Notes

- License: the spec prose, schema, fixtures, registries, and the corpus's structure and transcription are CC0 — no attribution required, no conditions. Quoted roaster prose inside corpus documents remains the quoted source's, carried with attribution. The SDK packages (@coffeejson/core, @coffeejson/react, coffeejson-swift) are Apache-2.0.
- Every document declares its version in the `coffeejson` key; compatibility rules are in the versioning chapter.
- Units are explicit and canonical (grams, celsius, bar) — never inferred from locale.
- Interoperability, measured field by field against the public data models of the Visualizer and BeanConqueror projects: on the bean side one field in sixteen had no home in CoffeeJSON. Either could read the format without a schema change.
- A whole recipe fits in a QR code. Documents travel as a file, as a share URL carrying the document in the query string, or as that URL printed as a QR — no server, no account, no lookup.
- What CoffeeJSON is not: it is not a control-profile format (pressure and flow curves over time belong to formats like OEPF), not a cupping-score format (no cup-score field exists — a score without its scale is worse than no score), and not a service. There is nothing to sign up for and no endpoint to call.
- Minimum valid document: the `coffeejson` version string, a recipe `title`, a `coffee` quantity, and either a `water` quantity or a ratio. A reader is required to ignore members it does not know, so documents stay readable as the format grows.