Machine translation without native-speaker review. The English version is binding. · hrvatski 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:

Each map file is published together with <file name>.sha256 (see "Checksum").

Byte rules (both encodings)

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:

ColumnTypeMeaning
stable_id10 characters from 0-9 A-Z without I L O UThe code's identifier, the path segment printed in the QR code.
current_urlURL, or absentWhere the code sends a scan now. Absent if and only if state is deleted.
fallback_urlURL, or absentThe owner's fallback. Absent when the owner declared none; always absent when state is deleted.
updated_attimestampWhen version version was created, i.e. when the code last changed. Every change moves it: destination, fallback, rollback, pause, resume and deletion.
actorlowercase 8-4-4-4-12 hexadecimal subjectThe account user whose change created version version: their identity-provider subject, e.g. 0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40. Not an e-mail address.
versioninteger, 1 to 9007199254740991Version 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.
stateone of active, grace, frozen, paused, blocked, deletedLifecycle 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:

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

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"}

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:

statefallback_urlAnswerDurableQR source
active, grace, frozenany302 to current_urldecision.py:126-127
pausedpresent302 to fallback_urldecision.py:114-115
pausedabsent200, a neutral "paused" note, no advertisingdecision.py:117-118, handler.py:142
blockedany200, 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:

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:

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.

Destination history file v1 · hrvatski