El formato de archivo .qrb explicado

Yo diseñé este formato, así que lee el resto con eso en mente

Construí el formato .qrb para NxtTools, la app de utilidades todo-en-uno que hace mi empresa. Soy Jangul Aslam, y NxtTools la hace Const Agility, LLC desde Houston, Texas, EE. UU. Hoy NxtTools es el único software que produce y abre archivos .qrb, así que el artículo que estás leyendo viene sesgado. Estoy explicando un formato que yo mismo escribí, y tengo un interés obvio en que lo uses.

Lo que no voy a hacer es disfrazar esto de un repaso neutral de formatos de archivo. Esto es un ingeniero contándote por qué una colección de códigos QR necesitaba un formato propio, qué hay físicamente dentro de un .qrb, y dónde el formato se detiene deliberadamente antes de pretender ser un estándar universal. Si llegaste aquí para saber si un .qrb seguirá abriéndose dentro de tres años, la respuesta es sí, y te voy a mostrar la parte de la especificación que la convierte en una promesa real y no en una frase de marketing.

TL;DR

• Un archivo .qrb es un ZIP. Renómbralo a .zip, ábrelo, y puedes leer cada byte. No hay binario propietario ni DRM.
• Por dentro hay tres cosas: manifest.json (qué es el bundle), qrset.json (la lista ordenada de entradas) y un directorio assets/ para cualquier imagen por entrada.
• Cada entrada guarda el payload QR sin procesar en un campo value, más etiquetas y metadatos opcionales. Como el payload se conserva, NxtTools vuelve a renderizar un QR escaneable a partir de cada entrada cuando abres el archivo.
• El esquema está versionado como qrbundle/1.0 con una garantía escrita de retrocompatibilidad: los campos existentes nunca se eliminan, y los campos desconocidos deben ser ignorados por los lectores.
• El formato es abierto y está documentado en github.com/ConstAgility/qrbundle. Hoy es un formato nativo de NxtTools, no un estándar universal como PDF. Esa honestidad importa, y la cubro abajo.

Por qué una colección de códigos QR necesita un archivo

La objeción obvia es: ¿por qué no mandar simplemente una lista de enlaces? Para el caso más común (un puñado de URLs de sitios web), podrías. Pero "un Bundle QR es una lista de enlaces" es justo lo que el formato tuvo que superar, por dos razones.

La primera es la estructura. Una pila de enlaces no tiene forma. El punto entero de un bundle es que la persona del otro lado abre un solo archivo y ve tus veinticinco opciones de muebles como un único conjunto con nombre, no como un muro de texto suelto. El texto plano pierde eso en el momento en que sale de tu teléfono. El artículo pilar, ¿Qué es un Bundle QR?, recorre el día que me lo hizo concreto.

La segunda razón es la que la gente pasa por alto: no todo código QR es un enlace. Un código QR puede codificar una conexión de Wi-Fi, un número de teléfono, un evento de calendario o una etiqueta de devolución de un envío cuyo payload no es una URL en absoluto. Si un bundle solo guardara URLs, no podría contener esas cosas. Por eso el formato guarda el payload escaneable sin procesar de cada entrada, sea un enlace o no, que es justo el punto que cubren los casos de uso de Bundle QR con el ejemplo de las devoluciones de Amazon. Una lista de enlaces físicamente no puede hacer ese trabajo.

Hay precedentes para "codificar datos estructurados en una forma portable" — vCard y MeCard llevan décadas haciéndolo con las tarjetas de contacto, y son excelentes exactamente en eso. Pero una vCard describe un solo contacto. No existe una forma establecida, abierta y basada en archivos de entregarle a alguien un conjunto ordenado y etiquetado de payloads QR arbitrarios. Ese hueco es lo que llena .qrb.

Qué hay realmente dentro de un .qrb

Abre uno y encontrarás una estructura pequeña y deliberadamente aburrida:

Un bundle que escribe NxtTools va etiquetado con honestidad. El manifest.json lleva "schema": "qrbundle/1.0", un createdBy de NxtTools y un id de app de origen com.constagility.nxttools, así que cualquier lector (incluso uno futuro que yo todavía no haya escrito) puede saber de dónde vino el archivo.

Las entradas viven en qrset.json. Cada una lleva un campo value, y value es el payload QR sin procesar: los bytes exactos que obtendrías si escanearas el código con una cámara. Para un QR de sitio web es la URL. Para una etiqueta de devolución de un envío es lo que sea que haya codificado el transportista. Junto a value, una entrada puede llevar campos opcionales: un marcador de tipo, un título legible para humanos, una marca de tiempo de escaneo, además de notas, un precio, coordenadas o referencias a imágenes. NxtTools hoy escribe el subconjunto de enlaces de eso: el payload sin procesar de cada código, reunido bajo un solo nombre de bundle. Los campos por entrada más ricos existen en el formato y los aprovecha un producto aparte, al que llegaré.

