GS1 标签数据转换（TDT 2.3）工作台

The GS1 TDS / TDT 2.3 Translator is a high-throughput, client-side bidirectional conversion and validation engine for GS1 identification keys. It bridges the gap between physical carrier representations (RFID bitstreams, barcode strings) and digital network identifiers (URIs and web resolvers).

GS1 规范性标准 Implemented

The application follows a strict zero-build, client-side Progressive Web App architecture. It is built to drop directly onto standard Apache 2.x webservers without requiring Node.js, npm scripts, bundlers (Webpack, Vite), or compiler toolchains.

项目仓库目录结构

Standard file and folder layout of the GS1 TDS / TDT 2.3 Translator application repository:

TDT_2_3/
├── index.html                 # Production PWA Single-Page Application (HTML5 user interface)
├── developer_guide.html       # Self-contained Developer Architecture & Handover Guide
├── TDTtranslator.js           # Core TDT 2.3 Translation Engine class (ES6 class, ~3,500 lines)
├── batch_translate.js         # Standalone headless batch translation runner & automation script
├── createApp.js               # Vue 3 Options API application instance and state orchestrator
├── style.css                  # Production Vanilla CSS styles (GS1 design system, zero frameworks)
├── vue.global.js              # Vue 3.3.4 Global Build (zero-build reactive runtime)
├── jszip.js                   # JSZip v3.10.1 client-side unarchiving library
├── jszip-utils.js             # JSZip AJAX / ArrayBuffer bridge loader
├── sw.js                      # Service Worker script (PWA offline caching, cache version v1.0.7)
├── manifest.webmanifest       # PWA Application Manifest metadata
├── icon-192.png, icon-512.png # High-resolution PWA home screen application icons
├── gcpprefixformatlist.json   # Optional GS1 Company Prefix format allocation list (~14 MB)
├── fonts/                     # Local offline WOFF2 web fonts (Inter, Fira Code)
│   ├── inter.woff2            # Inter UI typeface (weights 300..800)
│   └── firacode.woff2         # Fira Code monospace typeface with coding ligatures (weights 400..700)
├── minimal_version_for_resolvers/ # Standalone lightweight resolver deployment example
│   ├── index.html             # Minimal resolver web UI for decompressing /eh and /ex Digital Links
│   ├── createApp.js           # Compact Vue 3 controller (<90 lines) invoking TDTtranslator
│   ├── style.css              # Streamlined dark-themed resolver stylesheet
│   ├── test_minimal.html      # Automated browser verification test harness
│   ├── TDTtranslator.js       # Core translation engine runtime copy
│   └── schemas/               # Normative scheme definitions and lookup tables
├── schemas/                   # Normative declarative scheme definitions (47 EPC schemes) and lookup tables
│   ├── TDT_TableA.json        # 7-bit subdomain and TLD optimization dictionary (TDS §14.5.16)
│   ├── TDT_TableB1.json–B4.json# 14-bit extended domain partition tables (TDS §14.5.16)
│   ├── TDT_TableB.json         # Consolidated Table B offline reference dictionary
│   ├── TDT_TableE.json        # Prefix list & GCP partition lookup table (TDS §14.5.15)
│   ├── TDT_TableF.json        # AI compaction rules and bitlength dictionary (TDS §14.5.2–14)
│   ├── SGTIN++.json           # Extensible SGTIN schema definition with domain compaction
│   └── ...                    # 46 other scheme definition files (47 EPC schemes total: SGTIN-96, GRAI-96, GIAI-96, SSCC-96, etc.)
└── tests/                     # Headless node verification and test harness scripts

权威 TDS 数据表与参考数据集

The engine relies on 9 normative JSON table artifacts located under the schemas/ directory. These artifacts provide lookup dictionaries, AI syntax rules, and compaction codes:

数据表快速查看与字典查询

Inspect and search the loaded normative schema tables directly from memory without inspecting raw JSON files:

代码库集成示例与架构片段

Drop-in code patterns for integrating TDTtranslator.js across different runtime environments:

{{ recipeCodeBrowser }}

{{ recipeCodeWorker }}

{{ recipeCodeNode }}

无界面工具架构与批量转换

Developers building high-throughput batch conversion pipelines, microservices, or CLI tools can run TDTtranslator.js headlessly without the Vue.js user interface. The engine is an autonomous ES6 class with zero dependency on DOM APIs, Vue runtime, or CSS stylesheets. It executes natively in Node.js (v16+), AWS Lambda, worker threads, and headless container environments.

Headless Engine Lifecycle & Batch Processing Rules

