TagDataTranslation 3.0.6

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

NuGet (.NET and .NET MAUI)

dotnet add package TagDataTranslation

Or via Package Manager:

Install-Package TagDataTranslation

The NuGet package includes targets for .NET 8.0/9.0/10.0, Android, iOS, and macCatalyst. .NET MAUI projects will automatically resolve the correct platform target.

From Source

git clone https://github.com/dannyhaak/TagDataTranslation.git
cd TagDataTranslation
dotnet build src/TagDataTranslation/TagDataTranslation.csproj

Requirements

• .NET 8.0 or later (supports .NET 8.0, 9.0, and 10.0)
• For mobile targets: .NET MAUI workload (dotnet workload install maui)

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 parameterList = "tagLength=96";
string legacy = engine.Translate(binary, parameterList, "LEGACY");
// legacy = "gtin=00037000302414;serial=10419703"

Get All Representations

var engine = new TDTEngine();
var result = engine.TranslateDetails("30340242201d8840009efdf7", "tagLength=96", "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.

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)

Building

dotnet build src/TagDataTranslation/TagDataTranslation.csproj
dotnet test test/TagDataTranslation.Tests/TagDataTranslation.Tests.csproj

Creating a NuGet Package

dotnet pack src/TagDataTranslation/TagDataTranslation.csproj -c Release -o ./artifacts

To publish to NuGet.org:

dotnet nuget push ./artifacts/TagDataTranslation.*.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json

Version History

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