P4 Software
/
BarcoderX English
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.
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.ean-13, the name of the symbology in the registry.| Member | Meaning |
|---|---|
schemaVersion | Required. A whole number, the version of the format. It is 1 for now. |
minReaderVersion | The 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. |
$schema | Optional. The web address of the format's schema. BarcoderX never fetches it. The writer adds none until the address is final. |
name | Optional. A display name. |
page | Required. The page, described below. |
elements | Required. The list of elements. The first is at the bottom. |
fields, variables, counters, masks, settings | Optional. 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. |
| Member | Meaning |
|---|---|
unit | The unit of every length in the file: in, mm, cm, dot, pt, pica, mil, twip or um. The default is mm. |
width, height | The size of the label, in the unit. |
dpi | Dots per inch, a whole number from 96 to 1,200. The default is 203. |
orientation | 0, 90, 180 or 270 degrees. |
colorMode | mono, gray or color. |
media, layout | The kind of label stock, and the columns and rows of labels on a roll or a sheet. |
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.
| Kind | Main members |
|---|---|
text | content, font (family, asset, size, bold, italic, underline, strikeout), color, background, box, align, valign, lineSpacing, charSpacing, sizing. See Text on a label. |
barcode | symbology, 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. |
line | x2, y2, stroke, color |
box | stroke, color, fill, radius |
ellipse | stroke, 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.
#RRGGBB or #RRGGBBAA, in upper or lower case.align are words in quotation marks, never numbers.null value for an optional member means that the member is absent.asset is an identifier in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.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:
NaN (BX1106, BX1108, BX1109, BX1103);\ud800 (BX1107);type, with a type that is not a word, that is not first or that is not a known kind (BX1111 to BX1114);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 it is | What happens |
|---|---|
| A member that the format does not define, anywhere except inside a content object | It 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 known | It is an error (BX1113). |
| A file that needs a newer reader | A 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).
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:
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.unit, dpi, width and height are always written, because they decide what every number in the file means.<, >, & 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.\n) at the end of each line and one line feed at the very end.$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.
BarcoderX checks every limit before it uses the memory that the limit protects.
| Limit | Value |
|---|---|
| Size of a template file | 2 MB. The program that hosts BarcoderX may raise it, never above 10 MB. |
| Nesting | 64 levels. This is fixed. |
| A text | 1,000,000 characters |
| A member name | 128 characters |
| A number | 1,024 characters |
| Elements in one template | 2,000 |
| Fields, variables, counters or masks, each list | 1,000 |
| Computed properties on one element | 64 |
| Options of one barcode | 64 |
Extension data on the template, the page or one element, all x- members together | 4 KB |
| Longest side of a label | 1,000 mm |
| Findings listed in one result | 200. 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.
These points matter when your program takes templates from other people or shows what BarcoderX reports.
<, >, & 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.<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.BarcoderX is a product of P4 Software.
Was this page helpful?