• Single Instance Initialization: Instantiate new TDTtranslator() once at service startup and await translator.initialized, then invoke translator.processData(). Never instantiate the translator inside a per-item loop because parsing 56 JSON schemas consumes CPU cycles and memory. Reusing a single instance processes items in 5–10 milliseconds each.
• Compaction Options: When translating into binary or hex representations under multi-AI schemes (e.g. SGTIN++, SSCC++), TDS §14.5.16 compaction requires filter (e.g. 0) and uriStem (e.g. 'https://id.gs1.org') or hostname.
• Per-Item Error Boundaries: Wrap individual translation calls in try...catch blocks. Different EPC schemes support different syntax levels (for example, multi-AI schemes do not support PURE_IDENTITY Tag URIs). Catching errors per level ensures that a single unsupported level does not halt the batch.

Production-Ready Batch Translation Script

Save the following script as batch_translate.js alongside TDTtranslator.js and the schemas/ directory:

{{ batchTranslateCode }}

$ node batch_translate.js
Initializing headless TDT 2.3 engine...
Engine ready in 82ms. Active schemes: 47

Batch translation complete: 5 items in 33ms (6.60ms/item)
[
  { "id": "item-01", "scheme": "SGTIN-96", "HEX": "3014257BF46DB64000000190", "DL": "https://id.gs1.org/01/10614141123459/21/400" },
  { "id": "item-02", "scheme": "SGTIN++", "HEX": "FD0095212341234538566CB0AFC515067E6C6E0", "DL": "https://id.gs1.org/01/09521234123453/21/32a%2Fb" },
  { "id": "item-03", "scheme": "SGTIN-96", "HEX": "3074257BF4003E0000000190", "DL": "https://id.gs1.org/01/00614141002481/21/400" },
  { "id": "item-04", "scheme": "SSCC-96",  "HEX": "3114257BF4499602D2000000", "DL": "https://id.gs1.org/00/106141412345678908" },
  { "id": "item-05", "scheme": "SSCC++",  "HEX": "EF01061414123456789088A833F36370", "DL": "https://id.gs1.org/00/106141412345678908" }
]

Embedding TDTtranslator.js in Custom Web Applications (Re-Skinning Guide)

Developers wishing to create custom front-end user interfaces or re-skin the tool (using React, Angular, Svelte, Lit, or plain handwritten Vanilla HTML/JS) can reuse TDTtranslator.js directly. The engine is entirely decoupled from the presentation layer:

• Zero Framework Dependency: TDTtranslator.js does not require Vue.js, jQuery, or any third-party UI framework. In standard browser environments, loading <script src="TDTtranslator.js"></script> attaches the constructor directly to window.TDTtranslator.
• Zero Zip Libraries Needed when Serving Unzipped Schemas: When deploying the schemas/ directory as unzipped static JSON files on your web server (Apache, Nginx, CDN, or local server), the engine natively uses the browser's standard fetch() API. You do not need to include jszip.js or jszip-utils.js in your application bundle.
• Managing the Asynchronous Lifecycle (async / await): Because TDTtranslator downloads manifest.json and all 56 schema files asynchronously over HTTP, developers must coordinate the engine lifecycle with their UI state:
  1. Instantiate the engine: const translator = new TDTtranslator();
  2. Wait for all schemas to download: await translator.initialized;
  3. Compile in-memory routing and optimization structures: translator.processData();
  4. Enable user interface controls and start accepting inputs.
  Always maintain a UI state indicator (e.g. LOADING → READY or ERROR) and disable translation inputs until initialized resolves to prevent race conditions.

{{ customWebSnippet }}

高吞吐量 Web Worker 批量处理（界面保持响应）

While translating an individual barcode or EPC Tag URI on the browser's main thread takes approximately 5 milliseconds, batch processing hundreds or thousands of tags in a synchronous loop blocks the JavaScript event loop. This causes DOM freezes, halts CSS animations, and triggers browser "Page Unresponsive" warnings.

To maintain a fluid 60 FPS user experience during high-volume batch translation, offload the workload to a dedicated Web Worker thread:

• Dedicated Background Thread: Web Workers run on a separate OS thread, completely isolated from DOM rendering.
• Real-Time Progress Streaming: Rather than waiting for the entire batch to finish, the worker streams incremental PROGRESS events (e.g. { processed, total, percent }) back to the main UI thread to animate a progress bar smoothly.
• Fault-Tolerant Queue Processing: Per-item try/catch boundaries ensure that individual malformed identifiers are recorded as errors while the remaining queue continues uninterrupted.

{{ webWorkerSnippet }}

{{ mainWorkerSnippet }}

