GS1 data¶
Every barcode starts from a Gs1Message: a list of element strings, each an
Application Identifier (AI) and its value. (01) is the GTIN, (10) the batch or lot, (17) the expiry
date, and so on.
A Gs1Message is always valid: building one checks every value, so an encoder never receives bad data.
Building a message¶
There are three ways, and they give the same result.
The builder knows the common AIs: gtin, sscc, content, batch, serial, dates (productionDate,
bestBeforeDate, expiryDate…), counts, weights and dimensions, price, amountPayable, orderNumber, GLNs
and originCountry. For anything else use add(ai, value):
Gs1Message.build {
gtin("4006381333931") // GTIN-13: padded to 14 digits for you
add(Gs1Ai.companyInternal(1), "BIN-42") // (91)BIN-42
}
AI constants¶
Gs1Ai has a constant for every AI, named after its meaning. AIs whose last digit is a parameter (decimal
places, a sequence number) are functions:
Gs1Ai.GTIN // "01"
Gs1Ai.BATCH_LOT // "10"
Gs1Ai.EXPIRY_DATE // "17"
Gs1Ai.netWeightKg(3) // "3103": net weight in kg with 3 decimals
Gs1Ai.companyInternal(1) // "91"
To look up an AI's format and title, use ApplicationIdentifier:
val ai = ApplicationIdentifier.find("17")!!
ai.title // "USE BY or EXPIRY"
ai.isPredefinedLength // true
ApplicationIdentifier.all // every AI
Validation¶
Building a message throws Gs1Exception with a Gs1Error that says what failed and where:
try {
Gs1Message.parse("(01)09501101020910")
} catch (e: Gs1Exception) {
e.error.code // Gs1ErrorCode.INCORRECT_CHECK_DIGIT
e.error.ai // "01"
e.error.position // 13: offset of the wrong digit within the value
e.message // AI (01): incorrect check digit at "0" (position 13)
}
Values are checked against the GS1 Barcode Syntax Dictionary and the GS1 Barcode Syntax Tests: lengths,
character sets, check digits, dates and times, ISO country and currency codes, IBANs and more. To check a single
value without building a message, call ApplicationIdentifier.validate(value), which returns the error or
null.
Not checked yet: GS1 Company Prefix positions, coupon formats (AIs 8110 and 8112) and the rules about which AIs must or must not appear together.
Check digits¶
Gs1CheckDigit.compute("950110102091") // 7
Gs1CheckDigit.append("0950110102091") // "09501101020917"
Gs1CheckDigit.isValid("09501101020917") // true
Element order¶
By default, of, parse and build put the predefined-length AIs (GTIN, dates…) first. Those need no
separator after them, so the symbol is smaller. Pass Gs1Order.AS_GIVEN to keep your order:
Gs1Message.parse("(10)ABC123(01)09501101020917").humanReadable
// (01)09501101020917(10)ABC123
Gs1Message.parse("(10)ABC123(01)09501101020917", Gs1Order.AS_GIVEN).humanReadable
// (10)ABC123(01)09501101020917
Reading scanned data¶
Barcode readers return GS1 data as an element string: a symbology identifier such as ]d2 (DataMatrix),
]C1 (GS1-128) or ]Q3 (QR Code with FNC1), the AIs and values, and the ASCII group separator (GS, character
29) after variable-length values. Parse it back into a message:
val scanned = Gs1Message.parseElementString("]d2010950110102091717261231" + "10ABC123")
scanned[Gs1Ai.BATCH_LOT] // "ABC123"
scanned.humanReadable // (01)09501101020917(17)261231(10)ABC123
A GS1 Digital Link QR Code gives a URI instead; see parsing Digital Link URIs.
The reverse, message.toElementString(), produces the same string a reader would return, which is useful in
tests.