Integrating CoffeeJSON

How to make an application read CoffeeJSON documents, write them, and interoperate with other implementations. This guide is non-normative. Every rule here links to its normative home in the specification.

Two roles are defined in the Overview. A consumer reads documents. A producer emits them. Most implementations are both, but the roles are independent. What conformance requires of each is specified in Versioning § Conformance. This guide covers the same rules in build order.

Consuming — the import checklist

1 · Accept the intake channels you have. Every form below carries the same envelope: a JSON object with a coffeejson version marker and its beans, recipes and tastings collections. A document arrives in one of four forms: a plain .json file with media type application/vnd.coffeejson+json and no dedicated extension, a share URL (https://<host>/r?d=<base64url payload>), a QR code encoding that same URL, or an HTTP response whose body is the document. All four carry the identical payload, so a second channel never changes your parser. Start with the URL form, which is how documents circulate.

2 · Extract from any host. The host in a share URL names who serves the fallback web page, never who may read the payload. Your scanner or link handler SHOULD attempt d= extraction on any http(s) URL, including hosts you have never seen (Transport § Accepting links from any host).

3 · Decode exactly, and reject exactly. The decode algorithm is short and fully specified in Transport § Encoding; implement it from there, where it is normative. The repository ships scan-input test vectors with expected outcomes. Run your intake against them. An importer that reads only files still runs the version vectors among them, decoding each payload to the document it carries: newer-minor, later-minor, unsupported-major, newer-major, bare-major, leading-zero-major and patch-component. The envelope's version gate is the same for a file as for a link.

Name your failures these twelve things. Each rejecting vector states the one it expects, as a kind member. Those names are the format's error vocabulary, and both reference SDKs report exactly these:

Outcome What it means TypeScript Swift
no payload no d parameter, or an empty one no_payload .noPayload
malformed base64 characters outside the base64url alphabet malformed_base64 .malformedBase64
unrecognized encoding first byte is neither { nor a zlib header unrecognized_encoding .unrecognizedEncoding
damaged compression a zlib stream that did not survive the wire damaged_compression .damagedCompression
too large past the 8192-byte cap, as sent or after inflating too_large .tooLarge
not UTF-8 the bytes are not text not_utf8 .notUTF8
not JSON text, but not JSON not_json .notJSON
not a document JSON, but no usable coffeejson member not_a_document .notADocument
unsupported version a major your build does not support, or a marker outside MAJOR.MINOR ("1", "1.0.0", "01.0") unsupported_version .unsupportedVersion
empty document neither beans nor recipes carries anything empty_document .emptyDocument
not a URL a scan that is not a URL at all — scanned input only not_a_url .notAURL
not http(s) a URL of another scheme, javascript: or data: — scanned input only not_http .notHTTP

These are decode failures only. A document that decoded and then failed your rules belongs to a separate vocabulary of your own. Do not collapse them. "Not UTF-8", "not JSON" and "not a document" are three defects with three different fixes.

4 · Gate on the major version only. A document declares its spec version in the coffeejson member. Decide support by the major component. If the major is the same and the minor is newer, accept the document. New optional fields are invisible to you. If the major is newer, you can reject it, and show a clear "unsupported version" message rather than an opaque failure. The rules and their conformance keywords are in Versioning § The version gate.

5 · Never gate imports on schema validation. The published JSON Schema is a producer gate for the current minor. It rejects vocabulary values a newer minor may define, so a valid future document can fail it. The fallback rules govern import, not validation. See Versioning § The published schema.

6 · Ignore the unknown, and fall back per vocabulary. The forward-compatibility contract is the rule every other step depends on. Ignore members you do not recognize, at any depth. Never reject a document over them. Unknown values of known fields follow each vocabulary's stated fallback, and the index table in Vocabularies lists every one. They come in three classes. Map to other where "not listed" is itself a usable answer (method, step kind, process, form). Ignore the field where a wrong guess would assert something false (roast_level, grind size, party type, each with its named recovery). Derive from the document where the data answers the question (basis — whether a recipe is measured to its brewed water or to what lands in the cup — from the quantities present; origin.type from the item count).

7 · Convert units, or treat the measurement as absent. Units travel as canonical identifiers (gram, celsius, bar), never display symbols. Convert anything you recognize into your own canonical store. Treat a measurement with an unrecognized unit as absent. Never guess, and never show the wire identifier verbatim (Vocabularies § Units).

8 · Preserve step order, and show what you do not model. A recipe's steps array order is authoritative. Preserve a step kind you do not model (a pour-over app that meets tamp) and show it read-only. See Recipe § Mixed-capability consumers.

9 · Resolve bean↔recipe association by the one rule. An explicit bean_ref wins, by exact, case-sensitive match. An unresolved reference leaves the recipe unlinked, never an error. A single co-located bean associates by position. Otherwise entities are independent (Envelope § Association).

10 · Preserve on re-share. When you re-emit an unedited document you did not author, carry the members you did not recognize rather than strip them. When you rebuild a document from your own model you may drop what you do not carry, and you say so. The round-trip / re-author distinction is Overview § Preservation on re-share.

Producing — the export checklist

1 · Emit canonical, locale-neutral identifiers. Emit machine ids for everything enumerable (pour_over, washed, gram). The consumer renders localized labels. Emit URL-valued fields in URI form. Emit the linking members — id, bean_ref, recipe_ref — in Unicode NFC, which bean_ref ↔ id matching depends on, and human text in NFC too where you can. Emit derived step labels as absent. For gear the gear registry does not carry, emit id: "custom" with a label, and brand and model where you know them, rather than a slug of your own: a Gear object's id is a registry slug or "custom", and a slug the registry does not carry matches nothing. For gear it does carry, emit its slug and omit brand and model, which the registry supplies. The compact statement of all producer obligations is Versioning § Conformant producer.

2 · Lint your output with the authoring schema. The authoring variant closes every object except the reserved ext member, and rejects empty optional arrays. It requires bean_ref on every recipe once you emit more than one bean, and rejects brand and model beside a registered gear id. A typo'd field name then fails your build loudly instead of being silently ignored by every consumer forever. A second coffee cannot quietly unlink the recipes that were associated with the first. It is a producer lint only. Never validate imports against it.

3 · Do not emit reserved names. Put private data under ext. The reserved extensions are named growth areas. Do not emit them as if defined. Vendor-private data is the one exception: put it under the vendor-extension member ext, keyed by your vendor identifier. Do not invent bare members on spec entities.

4 · Share from your own domain, and run a fallback page. A share link lives on your domain (yourapp.example/r?d=…). Platform app-association binds domains to apps, so your link is your app's link. Run a fallback page that decodes client-side and renders a preview. Chat clients routinely open links in in-app browsers that bypass app association (Transport § Deep-linking). Your page SHOULD NOT log the d parameter (Transport § Privacy).

5 · Prefer self-contained QR codes. A QR that carries the document in the ink works offline and needs no infrastructure. Every CoffeeJSON-aware scanner can read it regardless of the printed host (Transport § QR code). Keep documents lean so the code stays scannable. Trim content. Never truncate a document. A code printed on a coffee bag has its own guidance (Transport § Printed on a bag).

Test against the repository

The fixture corpus is the executable contract:

Reference implementations live beside the spec. @coffeejson/core (TypeScript: types, codec, a total normalize) and @coffeejson/react (renderer components) are in this repository's packages/. coffeejson-swift covers Apple platforms. They track the format and version independently under semver. See Versioning & conformance.

List your implementation

registries/implementations.json lists what implements CoffeeJSON (apps, hosted services, libraries, machines) and the transport surfaces each one reads and writes. Fallback pages use the reading half to offer "open in your app" handoffs. Something that only publishes documents belongs there as much as something that only imports them. A one-line pull request adds yours. An optional icon, a square image added under the site's public/showcase/ in the same pull request, appears beside your name on the showcase. Registration buys visibility, never interoperability.