-
Notifications
You must be signed in to change notification settings - Fork 36
This library vs implementation guidelines
The SwissQRBill library implements version 2.2 and 2.3 of the Swiss Payment Standards 2019 – Schweizer Implementation Guidelines QR-Rechnung (English version). Overall, the document is easy to understand and concise. However, there are minor contradictions and questions how to interpret the specification. This page details how this library implements parts of the specification with room for interpretation.
Generally, the German version seems to be source version and therefore the prime reference while the English version seems to be a translation (it has even some untranslated part).
The library also implements the Gestaltungsvorgaben und -empfehlungen für die QR- Rechnung (style guide)
The dimension of the payment part is given as A6 sheet and 148mm by 105mm, thus omitting the fractional part of the A6 size (148.65mm by 105.11mm) and incorrectly rounding it to the nearest integer number. This library uses the integer values 148mm, 105mm, 210mm and 62mm.
The specification says to use a line width of 0.75pt for the corner marks and refers to graphics file that can be downloaded. However, the graphics files use a line width of 0.8pt. The style guide also specifies 0.75pt. This library uses 0.75pt.
The chapter does not give any details how the address should be displayed. While a Swiss address street before house number and postal code before town, it's the other way round in the UK or in the USA. So should foreign addresses be displayed according to Swiss convention or according to the convention of the respective country? This library always uses the Swiss convention.
And what about the country code? None of the examples shows a country. It's only part of the data embedded in the QR code. This library shows the country code at the start of the address line with postal code and town for all countries except for addresses in the same country.
The text embedded in the QR code can use LF or CR + LF as separator. By default, this library uses LF when generating the QR code text as a simple measure to reduce the bit length of the QR code and increase the size of the individual blocks. This can be changed in the Bill data structured (makes only sense if the QR bill is processed by non-compliant software). It can process both types of separator when processing the embedded text. (Using a sequence of two characters as a separator was a costly mistake in MS-DOS and should never have been allowed in the QR bill standard. It just adds complexity and no benefit.)
A trailing line feed after the last mandatory or optional field (and in particular after the AltPmt element) is not allowed as the line feed serves as a separator only (unlike regular text only files that usually end the file with a line feed). However, QR bills with such trailing line feed seem to occur in practice. This library does not generate trailing line feeds at the end of the data structure but silently ignores them when decoding QR code text.
The element StrdBkgInf immediately following the element Trailer (fixed text "EPD") used to be of type "optional" (up to version 2.1 of the implementation guide) and was then changed to type "additional" (version 2.2 of the implementation guide). Thus the line feed after the trailer, which was required in many cases even though it was not followed by any data, is no longer required. Starting with version 3.0, this library omits the line feed if not data follows, preventing trailing line feeds as originally intended by the specification but incorrectly specified. When decoding QR code text, this library silently ignores trailing line feed.
For the data element CcyAmt (amount), it says to include it without leading zeros. While everybody agrees that it should be 37.50 and not 037.50 or even 000037.50, there is no universal agreement regarding amounts smaller than 1.00. Is it supposed to be 0.50 or .50? While the intent of the specification was probably 0.50, it in fact says to remove the leading zero, i.e. to use .50. However, all generators seem to implement 0.50. Most scanners accept 0.50; very few scanners reject 0.50 and a few reject .50. For best interoperability, this library includes the leading zero for amounts smaller than 1.00, i.e. 0.50 is written as 0.50. This discussion only affects the encoded QR code text, not the human-readable display.
This chapter was written when the character set was a subset of Latin-1, and it has not been updated. With the extended character set, 997 characters no longer equals 997 bytes as some characters require 2 or 3 bytes to encode. So the maximum QR code version can easily exceed version 25.
This chapter makes no sense. The QR code must be 46mm by 46mm in size and the error correction level and data content is given. Therefore, module size is a result of the other parameters and cannot be chosen.
For the maximum QR code with 117 by 117 modules, the smallest module size becomes 0.39mm, slightly below the recommended value.
This chapter mandates the use of vector graphics to scale the QR code. Does this rule out the use of pixel graphics format at all? This library supports PNG as well and describes that a sufficient high resolution should be used (about 200dpi or higher). By implementing a Canvas class, additional pixel formats can be supported.
In order to place the Swiss cross in the center of the QR code, this library first removes all modules (QR codes pixels) that would overlap with the Swiss cross (or rather with an area of 7mm by 7mm). All remaining modules are fully visible and not hidden under the cross or partially cut off by the white margin around the cross.
In the tables of examples all fields are included even if they are empty. In the QR code of the sample examples, the empty alternative scheme fields are omitted. This library only includes the alternative scheme fields if they have a value.
The first full examples with two alternative schemes seems to have an invalid QR code. The text embedded in the QR code ends with a line feed even though the last field is not supposed to have one.