Skip to content
P4 Software P4 Software / BarcoderX English

Add these docs to Claude

Ask Claude questions about these docs. Claude reads the published pages and links you back to them. Copy this address:

https://p4-software.opendocs.page/mcp

In claude.ai or Claude Desktop: open Settings, then Connectors, choose Add custom connector and paste the address.

In Claude Code, run:

claude mcp add --transport http docs https://p4-software.opendocs.page/mcp

The label template format

The label template format

Applies to: BarcoderX Basic and Ultimate

Status: Built, not yet released. The code that reads and writes a template in JSON exists and is tested. It is a library inside the engine that is still being built. There is no released package, there is no public interface that you can call to read or write a template directly, and the licensed engine will be the only public way to produce output. This page describes the format and what the reader and the writer do. Names of members are working names until the format is published. Anything marked "planned" is not usable yet.

A template is a text file that describes one label. This page shows what a template looks like, what happens when BarcoderX reads one and writes one, the limits, and what a program that hosts BarcoderX must do to stay safe. For the ideas behind templates, see Templates and data.

The smallest template

This template has one text, one box and one EAN-13 barcode. It is real: the reader accepts it, and a test reads it.

{
  "schemaVersion": 1,
  "page": { "unit": "mm", "width": 100, "height": 50, "dpi": 203 },
  "elements": [
    { "type": "text", "id": "title", "x": 4, "y": 4, "width": 60, "height": 10,
      "content": { "text": "Hello" }, "font": { "size": 14, "bold": true } },
    { "type": "box", "id": "frame", "x": 2, "y": 2, "width": 96, "height": 46, "stroke": 0.4 },
    { "type": "barcode", "id": "code", "symbology": "ean-13", "x": 4, "y": 20, "width": 60, "height": 20,
      "content": { "text": "9501101531000" } }
  ]
}

What it says:

  • schemaVersion is the version of the format. It is 1 for now.
  • page gives the unit (millimeters here), the width and the height of the label in that unit, and the resolution in dots per inch. unit and dpi can be left out. They then mean millimeters and 203.
  • elements is the list of things on the label, from the bottom one to the top one. Each has a type and an id.
  • The text has fixed content, "Hello", in a bold 14-point font. The box has a border 0.4 mm wide. The barcode has the symbology ean-13, the name of the symbology in the registry.
  • The barcode number, 9501101531000, is the EAN-13 printed in Figure 5-11, on page 326, of the GS1 General Specifications, release 26.0. Its last digit, 0, is its check digit.

The parts of a template

The top of the file

MemberMeaning
schemaVersionRequired. A whole number, the version of the format. It is 1 for now.
minReaderVersionThe oldest version of the format that a reader needs in order to read this file. If it is missing, it is the same as schemaVersion.
$schemaOptional. The web address of the format's schema. BarcoderX never fetches it. The writer adds none until the address is final.
nameOptional. A display name.
pageRequired. The page, described below.
elementsRequired. The list of elements. The first is at the bottom.
fields, variables, counters, masks, settingsOptional. The fields, variables, counters and masks that the label uses, and its settings. They are read and checked. Using them to build a label is planned.

The page

MemberMeaning
unitThe unit of every length in the file: in, mm, cm, dot, pt, pica, mil, twip or um. The default is mm.
width, heightThe size of the label, in the unit.
dpiDots per inch, a whole number from 96 to 1,200. The default is 203.
orientation0, 90, 180 or 270 degrees.
colorModemono, gray or color.
media, layoutThe kind of label stock, and the columns and rows of labels on a roll or a sheet.

The elements

Five kinds of element can be read today: text, barcode, line, box and ellipse. The kinds picture, grid, repeater, RFID and raw command are planned. A template that uses one of them is refused with the code BX1113 until it is supported.

Every element starts with type, then id. The type must be the first member. The id must be different for every element. After them come the position and size (x, y, width, height, in the page unit) and, where the format has them, rotation, name, anchor, printWhen, output, locked, locks, group, printSide, computed and comment.

KindMain members
textcontent, font (family, asset, size, bold, italic, underline, strikeout), color, background, box, align, valign, lineSpacing, charSpacing, sizing. See Text on a label.
barcodesymbology, content, xDimension, xDimensionUnit (page or dot), sizing (fixed or fit), barHeight, barWidthAdjust, quietZone, checkDigit, humanReadable (position: below, above or off), options, color, background. See Barcodes.
linex2, y2, stroke, color
boxstroke, color, fill, radius
ellipsestroke, color, fill