Conservar el payload sin procesar es lo que hace que un bundle sea más que un álbum de capturas de pantalla. Cuando NxtTools abre un .qrb, lee cada value y vuelve a renderizar un QR fresco y escaneable a partir de él. Una etiqueta de devolución que agrupaste hace tres semanas sigue escaneándose en el mostrador del transportista, porque el archivo conservó el dato, no una foto del código. Esa única propiedad es la razón por la que el formato guarda payloads en lugar de imágenes renderizadas.

¿Es lo mismo que el .qrb de Qt o el .qrb de la blockchain Nxt?

No. La aclaración merece un párrafo porque .qrb es, francamente, una extensión compartida y prefiero decirlo de entrada. Si buscaste .qrb antes de llegar aquí, probablemente viste un puñado de proyectos sin relación:

• Qt Resource Bundle. La herramienta rcc de Qt compila los assets de una aplicación en un .qrb binario para apps de Qt de escritorio y embebidas. Lo genera la herramienta de compilación, no humanos. Por dentro es un bloque binario compilado específico de Qt, sin manifest y sin JSON.
• NetBrain Runbook. Un formato de runbook de automatización de redes que usan las herramientas de NOC de NetBrain. Nada que ver con códigos QR y nada que ver con nosotros.
• Los "Nxt Tools" de Jelurida y la blockchain Nxt. Un proyecto de criptomonedas más viejo llamado "Nxt" que es como una década anterior a esta app. Los repos NxtTools de GitHub en ese espacio de nombres son para monederos de la blockchain Nxt y herramientas de nodos. Otro "Nxt", otras "tools", otro producto. No somos nosotros.
• Robótica LEGO Mindstorms NXT. Los repos qreal/nxt-tools y trikset/nxt-tools son herramientas educativas de robótica para el viejo bloque NXT. Tampoco somos nosotros.

Si tienes un .qrb enfrente y no estás seguro de cuál es, la prueba es mecánica. Descomprime el nuestro y obtienes un manifest.json que lleva "schema": "qrbundle/1.0", un qrset.json con entradas QR y un directorio assets/. Descomprime uno de Qt y obtienes una sección binaria compilada sin manifest y sin JSON. El tipo MIME application/vnd.qrbundle es el árbitro formal — Qt no registra un MIME en absoluto y se identifica por una firma de bytes en la cabecera. El tamaño del archivo también es una pista rápida: un bundle de NxtTools con cinco códigos QR suele estar por debajo de 50 KB; un Qt resource bundle para una app de escritorio real suele pesar megabytes.

La parte que lo convierte en una promesa real: no se va a pudrir

Un formato de archivo solo es confiable si un archivo que haces hoy se abre dentro de varios años. La especificación de .qrb en github.com/ConstAgility/qrbundle lo deja escrito como reglas, no como buenos deseos.

La cadena de esquema qrbundle/1.0 está versionada a propósito. La especificación se compromete a tres cosas en lenguaje claro. Los campos existentes nunca se eliminan. Se pueden agregar campos nuevos. Y los campos desconocidos deben ser ignorados por los lectores, de modo que una app más vieja que abre un bundle más nuevo se salta los campos que no entiende en lugar de atragantarse con ellos. Un cambio incompatible no puede ocurrir en el mismo lugar; requiere una nueva cadena de versión, qrbundle/2.0, que los lectores viejos pueden reconocer y manejar deliberadamente.

La extensión .qrb, el tipo MIME application/vnd.qrbundle y los nombres de archivo permanentes manifest.json y qrset.json también están fijados como estables entre versiones. Suma eso a que el formato es un ZIP plano de JSON plano, y el peor caso es tranquilizador: incluso si desaparecieran todas las apps que leen .qrb, podrías descomprimir el archivo y leer tus datos en cualquier editor de texto. Esa es la garantía de "tus bundles no se van a pudrir", y es la razón por la que publiqué la especificación de forma pública en lugar de guardarla dentro de la app.

NxtTools escribe la mitad simple — a propósito

Dije que el formato lleva más de lo que NxtTools escribe. Aquí va la cuenta honesta. NxtTools escribe enlaces: el payload sin procesar de cada código, guardado bajo un solo nombre de bundle. El lado más rico de tarjeta de ítem del formato cubre entradas que llevan una etiqueta por entrada, una foto de producto, un precio, una ubicación de tienda o tus propias notas — y el reordenamiento y las tarjetas de ítem que las hacen legibles. Ese lado le pertenece al próximo producto QRly, hoy en modo sigiloso con una nota de En desarrollo…. El mismo formato .qrb por debajo; más de sus campos puestos a trabajar encima.