The translation engine auto-detects and converts across 8 structural syntax levels. Every supported format is strictly mapped through declarative grammar expressions and option keys:

规范测试向量矩阵

Reference test vectors validating cross-level translations across major GS1 EPC scheme families. Click the button below to copy the full suite of fixtures as a structured JSON test matrix:

EPC Scheme Directory & Bit Capacity Matrix

Reference catalog of all 47 GS1 Electronic Product Code (EPC) schemes supported by the translation engine:

EPC Partition Table & Floating Bit Boundary Explorer

In legacy 96-bit EPC schemes (such as SGTIN-96, SSCC-96, GRAI-96, GIAI-96, SGLN-96), TDS allocates a strictly fixed total bit budget for identification (e.g. 44 bits for SGTIN-96; 58 bits for SSCC-96). A 3-bit partition value (P ∈ 0..6) dynamically shifts the internal boundary between the GS1 Company Prefix (M bits) and the Item Reference or Serial Reference (N bits).

The system pipeline decouples the data models from translation mechanics. The lifecycle operates through four discrete stages:

[Input String] 
     │
     ▼
1. Auto-Detection ───► Regex pattern matching against all registered TDS scheme profiles
     │
     ▼
2. Token Extraction ─► Slices fields, runs URLDECODE, maps AI keys (01, 21, etc.)
     │
     ▼
3. Normalization ────► Identifies GCP length via gcpprefixformatlist.json (or override)
     │
     ▼
4. Compaction Codec ─► Evaluates Table F rules; optimizes custom hostname (§14.5.16)
     │
     ▼
5. Grammar Assembly ─► Concatenates literal header, filter, encoded AIs, and binary hostname
     │
     ▼
[Output Representations] (Binary, Hex, Digital Link, Tag URN, Pure URN, Bare KV)

Regex Constants & Character Set Deconstruction

The translation engine relies on static regular expressions defined on the TDTtranslator class to validate data inputs and route tokens through syntax parsers:

Interactive Regex Pattern Sandbox

Test arbitrary character strings against core GS1 TDS 2.3 validation and grammar regular expressions in real time. Inspect match status, capture groups, and invalid character positions:

方案初始化 & Unzipped Directory Loading

To ensure standard agility, all 9 Table definitions (TDT_TableA.json, TDT_TableB1-B4.json, TDT_TableF.json, etc.) and 46 scheme configurations reside unzipped under ./schemas/.

The private method #fetchDirectoryData(baseDir) loads manifest.json via HTTP fetch() in browsers, and maps each entry into memory cache arrays. If run in a Node.js test environment, it transparently falls back to fs.readFileSync.

GS1 Digital Link URI Parsing & Positional Grammar Deconstructor

GS1 Digital Link URIs encode identification keys, key qualifiers, and data attributes in web URIs. The translation engine executes digitalLinkPreFormat() and digitalLinkPostFormat() to decompose URIs into canonical components, normalize unordered query strings into standard positional sequence, decode URL-escaped entities (e.g. %2F → /), and format outputs across multiple GS1 syntaxes:

{{ dlParsedResult.jsonString }}

