The Barcode XML format

This page describes the XML format used by Barcode4J to define barcodes. It also contains notes about the message format supported by each symbology.

The general structure of the Barcode XML format looks like this:

<barcode message="123456789">
    <{type}>
      {barcode-specific configuration}
    </{type}>
</barcode>

Replace {type} with the name of the barcode type, ex. "ean13" or "code39". You can also use the fully qualified classname of the implementing class, ex. "org.krysalis.barcode4j.impl.Code39". If you use a name it will be resolved internally using the BarcodeClassResolver interface.

General structure in XSLT Stylesheet

When implementing with Usage with Xalan-J, Usage with SAXON, or Usage with FOP, the general structure of the Barcode XML format changes slightly, to include the barcode namespace. For example, when using Barcode 4J with FOP, it looks like this:

<barcode:barcode
    xmlns:barcode="http://barcode4j.krysalis.org/ns"
    message="123456789">
  <barcode:{type}>
    {barcode-specific configuration}
  </barcode:{type}>
</barcode:barcode>

The barcode-specific configuration is a set of elements and attributes defined by the barcode implementation itself. Please see further down for specifics. But here's an example:

<barcode>
  <intl2of5>
    <height>10mm</height>
    <wide-factor>2.5</wide-factor>
  </intl2of5>
</barcode>

The values for the configuration elements are of various datatypes:

• {boolean}: The values true|yes|on or false|no|off.
• {string}: A simple unicode string of text like "Hello123".
• {number}: A number such as "2.43" or "5".
• {unit}: length unit, one of mm, cm, or pt.
  • The default unit is normally "mm" (Millimeters) but is implementation-dependent.
  • A special unit supported in certain places is "mw" (module width). This is used in certain 1D barcode to specify values like "10 times the module width", ex. for the quiet zone.
• {length}: A length in the form "{number}[[ ]{unit}]". Examples: 1.2mm, 5.0, 3, or 10mw.
• {checksum-mode}: The checksum mode determines the behaviour for checksums. Possible values (not all values are supported by all barcode formats):
  • add: the checksum is automatically added to the message.
  • check: the checksum is checked while rendering the barcode.
  • ignore: no checksum processing is done.
  • auto: Enables the barcode type's default behaviour.
• {human-readable-placement}: This enumeration determines the placement of the human-readable part of a barcode. Possible values:
  • bottom: the message is placed at the bottom of the symbol.
  • top: the message is placed at the top of the symbol.
  • none: no human-readable part is generated.
• {baseline-alignment}: This enumeration determines the alignment of the lines of barcodes such as POSTNET.
  • bottom: Short and long lines are aligned at the bottom.
  • top: Short and long lines are aligned at the top.
• {font-name}: As the name says, a font name used in outputting <font-name/>. Note that not all fonts are available for all output formats.

Datatypes below are often given in the format "{length:15mm}". The value after the datatype indicates the default value.

The Barcode XML format can be "abbreviated" (thereby accepting all default values) as in this Code 39 example:

<barcode message="123456789">
  <code39/>
</barcode>

In this case, the defaults are assumed, and the result is effectively:

<barcode message="123456789">
  <code39>
    <height>15mm</height>
    <module-width>0.19mm</module-width>
    <wide-factor>2.5</wide-factor>
    <interchar-gap-width>1mw</interchar-gap-width>
    <quiet-zone enabled="true">10mw</quiet-zone>
    <checksum>auto</checksum>
    <human-readable>
      <placement>bottom</placement>
      <font-name>Helvetica</font-name>
      <font-size>8pt</font-size>
      <display-start-stop>false</display-start-stop>
      <display-checksum>false</display-checksum>
    </human-readable>
  </code39>
</barcode>

The configuration for the default implementation is:

<barcode>
  <intl2of5>
      <height>{length:15mm}</height>
      <module-width>{length:0.21mm}</module-width>
      <wide-factor>{number:3.0}</wide-factor>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <checksum>{checksum-mode:auto=ignore}</checksum>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
        <display-checksum>{boolean:false}</display-checksum>
      </human-readable>
  </intl2of5>
</barcode>

Notes

• The height should be at least 0.15 times the barcode's length or 0.25 inches, whichever is larger.
• The module width (width of narrow element) should be at least 7.5 mils (a mil is 1/1000 inch) or 0.19mm.
• The multiple for the wide element should be between 2.0 and 3.0 if the narrow element is greater than 20 mils. If the narrow element is less than 20 mils, the ratio must exceed 2.2.
• Quiet zones must be at least 10 times the module width or at least 0.25 inches.
• display-checksum controls whether the calculated checksum should be included in the human-readable part.

Message format

• Valid characters are 0-9.

Code 39 is also known as: USD-3, 3 of 9 code

The configuration for the default implementation is:

<barcode>
  <code39>
      <height>{length:15mm}</height>
      <module-width>{length:0.19mm}</module-width>
      <wide-factor>{number:2.5}</wide-factor>
      <interchar-gap-width>{length:1mw}</interchar-gap-width>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <checksum>{checksum-mode:auto=ignore}</checksum>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
        <display-start-stop>{boolean:false}</display-start-stop>
        <display-checksum>{boolean:false}</display-checksum>
      </human-readable>
  </code39>
</barcode>

Notes

• The height should be at least 0.15 times the barcode's length or 0.25 inches.
• The module width (width of narrow element) should be at least 7.5 mils (a mil is 1/1000 inch) or 0.19mm.
• The multiple for the wide element should be between 2.0 and 3.0 if the narrow element is greater than 20 mils. If the narrow element is less than 20 mils, the multiple can only range between 2.0 and 2.2.
• Quiet zones must be at least 10 times the module width or 0.10 inches, whichever is larger.
• The intercharacter gap width (igw) is 5.3 times the module width (mw) if mw is less than 10 mils. If mw is 10 mils or greater, the value for igw is 3mw or 53 mils, whichever is greater. However, for quality printers, igw often equals mw.