Content. A text or a barcode gets its content from exactly one of text (fixed text), field (a field of your data) or expr (an expression). A barcode may also say how the content becomes bytes, with encoding (text, hex or base64) and escapes (none or tilde). Reading content from a field or an expression to make a label is planned.

How values are written

  • Lengths are plain numbers in the page unit. Font sizes are in points. Angles are in degrees, clockwise.
  • Colors are #RRGGBB or #RRGGBBAA, in upper or lower case.
  • Choices such as align are words in quotation marks, never numbers.
  • A border width or a radius is one number, or a list of four numbers: top, right, bottom and left for sides, and top-left, top-right, bottom-right and bottom-left for corners.
  • A null value for an optional member means that the member is absent.
  • A font asset is an identifier in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Reading a template

BarcoderX reads a template from text, from bytes or from a stream. A template that is not valid is refused with one or more diagnostic codes, and no design is made from it. For a problem in the file, the message also says where: a line and a position. Both start at 1 and count characters, not bytes.

The reader refuses:

  • a file over the size limit, which it detects before it parses anything (BX1100);
  • text that is not UTF-8, and a file that starts with a byte order mark (BX1101, BX1102);
  • JSON that is broken: a missing comma or bracket, a comment, a trailing comma, a file that stops early (BX1103);
  • nesting that is too deep (BX1104);
  • a member written twice in the same object, also inside options and extension data (BX1105);
  • a name or a text that is too long, and a number that is too large or is written as NaN (BX1106, BX1108, BX1109, BX1103);
  • a half of a character code, such as \ud800 (BX1107);
  • an element with no type, with a type that is not a word, that is not first or that is not a known kind (BX1111 to BX1114);
  • a value of the wrong kind, such as text where a number belongs, and a color or an identifier that is not written correctly (BX1115 to BX1124);
  • a content object that has no source, or more than one (BX1125);
  • a template that needs a newer version of BarcoderX (BX1128).

After the file reads, the model rules check the design: ids that are used twice, numbers out of range and the limits below (BX1001 to BX1027). One problem of severity Error means that no design is returned. The full list of codes, with their texts in English and Spanish, is in Diagnostic codes.

What happens to members that BarcoderX does not know

What it isWhat happens
A member that the format does not define, anywhere except inside a content objectIt is kept and written back. A newer file loses nothing when an older tool edits it. A host application can keep its own data in members whose names start with x- and an identifier of the host.
A member that the format does not define, inside a content object (the object with text, field or expr)It is an error (BX1126). A content object holds only its own members.
A choice that is not a known word, such as "align": "left"It is an error (BX1121). It is not ignored.
An element type that is not knownIt is an error (BX1113).
A file that needs a newer readerA file whose minReaderVersion is above the reader's version is refused with BX1128, and nothing is half read. A file that says schemaVersion 2 and minReaderVersion 1 is read as version 1.

An unknown choice is an error because a reader cannot drop it and still make the element mean something. A newer format that adds a choice that changes the output therefore sets minReaderVersion, and an older reader refuses the file with a clear message.

Version 0 and below is not a version (BX1127).

Writing a template and the canonical form

BarcoderX writes a template in one fixed form, called the canonical form. The same design gives exactly the same text on every computer, on Windows x64, Linux x64 and Linux arm64. If you read a canonical file and write it again, you get the same bytes.

The rules of the canonical form:

  • Order. An element starts with type and id. Other members follow in the order of the format. Members that BarcoderX does not know come last, in alphabetical order. The keys of computed, options and every extension object are in alphabetical order.
  • Defaults are left out. A member whose value is its default is not written. The exception is on the page: unit, dpi, width and height are always written, because they decide what every number in the file means.
  • Numbers are written in the shortest form that reads back exactly. The culture of the computer plays no part.
  • Text is UTF-8. There is no byte order mark. The only characters that are escaped are the quotation mark, the backslash, the control characters (U+0000 to U+001F and U+007F to U+009F), U+2028 and U+2029. Every other character is written as it is, including <, >, & and '. The one exception is half of a pair of surrogate codes with no other half, which can occur only in a design built in code: it is written as U+FFFD.
  • Layout. Two spaces of indent, a line feed (\n) at the end of each line and one line feed at the very end.
  • Small choices. Colors are written in upper case and asset identifiers in lower case. Four equal side values are written as one number.
  • Extension values are written compact, on one line.
  • $schema is written only if the design has one. The writer never adds one.

