TagDataTranslation 4.0.0

TagDataTranslation

Encode and decode GS1 EPC identifiers for RAIN (UHF) RFID tags. Convert between GTIN, SSCC, SGLN, and 50+ other formats — from barcode to EPC hex and back.

Implements the GS1 EPC Tag Data Standard (TDS) 2.3 and Tag Data Translation (TDT) 2.2 specifications. Used in production for RFID tag programming, inventory systems, and supply chain applications.

Try it online: https://www.mimasu.nl/tag-data-translation/try-online

Why This Library

• Spec-complete: All 50 EPC schemes including TDS 2.3 '+' and '++' variants with Digital Link URIs
• Deterministic: Every encode/decode is provably correct against the GS1 specification — no approximations, no guessing
• Fast: SGTIN-96 encode in 7.8 us, decode in 7.7 us (benchmarked on Apple M1 Pro)
• Cross-platform: .NET, JavaScript/TypeScript (WASM), Python, Swift, Kotlin, Flutter
• Production-ready: Exception-free TryTranslate API for high-throughput tag programming and reading

Features

• GTIN to EPC encoding (SGTIN-96, SGTIN-198) and decoding
• SSCC, SGLN, GRAI, GIAI, GSRN, GDTI, SGCN, ITIP, GID, CPI, ADI, USDOD encoding
• GS1 Digital Link URI generation and parsing
• '++' schemes with custom hostname encoding for branded Digital Link URIs
• GS1 Company Prefix lookup
• Filter Value tables
• Hex to binary and binary to hex conversion

Platform Support

Supported Schemes

'++' schemes (TDS 2.3) support lossless encoding of custom hostnames in EPC binary, enabling round-trip translation with branded Digital Link URIs like https://coca-cola.com/01/... instead of https://id.gs1.org/01/....

Installation

# .NET
dotnet add package TagDataTranslation

# JavaScript / TypeScript
npm install @mimasu/tdt

# Python
pip install tag-data-translation

# Swift (Package.swift)
.package(url: "https://github.com/dannyhaak/TagDataTranslation.git", from: "3.0.0")

# Flutter
flutter pub add tag_data_translation

The .NET package includes targets for .NET 8.0/9.0/10.0, Android, iOS, and macCatalyst. The npm package uses WebAssembly and works in Node.js and browsers.

Quick Start

Encode GTIN to Hex

using TagDataTranslation;

var engine = new TDTEngine();
string epcIdentifier = "gtin=00037000302414;serial=10419703";
string parameterList = "filter=3;gs1companyprefixlength=7;tagLength=96";
string binary = engine.Translate(epcIdentifier, parameterList, "BINARY");
string hex = engine.BinaryToHex(binary);
// hex = "30340242201d8840009efdf7"

Decode Hex to GTIN

var engine = new TDTEngine();
string binary = engine.HexToBinary("30340242201d8840009efdf7");
string bareId = engine.Translate(binary, "", "BARE_IDENTIFIER");
// bareId = "gtin=00037000302414;serial=10419703"

Get All Representations

var engine = new TDTEngine();
var result = engine.TranslateDetails("30340242201d8840009efdf7", "", "TAG_ENCODING");

Console.WriteLine($"Pure Identity: {result.Fields["pureIdentityURI"]}");
Console.WriteLine($"Tag URI: {result.Fields["tagURI"]}");
Console.WriteLine($"GTIN: {result.Fields["gtin"]}");
Console.WriteLine($"Serial: {result.Fields["serial"]}");

Digital Link Generation

using TagDataTranslation.DigitalLink;

var components = new DigitalLinkComponents
{
    Domain = "id.gs1.org",
    PrimaryKey = ("01", "00037000302414"),  // AI 01 = GTIN
    KeyQualifiers = new List<(string, string)>
    {
        ("21", "10419703")  // AI 21 = Serial
    }
};

string digitalLink = DigitalLinkGenerator.Generate(components);
// https://id.gs1.org/01/00037000302414/21/10419703

Digital Link Parsing

if (DigitalLinkParser.TryParse("https://id.gs1.org/01/00037000302414/21/10419703", out var components))
{
    Console.WriteLine($"GTIN: {components.PrimaryKey.Value}");
    // GTIN: 00037000302414
}

GS1 Company Prefix Lookup

