Barcodes & QR Codes: Fundamentals

A symbology is the rule set that turns data into a pattern: which characters are allowed, how each is drawn, how the start and end are marked and how a reader can check that it read the pattern correctly. Symbologies fall into two families.

Linear (one-dimensional) barcodes encode data in the widths of parallel bars and spaces. A reader sweeps a line across them, either with a laser or with a camera that looks at one row of pixels, which is why a linear barcode has to be printed with its bars perpendicular to the scan direction and why a small scratch across the bars (not along them) can ruin a read. The symbologies a Java developer meets most often are these.

Two-dimensional (matrix or stacked) codes use both directions, so they hold much more data in a small area, they can be read by a camera from any rotation and they carry real error correction.

The choice follows from the reader and the data. A scanner at a till that only reads linear codes forces EAN or Code 128. A person pointing a phone at a printed page expects a QR code. A label of a few millimetres wants a DataMatrix. A regulation can also decide for you: the invoice QR codes discussed in Regulated QR Codes on Invoices & Payments must be QR codes of a given size and error-correction level, whatever the layout designer prefers.

As a concrete linear example, the check digit that the last position of an EAN-13 carries is easy to compute and a common source of invalid test data. Digits in odd positions (counting from the left, starting at one) have weight 1, digits in even positions weight 3, and the check digit is whatever brings the weighted sum up to a multiple of ten. The same modulo-10 rule is used by every GTIN length.

The example needs only the JDK. It was compiled with --release 21 and run, and it prints 4006381333931, which is the example GTIN used throughout the GS1 documentation. The rule it implements is specified in the GS1 General Specifications, GS1 General Specifications.

A QR code is a square grid of dark and light modules. A module is the smallest unit of the symbol: one cell, printed either dark or light. A QR symbol always has an odd number of modules per side, and that number depends on the version. Versions run from 1 to 40; version 1 is 21 by 21 modules and every further version adds four modules per side, so the side in modules is 4 * version + 17, up to 177 by 177 modules for version 40. Besides the 40 versions of the full symbol, ISO/IEC 18004 defines Micro QR (versions M1 to M4, one finder pattern only) and, in its newer editions, rectangular Micro QR (rMQR); the examples on this page produce only the full symbol, so the small variants are not covered further.

The figure shows a version 2 symbol, 25 by 25 modules, with the fixed structures that every reader looks for before it tries to decode a single data bit. The data area of the drawing is a schematic filling, not the pattern of any real message.

Before the bits are written, the encoder splits the message into segments and picks the most compact encoding mode for each.

Further segment types exist for ECI designators, for splitting a message over several symbols (structured append) and for the FNC1 marker that makes a QR code a GS1 QR code. The encoder may mix segments, and the capacity of a symbol is a function of its version, its error-correction level and the mode used.

Three physical quantities decide whether a printed code is read.

The module size (called the X-dimension for linear codes, the width of the narrowest bar) is the size of one module on paper. Everything else scales with it: a version 5 code at 0.5 mm per module is 37 modules times 0.5 mm, that is 18.5 mm, plus the quiet zone. Guidance for linear retail codes comes from the GS1 General Specifications, which give a nominal X-dimension of 0.33 mm for an EAN-13 and allow magnifications between 80 % and 200 % of the nominal size (check the current edition of the specification for the exact table, because it differs by symbology and by scanning environment). For QR codes there is no universal minimum, since it depends on the scanner. A widely used rule of thumb for printed codes read with a phone is 0.4 to 0.5 mm per module or more, and the density a printer produces must make the module an integer number of printer dots, otherwise the module edges are blurred by anti-aliasing. These are rules of thumb from practice, not requirements of the standard.

The print resolution sets the grid on which the module has to sit. At 300 dpi a printer dot is 25.4 / 300 = 0.0847 mm, so a module of four dots is 0.34 mm and one of six dots 0.51 mm. At 600 dpi the dot is 0.0423 mm, so a module of 0.5 mm is 11.8 dots and is rounded unevenly by the printer driver, while 0.42 mm (10 dots) is exact. A thermal label printer at 203 dpi has a dot of 0.125 mm, so a module of 0.5 mm is exactly four dots. A PDF is resolution independent, so the rule applies to the printer that finally rasterises it, not to the PDF; choosing a module size that is a multiple of the target dot pitch keeps the result sharp on that printer, and a display or a mobile viewer will scale it anyway.

The quiet zone is clear space around the symbol, and the required width differs by symbology. A QR code needs four modules on every side. Code 128 needs a margin of 10 times the X-dimension on both left and right, EAN-13 needs 11 on the left and 7 on the right (the human-readable digits are printed in that space, which is why the left digit of an EAN-13 sits outside the bars), and DataMatrix needs one module. The quiet zone has to be light and free of print: a coloured band, a table border or text touching the symbol destroys the contrast the reader relies on. This is the most common reason that a code looks fine on screen but fails on paper. A QR code placed inside a table cell needs a cell padding of at least four modules, and a code drawn with a "margin" hint of zero must be placed on a white rectangle that is larger than the symbol.