Message format

• Valid characters are 0-9, A-Z and the characters: - . $ / + % SPACE
• The implementation currently doesn't support the extended character set.
• The character '*' is only used as start and stop character and may not be used in the message. The '*' character is automatically added before and after the message even though you may not see it in the human-readable part. (See also "display-start-stop" and "display-checksum" values)
• display-start-stop controls whether the start and stop characters should be included in the human-readable part. Setting display-start-stop to true, automatically sets display-checksum to true, too.
• display-checksum controls whether the calculated checksum should be included in the human-readable part.

also known as: EAN/UCC 128

The configuration for the default implementation is:

<barcode>
  <code128>
      <height>{length:15mm}</height>
      <module-width>{length:0.21mm}</module-width>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
      </human-readable>
  </code128>
</barcode>

Notes

• The height should be at least 0.15 times the barcode's length or 0.25 inches.

Message format

• Valid characters: The full 7 bit ASCII (US-ASCII) character set is supported
• Functions 1 to 4 may be used. They are encoded as ASCII characters 0xF1 (241), 0xF2 (242), 0xF3 (243) and 0xF4 (244) in the message.

also known as: USD-4, NW-7, 2 of 7 code

The configuration for the default implementation is:

<barcode>
  <codabar>
      <height>{length:15mm}</height>
      <module-width>{length:0.21mm}</module-width>
      <wide-factor>{number:3.0}</wide-factor>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
      </human-readable>
  </codabar>
</barcode>

Notes

• No checksums are implemented at the moment

Message format

• Valid characters are 0-9, the characters: - $ : / . +
• Start and stop characters are: a b c d e * n t

The configuration for the default implementation is:

<barcode>
  <upc-a>
      <height>{length:15mm}</height>
      <module-width>{length:0.33mm}</module-width>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <checksum>{checksum-mode:auto=add|check}</checksum>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
      </human-readable>
  </upc-a>
</barcode>

Message format

• Valid characters are 0-9
• Message length must be 11 or 12 characters depending on the checksum mode.
• Behaviour when checksum-mode is set to auto: If a 11-character message is passed in, the check character is added. If a 12-character message is passed in, the check character is checked.
• Supplementals are supported (2 and 5 characters). You can add them by appending a "+" along with the supplemental message to the barcode message. Example: 037145007991+51528

The configuration for the default implementation is:

<barcode>
  <upc-e>
      <height>{length:15mm}</height>
      <module-width>{length:0.33mm}</module-width>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <checksum>{checksum-mode:auto=add|check}</checksum>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
      </human-readable>
  </upc-e>
</barcode>

Message format

• Valid characters are 0-9
• Message length must be 7 or 8 characters depending on the checksum mode.
• Behaviour when checksum-mode is set to auto: If a 7-character message is passed in, the check character is added. If a 8-character message is passed in, the check character is checked.
• The first character (number system) must be 0 or 1.
• You can pass in a UPC-A message (12 or 13 characters) to generate a UPC-E barcode. If the UPC-A message cannot be converted to a UPC-E message you'll get an exception.
• Supplementals are supported (2 and 5 characters). You can add them by appending a "+" along with the supplemental message to the barcode message. Example: 0123413+77

The configuration for the default implementation is:

<barcode>
  <ean-13>
      <height>{length:15mm}</height>
      <module-width>{length:0.33mm}</module-width>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <checksum>{checksum-mode:auto=add|check}</checksum>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
      </human-readable>
  </ean-13>
</barcode>

Message format

• Valid characters are 0-9
• Message length must be 12 or 13 characters depending on the checksum mode.
• Behaviour when checksum-mode is set to auto: If a 12-character message is passed in, the check character is added. If a 13-character message is passed in, the check character is checked.
• Supplementals are supported (2 and 5 characters). You can add them by appending a "+" along with the supplemental message to the barcode message. Example: 9783468111242+56789

The configuration for the default implementation is:

<barcode>
  <ean-8>
      <height>{length:15mm}</height>
      <module-width>{length:0.33mm}</module-width>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <checksum>{checksum-mode:auto=add|check}</checksum>
      <human-readable>
        <placement>{human-readable-placement:bottom}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
      </human-readable>
  </ean-8>
</barcode>

Message format

• Valid characters are 0-9
• Message length must be 7 or 8 characters depending on the checksum mode.
• Behaviour when checksum-mode is set to auto: If a 7-character message is passed in, the check character is added. If a 8-character message is passed in, the check character is checked.
• Supplementals are supported (2 and 5 characters). You can add them by appending a "+" along with the supplemental message to the barcode message. Example: 22139337+12

The configuration for the default implementation is:

<barcode>
  <postnet>
      <height>{length:15mm}</height>
      <module-width>{length:0.02in}</module-width>
      <quiet-zone enabled="{boolean:true}">{length:10mw}</quiet-zone>
      <checksum>{checksum-mode:auto=ignore}</checksum>
      <interchar-gap-width>{length:0.026in}</interchar-gap-width>
      <tall-bar-height>{length:0.125in}</tall-bar-height>
      <short-bar-height>{length:0.050in}</short-bar-height>
      <baseline-alignment>{baseline-alignment:bottom}</baseline-alignment>
      <human-readable>
        <placement>{human-readable-placement:none}</placement>
        <font-name>{font-name:Helvetica}</font-name>
        <font-size>{length:8pt}</font-size>
        <display-checksum>{boolean:false}</display-checksum>
      </human-readable>
  </postnet>
</barcode>

Message format

• Valid characters are 0-9
• display-checksum controls whether the calculated checksum should be included in the human-readable part.