var engine = new TDTEngine();
var result = engine.GetPrefixLength("0037000302414");
Console.WriteLine($"Prefix: {result.Prefix}, Length: {result.Length}");
// Prefix: 0037000, Length: 7

Debugging Scheme Loading

var engine = new TDTEngine();
if (engine.LoadErrors.Count > 0)
{
    foreach (var error in engine.LoadErrors)
    {
        Console.WriteLine(error);
    }
}

API Reference

TDTEngine

Translate

public string Translate(string epcIdentifier, string parameterList, string outputFormat)

Translates an EPC identifier from one representation to another.

Returns: The converted EPC as a string.

Parameter Keys

Pass as semicolon-delimited key=value pairs, e.g. "filter=3;gs1companyprefixlength=7;tagLength=96".

When decoding (hex/binary input), no parameters are needed — the engine determines everything from the binary data.

Output Formats

Legacy alias (backward-compatible):

TranslateDetails

public TranslateResult TranslateDetails(string epcIdentifier, string parameterList, string outputFormat)

Same as Translate, but returns a TranslateResult object containing all extracted fields.

TryTranslate (Exception-Free)

public bool TryTranslate(string epcIdentifier, string parameterList, string outputFormat, out string? result, out string? errorCode)

Translates an EPC identifier without throwing exceptions. Ideal for high-throughput scenarios.

if (engine.TryTranslate(epcIdentifier, parameterList, "BINARY", out var result, out var errorCode))
{
    Console.WriteLine($"Success: {result}");
}
else
{
    Console.WriteLine($"Failed: {errorCode}");
}

TryTranslateDetails (Exception-Free)

public bool TryTranslateDetails(string epcIdentifier, string parameterList, string outputFormat, out TranslateResult? result, out string? errorCode)

Same as TryTranslate, but returns a TranslateResult object on success.

GetPrefixLength

public PrefixLengthResult GetPrefixLength(string input)

Looks up the GS1 Company Prefix length for a given identifier.

GetFilterValueTable

public Dictionary<int, string> GetFilterValueTable(string scheme)

Returns the filter value descriptions for a scheme (e.g., "SGTIN" returns {0: "All Others", 1: "POS Item", ...}).

LoadErrors

public IReadOnlyList<string> LoadErrors { get; }

Contains any errors encountered while loading scheme files. Inspect this after construction to debug missing or malformed schemes.

Helper Methods

public string HexToBinary(string hex)      // Convert hex to binary string
public string BinaryToHex(string binary)   // Convert binary string to hex

Exceptions

TDTTranslationException is thrown with one of these codes:

Performance

Benchmarked on Apple M1 Pro, .NET 8.0 (BenchmarkDotNet):

The engine uses compiled regex caching, pre-sorted scheme data, and lookup tables for hex/binary conversion. The TDTEngine constructor loads all schemes once; subsequent Translate() calls benefit from cached patterns and pre-computed data structures.

Run benchmarks yourself:

dotnet run -c Release --project test/TagDataTranslation.Benchmarks

Examples

See the examples/ directory for platform-specific sample projects:

• examples/ConsoleApp/ -- .NET console application
• examples/MauiApp/ -- .NET MAUI cross-platform app (Android, iOS, macCatalyst)
• examples/NodeApp/ -- Node.js application (via WebAssembly)

License

This library is licensed under the Business Source License 1.1 (BSL 1.1).

• Non-production use (development, testing, evaluation) is free
• Production use requires a commercial license -- contact tdt@mimasu.nl
• Each version converts to Apache 2.0 four years after release

See LICENSING.md for full details.

The included JSON and XSD artifacts are (c) GS1 (https://www.gs1.org/standards/epc-rfid/tdt).

Use Cases

• Tag programming: Encode GTINs and SSCCs to EPC hex for writing to RAIN RFID tags
• Tag reading: Decode EPC hex from RFID readers back to human-readable identifiers
• Inventory systems: Translate between barcode and RFID representations
• Supply chain: Convert between GS1 Digital Link URIs and EPC binary
• Label printing: Generate EPC hex for RFID-enabled label printers (Zebra, SATO, etc.)
• Mobile RFID apps: Encode/decode on iOS and Android via native SDKs

Resources

• GS1 TDT Standard
• GS1 Tag Data Standard (TDS)
• GS1 Digital Link
• Online Demo
• RAIN RFID Training Academy