This is the canonical form of the smallest template above, exactly as the writer produces it:

{
  "schemaVersion": 1,
  "page": {
    "unit": "mm",
    "width": 100,
    "height": 50,
    "dpi": 203
  },
  "elements": [
    {
      "type": "text",
      "id": "title",
      "x": 4,
      "y": 4,
      "width": 60,
      "height": 10,
      "content": {
        "text": "Hello"
      },
      "font": {
        "size": 14,
        "bold": true
      }
    },
    {
      "type": "box",
      "id": "frame",
      "x": 2,
      "y": 2,
      "width": 96,
      "height": 46,
      "stroke": 0.4
    },
    {
      "type": "barcode",
      "id": "code",
      "x": 4,
      "y": 20,
      "width": 60,
      "height": 20,
      "symbology": "ean-13",
      "content": {
        "text": "9501101531000"
      }
    }
  ]
}

A design that was read from a template can be written and read back with the same limits. The writer refuses a design whose canonical text would be larger than the size limit (BX1130), and it leaves out an extension value that the reader would refuse. An extension member whose name is also the name of a member that the format defines is left out, so that it cannot hide the real one.

Limits

BarcoderX checks every limit before it uses the memory that the limit protects.

LimitValue
Size of a template file2 MB. The program that hosts BarcoderX may raise it, never above 10 MB.
Nesting64 levels. This is fixed.
A text1,000,000 characters
A member name128 characters
A number1,024 characters
Elements in one template2,000
Fields, variables, counters or masks, each list1,000
Computed properties on one element64
Options of one barcode64
Extension data on the template, the page or one element, all x- members together4 KB
Longest side of a label1,000 mm
Findings listed in one result200. After that, one message (BX1026) says the design was not fully checked.

The values for a member name, a number, the four lists, computed properties, options and findings are first choices that the builders made. They have not been confirmed yet and can change before the first release.

Notes for developers who host BarcoderX

These points matter when your program takes templates from other people or shows what BarcoderX reports.

  1. The canonical text is not escaped for HTML. <, >, & and ' are written as they are. Encode the text for HTML before you put it in a page, and for an attribute before you put it in an attribute in quotation marks. Never put it inside an HTML script block unless every < in it is first written as \u003C. The same holds for the raw text of an extension or option value that the engine keeps.
  2. A message can contain words from the template. The element id, the names of declared fields, variables, counters and masks, and the names of computed properties appear in some diagnostics (codes BX1001 to BX1027), each at most 128 characters. They can contain anything a person can type, including line breaks. Insert them into a page as text, never as markup. This holds for the whole message: the element id and the location that come with it, every value and the finished text. Show ids and names in an isolated direction context (in HTML, a <bdi> element), because characters that reverse the direction of text, such as U+202E, are not changed by HTML encoding. Before you write a message to a log, replace carriage returns, line feeds, other control characters and the direction characters U+061C, U+200E, U+200F, U+202A to U+202E and U+2066 to U+2069, so that one template cannot fake a line of your log. The messages of the reader itself (BX1100 to BX1130) never contain text from the file. The text layout codes can carry a font name that came from a template (see Text on a label), so treat them the same way.
  3. Limit how many templates you read at the same time. Reading uses memory in proportion to the size of the file. In the security review, one read allocated about 100 MB at the 2 MB default, and about half a gigabyte, up to about 0.6 GB, at the 10 MB ceiling. A read can also use up to about half a second of processor time at the default, and a few seconds at the ceiling. Keep the size limit as low as your labels allow, limit the size of the requests that you accept, and cap the number of reads that run at once. The program that calls the reader can cancel a read.
  4. Check that you can save a template when you accept it. The canonical form can be larger than the file it came from, because of its indent, so a template that reads within the size limit can still be too large to write back (BX1130). If your program stores the canonical form, write the template as soon as it is uploaded and refuse it there with BX1130, so that you never accept a template that you cannot store. Write with the same limits as the reader that will read the text back: a value over a stricter limit is left out, and today nothing reports it.

What is planned

  • A published JSON Schema file, so that you can check a template before you load it.
  • XML as an exact equivalent of JSON.
  • Upgrading templates written in older versions of the format.
  • The kinds of element that are not read yet, and using fields, expressions, counters and masks to make labels.

BarcoderX is a product of P4 Software.

Was this page helpful?