QRBundle (.qrb)

QRBundle is an open file format for storing and sharing collections of QR codes.

A QRBundle file (.qrb) packages multiple QR codes together with metadata such as titles, notes, prices, images, and location. Bundles can be saved, shared, and opened across different applications.

Overview

QRBundle allows multiple QR codes and related metadata to be grouped together in a single portable file.

Example use cases:

• Product collections in retail stores
• Travel guides
• Conference resources
• Restaurant menus
• Influencer product lists
• Personal QR collections

File Extension

.qrb

MIME Type

application/vnd.qrbundle

File Format

A .qrb file is a ZIP archive.

Example structure:

bundle.qrb ├── manifest.json ├── qrset.json └── assets/

Optional file:

mimetype

Contents of mimetype: application/vnd.qrbundle

Schemas & examples

Normative JSON Schemas for the root JSON files (format 1.0):

• schema/qrbundle.schema.json — manifest.json ($id: https://constagility.com/ns/qrbundle/1.0/qrbundle.schema.json; manifest must include "schema": "qrbundle/1.0")
• schema/qrset.schema.json — qrset.json ($id: https://constagility.com/ns/qrbundle/1.0/qrset.schema.json)

A minimal pair of documents (not a full ZIP) lives in examples/minimal-bundle/. The sample manifest uses "schema": "qrbundle/1.0" (the only value allowed by the v1.0 manifest schema).

Stability & Compatibility

QRBundle follows strict backward compatibility rules.

• Existing fields will not be removed
• New fields may be added
• Unknown fields must be ignored by readers
• .qrb extension and MIME type remain stable
• manifest.json and qrset.json remain permanent root files

Breaking changes require a new schema version (e.g. qrbundle/2.0).

Reference Implementation

Implemented in the NxtTools mobile application on iOS & Android platforms:

• Website
• App Store
• Google Play

npm package

Published as qrbundle (schemas, webfont, SVG source, examples).

npm install qrbundle

Paths inside node_modules/qrbundle/:

| Use case | Path (from package root) | | ---------------- | --------------------------------------------------------- | | JSON Schemas | schema/qrbundle.schema.json, schema/qrset.schema.json | | Webfont + CSS | fonts/qrbundle.css (+ .woff2, .woff, .ttf) | | SVG glyph source | icons/qrbundle.svg | | Sample JSON | examples/minimal-bundle/ |

Bundlers (Vite, webpack, etc.): import the stylesheet so @font-face URLs resolve:

import 'qrbundle/fonts/qrbundle.css';

Then use the <qrb> markup from Icon font (qrbundle) (codepoint U+F101). If font files fail to load, copy fonts/* into your app’s static/public directory and link CSS from there.

Publishing (maintainers)

1. npm login (npm account required).
2. Bump "version" in package.json when releasing.
3. Regenerate fonts if icons/qrbundle.svg changed: yarn install && yarn build:font, then commit fonts/.
4. Verify tarball contents: npm pack --dry-run.
5. Publish: npm publish.

Development

This repo is a Yarn project (package.json + yarn.lock, package version 0.1.0). That npm semver can move independently of the bundle format version (1.0 / "schema": "qrbundle/1.0"). Tooling here is for format assets (schemas, icon font); it is not a reference .qrb reader/writer.

Layout: schema/ · examples/ · icons/qrbundle.svg (glyph source) · fonts/ (generated by yarn build:font).

yarn install

Formatting (Prettier):

yarn format        # write
yarn format:check  # CI / verify only

Generated fonts/ and **/*.svg are excluded (see .prettierignore) so Fantasticon output and glyph paths stay stable.

Icon font (qrbundle)

• Source glyph (for the build): icons/qrbundle.svg — Fantasticon turns every .svg in icons/ into a glyph; keep only this file there unless you intend more icons.
• SVG rules (Fantasticon / svg2ttf): avoid circle (use short polygon paths), evenodd, compound “hole” paths (svg2ttf often fills them solid—hollow QR finders use four frame rects + center instead), and rx/ry on transformed rects (can cause streaks).
• Overlapping fills & winding: TrueType uses non-zero winding. Extra shapes that overlap the wireframe (e.g. round corner caps) must use the same winding direction as the main quads; opposite winding shows up as white holes / “shattered” corners in the font preview even when the SVG looks fine.
• In apps / docs: prefer the fonts/qrbundle webfont (see below) or embed icons/qrbundle.svg as a flat black asset if you need a single SVG.

Regenerate TTF / WOFF / WOFF2 and CSS after editing the font source:

yarn build:font

Outputs go to fonts/ (qrbundle.ttf, qrbundle.woff2, qrbundle.css, preview qrbundle.html, qrbundle.ts, etc.) — same basename as the source SVG.

The default glyph maps to Private Use codepoint U+F101 (decimal 61697), class .qrb-qrbundle in the generated stylesheet. The CSS font-family name is qrbundle.

Important: fonts/qrbundle.css applies the icon font to qrb[class^="qrb-"]::before, so the markup must use the custom qrb element (or set font-family: qrbundle yourself and insert the character).

<link rel="stylesheet" href="fonts/qrbundle.css" />
<qrb class="qrb-qrbundle" aria-hidden="true"></qrb>

Plain span + same class will not work with the default CSS. For a span, use the codepoint directly:

<link rel="stylesheet" href="fonts/qrbundle.css" />
<span class="my-icon" aria-hidden="true">&#xf101;</span>

.my-icon {
  font-family: 'qrbundle', sans-serif;
  font-size: 2rem;
  line-height: 1;
}

Open fonts/qrbundle.html in a browser to verify the build. If the glyph looked “wrong” before, ensure .fantasticonrc.js does not set a small numeric round (that crushes path precision).

Governance

QRBundle is an open specification maintained by Const Agility, LLC.

Repository contents are licensed under the Apache License 2.0 — see LICENSE.