Esa división es una estrategia, no un accidente. Un formato solo importa si la gente lo adopta, y gratis más simple es como se adopta. NxtTools escribe la forma útil más simple de .qrb gratis, sin cuenta, para que el formato salga al mundo. QRly aprovechará el resto.

Cuándo NxtTools no es la opción correcta

El formato se gana su lugar para un trabajo específico. Estos son los casos donde no, dichos sin rodeos.

• Solo tienes un enlace. Un formato de archivo es una complicación sin recompensa para una sola URL. Un código QR simple o solo mandar el enlace es más práctico. Si quieres una sola imagen QR imprimible, un generador web gratis como QRCode Monkey hace una sin instalación y sin cuenta. Recurre a un bundle solo cuando un código no es suficiente — la línea entre los dos es el tema entero de Bundle QR vs código QR.
• Tu destinatario no va a instalar una app. Un .qrb es hoy un formato nativo de NxtTools. No es un estándar universal como lo es PDF — no hay soporte integrado del sistema operativo, y el destinatario necesita NxtTools para abrir el archivo. Para una entrega puntual a un desconocido, un solo código QR o un enlace público son de menor fricción. Prefiero que lo sepas de entrada a que lo descubras cuando le mandes un bundle a alguien que no puede abrirlo.
• Estás compartiendo una sola tarjeta de contacto. vCard es la herramienta correcta, punto. Es un estándar abierto de hace décadas que todo teléfono, cliente de email y libreta de direcciones ya lee. Envolver un contacto en un .qrb no te compra nada y le cuesta una instalación a tu destinatario.

Donde el bundle es la forma equivocada, gana una herramienta más simple, y prefiero apuntarte hacia ella. Pero la app que instalarías para leer un .qrb no es una app de un solo truco. NxtTools también incluye un escáner de documentos, herramientas de PDF, herramientas de imagen y un pad de firma en la misma instalación gratis — así que la próxima vez que necesites escanear un contrato o reducir un PDF en tu teléfono, no estás buscando otra descarga. El formato es estrecho por diseño; la app a su alrededor no.

FAQ

¿Qué es un Bundle QR y cómo funciona?

Un Bundle QR es un archivo con la extensión .qrb que guarda una lista ordenada de códigos QR. Por dentro es un ZIP que contiene un manifest.json que describe el bundle, un qrset.json que lista cada entrada y un directorio assets/ para cualquier imagen. Lo creas en tu teléfono y luego compartes el archivo como un PDF. El destinatario lo abre y ve cada entrada en una sola vista, sin ningún código QR maestro de por medio.

¿Cómo agrupo varios códigos QR en uno?

Escanea o pega cada código en un solo Bundle QR y ponle un nombre. NxtTools guarda todo el conjunto como un único archivo .qrb que puedes compartir como cualquier otro documento. Como el formato guarda el payload sin procesar de cada código, el bundle vuelve a renderizar cada entrada como un QR escaneable cuando se abre — así una etiqueta de devolución agrupada sigue siendo una etiqueta de devolución que funciona, no solo una captura de pantalla.

¿Qué son los códigos QR compartibles?

Los códigos QR compartibles son códigos que recolectas y envías como conjunto en lugar de escanearlos de uno en uno. Un Bundle QR es el archivo que lo hace posible: un .qrb que guarda el payload sin procesar de cada código. Lo envías por AirDrop, iMessage, WhatsApp o email como cualquier archivo. No hay página pública ni servicio de alojamiento de por medio — los códigos viven en el archivo que entregaste.

¿Cuál es la mejor app de Bundle QR?

NxtTools es la app de Bundle QR hoy, porque es la única app que escribe y lee el formato .qrb. Crea bundles en tu teléfono gratis y sin cuenta, y el formato que escribe está documentado en una especificación pública en github.com/ConstAgility/qrbundle. Una experiencia más rica de tarjeta de ítem sobre el mismo formato viene aparte en QRly. Si solo necesitas una sola imagen QR estática, un generador web simple es más práctico que cualquier app de bundle.

Obtén NxtTools

El formato .qrb solo importa si puedes crear uno en unos pocos toques, así que Bundles QR viene gratis en NxtTools sin cuenta requerida. La misma instalación también te da un escáner de documentos, herramientas de PDF, herramientas de imagen y un pad de firma.

• iPhone & iPad — App Store
• Mac (Apple Silicon, M1 y posteriores) — Mac App Store (la misma app de iPad, se instala nativamente como aplicación de escritorio; las Macs con Intel no son compatibles por esta vía)
• Android — Google Play

Si la visión más rica de tarjeta de ítem construida sobre el mismo formato es lo que realmente quieres, qrly.space es hacia donde va eso.