Parsing and validating GS1 barcodes with AI-spec-driven rules, smart normalization of symbology/separators, strict/lenient modes, auto-generated up-to-date AI catalog, detailed results and errors.
gs1-parser is a modern Kotlin Multiplatform (KMP) library designed for parsing and validating GS1 barcodes (GS1-128, GS1 DataMatrix, GS1 QR Code). It uses an Application Identifier (AI) catalog generated directly from the official GS1 specifications.
Add the dependency to your build.gradle.kts file:
kotlin {
sourceSets {
val commonMain by getting {
dependencies {
implementation("fr.valyra:gs1-parser:1.0.1")
}
}
}
}
The Gs1 object provides a simplified entry point for parsing a raw string from a scanner.
import fr.valyra.gs1.Gs1
import fr.valyra.gs1.ParseMode
val rawInput = "01034123456789081521123110ABC123"
val result = Gs1.parse(rawInput, ParseMode.LENIENT)
if (result.isGs1) {
gtin = result.()?.value
expiry = result.()?.value
batch = result.()?.value
println()
}
Gs1ParseResult)The parsing result provides detailed information:
fields: A list of Gs1Field containing the AI, its raw value, formatted value, and full specification.errors: Fatal errors that prevented full parsing (unknown AI, invalid format, incorrect check digit).warnings: Non-blocking warnings (e.g., missing separator in LENIENT mode).val result = Gs1.parse("0104046241110150", ParseMode.STRICT)
if (result.hasErrors) {
result.errors.forEach { error ->
// e.g., "CHECK_DIGIT" -> "Invalid check digit for AI 01"
println("Error [${error.code}]: ${error.message}")
}
}
GS1 barcodes use a special character called FNC1 to delimit variable-length fields. In data transmitted by a scanner, this character is often represented by:
\u001D).]C1 at the beginning of the barcode).| or \u00E8 depending on hardware configuration.gs1-parser natively handles these cases by normalizing the input before parsing. It removes symbology identifiers and converts common separators into the standard \u001D character.
Each extracted field (Gs1Field) provides access to its official definition:
| Property |
|---|
Unlike other libraries, gs1-parser does not use a static list. A Gradle task (GenerateGs1CatalogTask) downloads the latest definitions from ref.gs1.org. This ensures your project remains compliant even when GS1 adds new Application Identifiers.
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.
Developed by Cyril Ponce.
ref.gs1.org).]C1, ]d2) and various group separators (GS).STRICT mode (rejects minor formatting issues) or LENIENT mode (attempts to recover data despite formatting errors).remainder: The part of the string that could not be parsed.| Description |
|---|
ai | The Application Identifier (e.g., "01", "10", "17") |
value | The extracted data without the AI |
spec | AiSpec object containing the title, description, and validation rules |
formatted | (Optional) Formatted version of the data |
Surfaced from shared tags and platforms — no rankings paid for.