The QRCODE Image Format

1. Introduction

Representing relatively small amounts of data in a machine-readable format has been important for decades. The humble UPC barcode format, for instance, allows storing numeric values up to ten decimal digits.

As time has passed, tho, we’ve required larger amounts of data to be represented (even if the amounts are still modest; a few kilobytes at most), and better error correction (UPC barcodes can correct for one wrong digit, but no more). Many approaches have been proposed and even adopted in various industries, but the QR Code, first invented in Japan in the 90s for labeling parts in semi-automated factories, has emerged as the clear leader in overall usage across the world in recent years.

While QR Code images are very usable in practice, they’re difficult to create; beyond the ordinary difficulties of creating any image file programmatically, the QR format is non-trivial to follow, and the error-correction parts of the format are complex. However, all the devices a user can expect to see a QR Code have access to libraries for creating them.

This specification defines a new QRCODE image format, and its associated MIME type image/qrcode, which represents the content of a QR code in a simple, human-readable, hand-authorable format. User agents, such as browsers, that recieve QRCODE images are expected to render them as QR codes.

2. Notes

Parameters of a QR code:

• "version": a number between 1 and 40, dictating the overall size in pixels/"modules". The eventual size of the QR code is version * 4 + 17 modules, plus additional margin space around the code (typically, at least one module in width).

• error-correction level: what level of error correction is applied to the payload, dictating how much of the code can be lost/obscured/misread without corrupting the code itself. Four values, corresponding to "low" (7% recoverable loss), "medium" (14%), "quartile" (25%), or "high" (30%).

• mask type: to help avoid large black or white "fields" in the code that make it harder to read or recognize, some of the data pixels can be inverted. There are 8 mask types, dictating which pixels are inverted and should be read as their opposite value.

• encoding type: how to interpret the bits in the payload. Three commonly-used value: "numeric", "alphanumeric", and "bytes".

  • Numeric is the digits 0-9.

  • Alphanumeric is 0-9, A-Z (uppercase only), and some punctuation. Aka a subset of ASCII.

  • Bytes has been defined by specs as two different byte-based character encodings. In practice, treating it as UTF-8 seems to be modern practice and is widely recognized by scanners (possibly heuristically).

Additional params I need to introduce:

• module size: a number of CSS pixels dictating the side length of a module.

• image size: a number of CSS pixels dictating the overall image size (which dictates the module size).

  • using both module and image size would just ignore one of them, I guess. Maybe use the larger one.

• margin?: a CSS pixel size for the safe area around the code

3. Image Format

Every QRCODE image must begin with the bytes 51 52 43 4f 44 45 7b (spelling "QRCODE{" in ASCII). Following that are zero or more non-7d bytes (the parameter bytes), followed by a 7d byte ("}" in ASCII), optionally followed by 0d 0a bytes (CR and NL in ASCII), followed by zero or more bytes with any value (the payload bytes).

A QRCODE image that does not follow this byte format is invalid.

QRCODE{}
https://example.com

QRCODE{version=5;error=low;mask=3;modulesize=5;margin=2}
https://example.com

3.1. Parameters

The parameter bytes are interpreted into the QR code parameters, which affect how the QR code image is generated. The format is intentionally identical to how MIME-type parameters are interpreted.