Machine translation without native-speaker review. The English version is binding. · македонски English
DurableQR map file, format version 1
A map file is the complete routing table of one DurableQR account: for every code, where a scan goes today. It exists so that the codes you printed can keep working without DurableQR. Any resolver that reads this file and follows the rules in "Resolving" below gives a scan the same status code, target, path handling and privacy headers as DurableQR, with the one exception stated there.
The format is open. This document, the validator and the example files are the whole specification. Design decisions and their reasons: ADR-0006 (docs/adr/0006-map-file-v1.md, in Polish).
Files
A map file comes in one of two encodings with identical content:
*.csv— comma-separated values,*.jsonl— JSON Lines, one JSON value per line.
Each map file is published together with <file name>.sha256 (see "Checksum").
Byte rules (both encodings)
- UTF-8, without a byte order mark.
- Lines end with LF (
\n). CR (\r) never appears. - The file ends with exactly one LF. No empty lines.
- Line 1 announces the format and version (see each encoding below).
- One record per code. Records are sorted by
stable_idin ascending byte order, and eachstable_idappears once. - Only one serialisation is valid for given data (canonical form), so the same data always produce the same bytes and the same checksum.
A file with no records is valid: it is the format line (and, for CSV, the column header) and nothing else.
Columns
Every record has exactly these seven fields, in this order:
| Column | Type | Meaning |
|---|---|---|
stable_id | 10 characters from 0-9 A-Z without I L O U | The code's identifier, the path segment printed in the QR code. |
current_url | URL, or absent | Where the code sends a scan now. Absent if and only if state is deleted. |
fallback_url | URL, or absent | The owner's fallback. Absent when the owner declared none; always absent when state is deleted. |
updated_at | timestamp | When version version was created, i.e. when the code last changed. Every change moves it: destination, fallback, rollback, pause, resume and deletion. |
actor | lowercase 8-4-4-4-12 hexadecimal subject | The account user whose change created version version: their identity-provider subject, e.g. 0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40. Not an e-mail address. |
version | integer, 1 to 9007199254740991 | Version number of the code. Starts at 1 and grows by one with every change to the code: destination, fallback, rollback, pause, resume or deletion. A deleted code carries the version its deletion created. |
state | one of active, grace, frozen, paused, blocked, deleted | Lifecycle state of the code. See "Resolving". |
URL. Starts with http:// or https:// (scheme in any letter case) and has at least one character after //; at most 2048 bytes in UTF-8. Exactly these code points are forbidden:
- U+0000 to U+001F;
\(U+005C);- every code point Python's
str.isspace()calls whitespace: U+0009 to U+000D, U+001C to U+001F, U+0020, U+0085, U+00A0, U+1680, U+2000 to U+200A, U+2028, U+2029, U+202F, U+205F, U+3000.
Nothing else is forbidden: DEL (U+007F), U+FEFF, the C1 controls other than U+0085, ,, ", &, <, > and any other non-ASCII character may appear. The URL is stored byte for byte as the owner entered it: no normalisation, no added slash. The validator does not check the host grammar; the DurableQR backend does when a URL is entered.
Timestamp. UTC, exactly YYYY-MM-DDTHH:MM:SS.mmmZ with three millisecond digits and a literal Z, e.g. 2026-09-01T08:15:02.041Z. It must be a real instant: a day that exists in its month (leap years included), hour 00-23, minute and second 00-59. No leap second, no offset, no other precision.
History. A version 1 map file carries only the current state of each code, not earlier destinations. Destination history is not part of this format; each code’s history is available through the API and the panel.
CSV encoding
# durableqr-map-file format_version=1
stable_id,current_url,fallback_url,updated_at,actor,version,state
3KQ7M2XWZP,https://example.com/menu,,2026-09-01T08:15:02.041Z,0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40,1,active
4HT9R6NCVB,"https://example.com/catalogue?lang=pl,en",https://example.com/,2026-09-12T17:40:59.900Z,0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40,3,active
- Line 1: exactly
# durableqr-map-file format_version=1. - Line 2: exactly the seven column names above, in that order.
- Lines 3 onwards: one record each, RFC 4180 with LF line endings.
- A field is enclosed in double quotes if and only if it contains
,or". A"inside a quoted field is written twice (""). No field ever contains a line break. - An absent value is an empty field.
versionis written in decimal without leading zeros.
Writing it with Python's standard library produces the canonical form:
f = open(path, "w", encoding="utf-8", newline="")
f.write("# durableqr-map-file format_version=1\n")
w = csv.writer(f, lineterminator="\n") # default QUOTE_MINIMAL
w.writerow(COLUMNS)
for r in records:
w.writerow(["" if r[c] is None else r[c] for c in COLUMNS])
Reading it with a stock CSV library: skip line 1, then read with a header. In Python: f = open(path, encoding="utf-8", newline=""); next(f); rows = csv.DictReader(f). Empty fields come back as ""; treat them as absent.
JSONL encoding
{"format":"durableqr-map-file","format_version":1}
{"stable_id":"3KQ7M2XWZP","current_url":"https://example.com/menu","fallback_url":null,"updated_at":"2026-09-01T08:15:02.041Z","actor":"0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40","version":1,"state":"active"}
- Line 1: exactly
{"format":"durableqr-map-file","format_version":1};format_versionis a JSON integer, not a string. - Every further line is one JSON object with exactly the seven keys, in column order.
- An absent value is
null, never"".versionis a JSON integer. - Canonical form: no whitespace between tokens. Inside strings the only escapes are
\",\\and, for U+0000 to U+001F, the formsJSON.stringifywrites:\b,\t,\n,\f,\rfor U+0008, U+0009, U+000A, U+000C, U+000D and\u00xxwith lowercase hex for the rest. Everything else is written as itself, including/,&,<,>, U+2028, U+2029 and all non-ASCII characters. (With the column rules above, only\"can occur in a valid file: URLs exclude controls and\.) This is exactly what JavaScriptJSON.stringify(record)produces, and Pythonjson.dumps(record, separators=(",", ":"), ensure_ascii=False)with the keys inserted in column order.
Format version
A reader must check format_version on line 1 before reading anything else and must refuse any value it does not know: a later version may have different columns. This document defines version 1 only.
Checksum
The checksum is SHA-256 over the exact bytes of the map file, format line included. It is published next to the file as <file name>.sha256 in the format of sha256sum: 64 lowercase hexadecimal digits, two spaces, the bare file name (no directory), LF. Run sha256sum from the file's own directory so it writes the bare name.
56434275ccc78eac27629649b77f0ee4c4ea193dc95d5c27cb2c89a4d007a5fe example.csv
Check it without any DurableQR tool: sha256sum -c example.csv.sha256, or on macOS shasum -a 256 -c example.csv.sha256.
Resolving
A resolver answers a scan of https://<host>/<stable_id>. The identifier is the first segment of the request path: leading and trailing / are ignored, anything after the next / is ignored, and the query string is not part of the path (handler.py:194-196). It is matched exactly, letter case included. For an empty identifier, or a stable_id with no record in the file, it answers 404. For a record, the answer depends on state and on whether fallback_url is present:
state | fallback_url | Answer | DurableQR source |
|---|---|---|---|
active, grace, frozen | any | 302 to current_url | decision.py:126-127 |
paused | present | 302 to fallback_url | decision.py:114-115 |
paused | absent | 200, a neutral "paused" note, no advertising | decision.py:117-118, handler.py:142 |
blocked | any | 200, an abuse note with the appeal procedure¹ | decision.py:111-112, handler.py:143 |
deleted | (always absent) | 404, identical to "no record" | decision.py:108-109, handler.py:144 |
¹ DurableQR's appeal address is today a placeholder, abuse@durableqr.com, marked in the code as to be replaced by a monitored address before the first code is blocked (handler.py:101-105).
Every response a resolver produces, redirect or not, carries these headers. DurableQR's resolver does (handler.py:31-34, :160-163), with two exceptions that come from its infrastructure rather than its code and may lack them: a 5xx when the routing record cannot be read (handler.py:36-39), and the refusal of any method other than GET and HEAD. Neither is a redirect. The headers are:
Cache-Control: no-store, so that a changed destination takes effect on the next scan;Referrer-Policy: no-referrer, without which the destination site would receive the code's identifier in theRefererheader on every scan;Content-Type: text/html; charset=utf-8.
A 302 carries Location set to the URL byte for byte and an empty body. If a record's URL for the chosen answer is missing, the answer is 404, never a 302 with an empty Location (handler.py:170-181).
Sources are in the DurableQR backend: decision.py is services/functions/resolver/logic/decision.py, handler.py is services/functions/resolver/handler.py (commit ba0aed1).
What the table means in words:
graceandfrozenare billing states. They never change where a scan goes; a resolver treats them exactly likeactive.blockedoutranks the fallback: a blocked code does not redirect anywhere, even when a fallback is set.- A deleted code (a tombstone) answers exactly as if it never existed, and a fallback does not rescue it. Tombstones stay in the file so that their identifiers are never given to a different destination.
- A resolver that is handed a
stateoutside the six values (which a valid version 1 file never contains) should treat it asactive, as DurableQR does (handler.py:218-223).
What this file does not reproduce. DurableQR also monitors each destination. When a destination is failing and the owner has set a fallback, DurableQR sends an active, grace or frozen code to fallback_url (decision.py:120-121). The monitor's verdict is not in the map file: it is a live observation, not the owner's instruction, and nothing outside DurableQR would keep it current. A resolver working from this file therefore always sends those codes to current_url. Every other answer in the table is the same as DurableQR's.
Validator and examples
The reference validator is webapp/scripts/check-map-file.mjs (Node.js 22, no dependencies beyond the standard library):
cd webapp
npm run check:map-file -- path/to/map.csv path/to/map.jsonl
It checks every rule in this document and the .sha256 file next to each map file, and reports each problem with its line number. It exits 0 when every file passes.
Example files, one record per state plus URLs that need CSV quoting and a non-ASCII URL, both encodings with the same content: webapp/scripts/__fixtures__/map-file-v1/ (example.csv, example.jsonl and their .sha256 files). They are the conformance fixtures for exporters and resolvers: the DurableQR export is tested against them. When the data change, the .sha256 files are regenerated in the same commit.