Transport

A CoffeeJSON document is JSON. It is transport-agnostic: the data model says nothing about how the bytes get from one place to another. This document describes the recommended bindings, ways to move a document that interoperate cleanly. They are conventions, not part of the core format. A producer is free to use any of them or none.

Four bindings are described here:

Binding Best for Infra
File Backup, library export, attachments none
Share URL Sharing one recipe over any channel a fallback page
QR code Print, in-person, bag-to-cup none
HTTP A catalog, or an endpoint that already exists a server

All four carry the identical payload, the same JSON document, so adding one later never requires a format change.

File

A document can be written to a plain .json file with the media type application/vnd.coffeejson+json. CoffeeJSON reserves no dedicated extension.

Share URL

A document can be made self-contained inside a URL by carrying the whole payload in a query parameter:

https://<host>/r?d=<base64url( utf8( document-JSON ) )>

For example:

https://coffeejson.org/r?d=eyJjb2ZmZWVqc29uIjoiMS4wIiwicmVjaXBlcyI6W3sidGl0bGUiOiJFdmVyeWRheSBWNjAiLCJjb2ZmZWUiOnsidmFsdWUiOjE1LCJ1bml0IjoiZ3JhbSJ9LCJ3YXRlciI6eyJ2YWx1ZSI6MjUwLCJ1bml0IjoiZ3JhbSJ9fV19

which decodes to:

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

The payload rides in the query, never the fragment. Chat and social clients linkify a URL only up to #, so a fragment-carried document is dropped at the tap. Nothing defines or emits a fragment form. A consumer parses ?d= and nothing else.

Two general rules regardless of binding:

The rules above are the producer's side. A consumer that scans QR codes or accepts pasted or shared links SHOULD attempt payload extraction on any http(s) URL. It parses the URL, reads the d query parameter, and decodes per Encoding, regardless of the URL's host, including hosts it has never seen. The host names who serves the fallback page, never who may read the payload.

A scanner hands you text, not a URL, and text that is not a URL at all is the ordinary case. So the first two steps are checks rather than parsing. Reject what is not a URL, then what is not http(s). The scheme check comes before the payload is read. A javascript: or data: URL can carry a well-formed payload, and an implementation that decodes first has already treated it as a share link. A consumer that then opens what it scanned is one step from executing it. Both cases are named in the scan vectors.

The reference implementations expose the whole binding as one call: decodeScanned(text) in @coffeejson/core, and ShareLink.importDocument(fromScanned:) in coffeejson-swift. An adopter does not have to reassemble it from this prose.

A scanner that recognizes only its own domain lets any other producer's QR fall through to the browser. The user lands on that producer's fallback page instead of importing into the app in hand.

The fixture corpus ships scan-input test vectors: own-host, foreign-host, extra-parameter, malformed, non-UTF-8, oversized, and empty-envelope inputs, each with its expected outcome. A rejecting vector carries a kind, the name this failure has in the failure vocabulary both reference SDKs report, so an implementation asserts on the vector's own word rather than on a name table of its own. A consumer can test its link intake against this contract directly, and the repository's own harness executes them.

Privacy, honestly

Encoding

Deep-linking and the fallback page

How a URL opens a specific app is a platform concern (deep-link / app-association mechanisms), outside the scope of CoffeeJSON. Two consequences shape what a share link can do:

QR code

A QR code encodes the same payload as the share URL: either the self-contained https://…/r?d=… URL or, for print reliability at higher data density, a short hosted URL that resolves to the document.

The choice is the producer's. The encoded document is identical either way. The binding is host-agnostic. A roaster prints the QR against its own domain if it wants the scan to land on its page, or against a neutral format host. Every CoffeeJSON-aware reader decodes the same d= payload regardless of host.

Printed on a bag

A coffee bag is a hard place to print a code. The label is small, curved and glossy. The code has to scan for as long as the bag exists. The person scanning it is often in a kitchen with a poor connection.

This section adds no rule about documents. A bag carries an ordinary document, and every reader that reads a share link reads it. The section says how a producer chooses what that document holds.

A bag with one recommended recipe and one more:

{
  "coffeejson": "1.1",
  "beans": [
    {
      "name": "Nano Challa",
      "roaster": { "name": "Example Roastery" },
      "origin": { "type": "single", "items": [{ "country": "ET", "region": "Guji" }] },
      "process": ["washed"],
      "roast_level": "light_medium",
      "roast_date": "2026-06-20",
      "rest_days": { "min": 7, "max": 45 }
    }
  ],
  "recipes": [
    {
      "title": "Roaster's V60",
      "method": "pour_over",
      "recommended": true,
      "brewer": { "id": "hario-v60" },
      "coffee": { "value": 15, "unit": "gram" },
      "water": { "value": 250, "unit": "gram" },
      "water_temp": { "value": 94, "unit": "celsius" }
    },
    {
      "title": "French Press",
      "method": "french_press",
      "brewer": { "id": "french-press" },
      "coffee": { "value": 30, "unit": "gram" },
      "water": { "value": 500, "unit": "gram" },
      "water_temp": { "value": 96, "unit": "celsius" }
    }
  ]
}

Compressed, that document makes a URL of 487 characters on coffeejson.org. Two scan vectors pin these shapes: bag-bean-only is a bag with no recipe, and bag-recommended is this document as a compressed code.

HTTP

A document can be served over HTTP at a URL, like any other resource. This is the binding for a producer that already runs a service: an endpoint that returns a recipe adds a CoffeeJSON representation of it, and every CoffeeJSON-aware consumer can read the result.

The trade-off is the mirror of the self-contained forms'. A hosted document can be corrected after the link is shared, so printed matter pointing at it stays current — and it stops working when its host does, or when the reader is offline. That durability is what the file and the self-contained share URL buy, and what they give up. The choice is the producer's, and a producer can offer both: the document is the same either way.

Compression

The payload of a share URL or QR code MAY be compressed with zlib (RFC 1950) before Base64. The compression covers the payload and nothing else. A document in a file, an HTTP body, a clipboard, or a .json attachment is plain JSON, unchanged.

Why zlib. Its first byte is (CINFO << 4) | CM, and CM is always 8 for deflate. The low nibble cannot be B, so a zlib stream can never begin {. That makes the discriminator below structural and free. Raw DEFLATE gives no such guarantee.

The discriminator. The two forms are told apart by one byte, after the Base64 decode. A consumer MUST commit to the branch that byte selects:

Two rules that decide whether an implementation is correct:

What a reader needs. A share-link consumer needs a Base64 decoder, a zlib inflate, and a JSON parser. The inflate is the one addition, and not an exotic one. Every browser ships DecompressionStream, and every server runtime and mobile platform has an equivalent. What it costs is legibility. A plain payload can be pasted into a console and read, and a compressed one cannot. That cost is confined to this transport. In a file, an HTTP body, or a clipboard, a CoffeeJSON document is still plain JSON.