When converting a GS1 Digital Link with a custom domain (e.g. https://id.abcde.com/01/...) to an EPC binary string (such as SGTIN++), TDS 2.3 Section 14.5.16 defines two lossless compaction strategies:

• Strategy 0 (URN Code 40): Compresses 3 characters into a 16-bit word (approx. 5.33 bits/char). Indicator bit = 0. Only supports uppercase letters, digits, dot, hyphen, colon.
• Strategy 1 (7-bit ASCII with Optimizations): Compresses subdomains and TLDs using pre-cached dictionary tables (Table A = 7 bits; Tables B1–B4 = 14 bits), falling back to raw 7-bit ASCII for unoptimized characters. Indicator bit = 1.

Interactive Hostname Compaction Strategy Comparator (TDS §14.5.16)

TDS 2.3 Section 14.5.16 evaluates two competing strategies in parallel to minimize tag bit occupancy for custom domains. Test any domain name to inspect intermediate tokenization and compare strategy outcomes in real time:

Test custom domain inputs and explore the live bitstream partitioning produced by the in-browser TDTtranslator engine:

Granular API documentation for all public and private methods across TDTtranslator.js and createApp.js:

{{ method.snippet }}

The reactive controller (createApp.js) manages application state through the Vue 3 Options API:

主要状态属性 (data())

Computed Reactive Pipeline

• detectedData: Invokes myTDTencoder.autodetect(inputString) and returns matching candidate schemes and source level.
• structuredSchemes: Iterates through each supported candidate scheme, invokes translate() across all target levels, builds color-coded HTML bit spans (span.binary0 .. span.binary9), and computes nibble and word boundary paddings.

响应式状态流程

Data flow cascade through the Vue 3 Options API reactive pipeline upon user interaction:

User Input Event (#inputString input change or .btn-demo click)
  │
  ▼
State Mutation: this.inputString updated
  │
  ▼
Computed Property: detectedData
  ├── Invokes TDTtranslator.autodetect(this.inputString)
  └── Returns matching candidate schemes, detected source level, and grammar options
  │
  ▼
Computed Property: structuredSchemes
  ├── Iterates through detected candidate schemes (e.g. SGTIN++, SGTIN-96)
  ├── Resolves GCP length (auto-detected via TDT_TableE.json or overridden by #gcpOverride)
  ├── Executes TDTtranslator.translate(...) for each target syntax level
  ├── Computes color-coded bit partition segments (span.binary0 .. span.binary9)
  └── Pre-computes formatted HEX, GS1 Digital Link, and Tag URI output representations
  │
  ▼
DOM Render Cascade (v-for="scheme in structuredSchemes")
  ├── Updates scheme card headers, total bit counts, and source badges
  ├── Renders color-coded bitstream block visualizer
  └── Renders output representation table with 1-click clipboard copy triggers

DOM 元素与指令映射

Mapping between user interface DOM elements, Vue 3 template directives, and underlying reactive handlers:

Concrete instructions for future developers maintaining this codebase:

交互式 Table F 压缩计算器

Test how GS1 Application Identifiers compact into binary sequences under TDS Section 14.5. Select a preset or input custom values to inspect bit lengths and mathematical formulas:

Table F 压缩算法矩阵 (TDS §14.5.2 – §14.5.14)

The GS1 Tag Data Standard defines specialized encoding algorithms to pack Application Identifier values into high-density bitstreams:

Interactive Luhn Modulo-10 Check Digit Calculator

GS1 identification keys (GTIN-8, GTIN-12, GTIN-13, GTIN-14, and SSCC-18) employ the standard Modulo-10 check digit algorithm defined in GS1 General Specifications Section 7.9. Calculate check digits for raw data payloads or validate existing full identifiers:

Common Pitfalls, Error Diagnostics & Troubleshooting

Reference diagnostics and resolutions for frequent runtime errors encountered during TDT development and deployment:

TDS Scheme Definition File Anatomy (e.g. schemas/SGTIN++.json)

Every declarative scheme file in schemas/ defines the bidirectional mapping across representation levels through five core structural pillars:

{
  "level": [ ... ],   // 1. Structural levels supported (BINARY, GS1_DIGITAL_LINK, TAG_ENCODING, etc.)
  "option": [ ... ],  // 2. Encoding options per level (patterns, filter options, bitlengths)
  "field": [ ... ],   // 3. Field components (header, filter, companyPrefix, itemReference, serial, hostname)
  "grammar": [ ... ], // 4. Assembly sequences concatenating fields and literals for target outputs
  "rule": [ ... ]     // 5. Normalization, URL decoding, check digit, and Table F compaction rules
}

1. Adding a New GS1 Application Identifier (AI)

1. Open schemas/TDT_TableF.json.
2. Add a new JSON record for the Application Identifier with its assigned compaction method:

   {
     "a": "8020",
     "b": "Variable-length alphanumeric",
     "c": "14.5.6",
     "f": "3",
     "g": "5",
     "h": "25"
   }

3. If the new AI requires a new encoding algorithm, add the encoder and decoder methods to TDTtranslator.js and map them in get tds2encodingMethods().

2. Updating Hostname Optimization Tables (Table A / Table B)

1. When GS1 updates subdomains or TLDs in the Tag Data Standard, replace schemas/TDT_TableA.json or schemas/TDT_TableB1.json through B4.json with the new authoritative exports.
2. Do not hardcode entries inside JavaScript. TDTtranslator.js will dynamically ingest the updated JSON tables upon page reload.

3. Adding a New EPC TDS Scheme

1. Drop the new scheme definition file (e.g. NEWKEY++.json) into schemas/.
2. Register the file inside schemas/manifest.json under definitionFiles.

4. Running Local Verification Tests

Run automated end-to-end test suites locally without build tools:

# Start a local static HTTP server
python3 -m http.server 8000

# Run headless verification test runner
node test_minimal_suite.js

# Or open test runners directly in your browser:
# http://localhost:8000/test.html
# http://localhost:8000/minimal_version_for_resolvers/test_minimal.html