Contrast matters as much: dark modules on a light background, with a ratio large enough to be read by infrared and red-light scanners, which see red as white; avoid red or yellow bars. Inverted codes (light modules on a dark background) are read by many but not all readers, so a printed document should keep the conventional polarity.

A barcode can reach the page in two ways, and the choice matters more in a PDF than on a web page.

A raster barcode is a bitmap, a PNG, drawn as an image. It has a fixed number of pixels, so when it is scaled the viewer or the printer has to resample it. If the bitmap is scaled by a non-integer factor, module edges blur and a code that was readable at one size becomes marginal at another. Rasters are acceptable only when the target resolution is known and the bitmap is created at an integer multiple of it, with image smoothing switched off.

A vector barcode is drawn with fill operators: each dark module (or each bar) is a rectangle, and adjacent modules are merged into one path. The viewer or the printer renders the geometry at its native resolution, the edges are as sharp as the device allows, the file is small (a version 3 symbol is a few hundred bytes of content stream) and the code can be enlarged without losing quality. The quiet zone is simply a white rectangle behind the symbol or empty space. Vector is the right default for a PDF that will be printed or archived. Its only disadvantage is that a code made of hundreds of rectangles is a larger drawing than a single image object, which is negligible on an invoice.

The following example draws a QR code as vector rectangles with iText Core. The module matrix comes from ZXing with its own margin disabled, so that the quiet zone is drawn explicitly and its size is visible in the code: four modules, and a module size of exactly 0.5 mm. All dark modules are added to one path and filled once.

iText is released under the AGPLv3 or a commercial licence, and Bookshelf Billing only uses it here to draw rectangles. Whether that licence is acceptable for a closed-source service is a decision for your own legal review; the licence choice and its consequences are explained in Introduction & Approaches. ZXing is Apache-2.0.

The example compiled for Java 21 against ZXing 3.5.4 and iText Core 9.8.0 and was run; it wrote a one-page A4 PDF and printed 29 modules, symbol 18.5 mm square including quiet zone (a 40-character payload at level M is a version 3 symbol). The PDF was not scanned with a reader in this verification, so the pattern was checked only by the module count and the symbol size. In the PDF, the y coordinate grows upwards, which is why the row index is flipped; the transformation matrix and the other drawing operators are explained in Low-level Canvas & Graphics. The derivation of the drawing is documented by the iText knowledge base, How to generate a 2D barcode as a vector image, and the PdfCanvas API is at PdfCanvas. The ready-made iText classes that do the same, including BarcodeQRCode, are used in Barcodes with iText, ZXing & Okapi.

Two more notes on PDFs. A barcode drawn in the content stream is invisible to assistive technology, so a code that carries information a person needs should have an alternative text or be tagged as an artifact with its data repeated as text next to it; tagging is covered in PDF/A & PDF/UA with iText. And a PDF that is printed through a driver that converts everything to bitmaps at a low resolution (some virtual printers and fax gateways) turns even a vector code into a raster one, so a code that must survive such a path needs a module size that is large relative to that resolution.

GS1 is the standards body behind retail and logistics identification. Its General Specifications define how data structures are encoded in barcodes, and several of its choices recur in every business application.

The GS1 rules apply only when a partner or regulation requires them; an internal invoice number is best served by a plain Code 128 or by the URL pattern of a QR code. If you do need GS1 data, make sure that the library can produce the FNC1 start character, since not every encoder can. The official documents are the GS1 General Specifications, the GS1 Digital Link standard and the GS1 guideline for 2D barcodes in retail.

Barcode generation in Java is a solved problem, but not every library that is still easy to find is maintained. The state below is as of 2026-10-09.

The practical recommendation for a new Spring Boot service is the following. Use ZXing to encode when you only need QR or the common symbologies, because it is small, permissively licensed and its BitMatrix can be drawn by any PDF library. Use the iText classes when you are already inside an iText document and want the codes to be vector objects of the PDF without extra code. Use Okapi Barcode when you need a symbology that ZXing does not write (check its symbology list on the project site) or vector output as SVG or EPS. Use Barcode4J and Barbecue only because an existing JasperReports template already references them, and plan to replace them, as discussed in Barcodes in JasperReports. Before adopting a library for a regulated use case check its licence and maintenance status on the project site, because both change.

A sizing and verification checklist closes the topic. Whatever the library, a code that matters should be verified in the same way it will be used: print the real PDF on the real printer at the real size, scan it with the real devices (a handheld scanner, an older phone, a current phone), and decode the generated image back with ZXing in a unit test so that a regression in the payload is caught before printing. A verifier that grades print quality against ISO/IEC 15415 or 15416 is the professional tool for GS1 labels, and a free phone app is not a replacement for it.

Books from the iText 1 and 2 era, which were consulted for the order of topics here and are not reproduced, show barcodes as the first-generation iText classes of the com.lowagie.text.pdf package, drawn through PdfContentByte, and they mention only a few symbologies. In current iText the classes live in the separate barcodes module of the itext-core artifact (package com.itextpdf.barcodes), draw through PdfCanvas and PdfFormXObject, and the QR code and the 2D symbologies are first-class. The books also predate QR codes in everyday use. Other points to avoid today: