transactions.dev by visibility.cloud

The blog  ·  2026-07-31

Naming the document itself — GDTI, Digital Link, and the hash fallback

Written for ED-3 — the in-house supply-chain platform team — the security and architecture reviewer asking what exactly goes in that field.

One thesis: a bizTransaction reference is only as good as the identifier inside it, and CBV 2.0 already specifies a complete naming scheme — GDTI EPC URIs and GS1 Digital Link URIs for documents with GS1 identity, and a hash-URI fallback for documents without one. Your architecture review does not need to design a document-naming convention. It needs to check that the pipeline follows the one the standard wrote.

Why the reference needs identity discipline

Two parties each stamp a purchase order onto their own event streams. If they name the document differently — PO-2026-0007 here, 4500012345 there, a URL somewhere else — the cross-party join that bizTransactionList exists to enable degrades into string matching. Idempotency has the same dependency: the join verb must emit the same reference every time it compiles the same document, or replays create phantom paperwork. Both properties reduce to one rule the pipeline enforces mechanically: one document, one identifier, and every event that cites the document agrees on it.

CBV 2.0 §8.5 — the same section that puts bizTransactionList on every event type — recommends the identifier syntaxes. There are three, and they cover the whole space.

Case one — the document has a GDTI

The Global Document Type Identifier is GS1's identifier for documents. As an EPC URI:

urn:epc:id:gdti:0614141.06012.1234
                ───┬─── ──┬── ──┬─
       GS1 company prefix │     serial (this document)
                document type

The company prefix names the issuer, the document type names the kind of paperwork (this issuer's purchase-order series, say), and the serial names the individual document. This is the form the family's golden corpus exercises — transaction-event-po.json carries exactly "bizTransaction": "urn:epc:id:gdti:0614141.06012.1234" — and it is the strongest case: the identifier is issuer-assigned, globally unambiguous, and resolvable to a party you can hold to it.

Case two — the same GDTI as a GS1 Digital Link URI

CBV 2.0 also sanctions Digital Link URIs for the same identifier. The GDTI travels under Application Identifier 253, as the 13-digit key (company prefix + document type + check digit) followed by the serial:

https://id.gs1.org/253/06141410601221234
                       ──────┬────── ─┬──
                        GDTI-13      serial

The check digit is computable by anyone: weight the twelve digits 061414106012 alternately 1 and 3, sum to 58, and the digit that lifts it to the next multiple of ten is 2. Same document, same issuer, same serial — one syntax for EPC-native systems, one for the web-native systems that resolve identifiers by HTTP. The grammar of Digital Link itself — AIs, keys, qualifiers — is barcoding.dev's layer of the family; what matters at this layer is that both spellings name the same document and the pipeline treats them as the same reference.

Case three — the document has no GS1 identity at all

Most webhook payloads, portal CSVs, and legacy documents have no GDTI and never will. CBV 2.0 §8.6 provides the fallback: a hash-based URI, computed over the document bytes, so the identifier is deterministic rather than assigned. Here is the fallback worked on a real fixture — a synthetic, license-clean 850 from the corpus, 352 bytes:

$ shasum -a 256 po-2026-0007.edi
7dc70e6d265be4136c4130a31b97f7ecc0bdff39cdcd2f93b6c2a995a24faa40

ni:///sha-256;7dc70e6d265be4136c4130a31b97f7ecc0bdff39cdcd2f93b6c2a995a24faa40

Any party holding the same bytes computes the same identifier — no registry, no coordination, no issuer. That property is what makes the fallback safe for the reviewer to approve: the identity claim is re-derivable from the artifact itself, which is the same posture the family already takes with event identity (CBV §8.9 event hashes, the hash verb on epcis.dev, same ni:///sha-256;… idiom) and with its own vendored artifacts (sha256 pins, changed only by journaled ruling). Identity is computed, never assigned, whenever computing it is possible.

The fallback's honest limitation is also worth stating in the review: byte-identical is the criterion. Two renditions of the "same" purchase order — the PDF and the EDI, or the 4010 and the re-released copy — hash differently, because they are different artifacts. When a partner sends the same commercial document in two forms, the ruling about which artifact anchors the reference is recorded, not improvised; that is the same journaled-ruling governance the pipeline applies to every mapping choice.

What the pipeline enforces

The rule set the join and enrich verbs apply, in order:

  1. If the source document carries a GDTI, the reference is the GDTI — EPC URI form on the record, Digital Link accepted on input and normalized to one spelling.
  2. If the issuer assigned no GS1 identity, the reference is the §8.6 hash URI over the canonical document bytes.
  3. One document, one identifier: recompiling the same bytes emits the same reference, and an event set in which two spellings of one document diverge is a typed error, not a warning.

Every emitted event then validates against the pinned official EPCIS 2.0 schema — the identifiers above are not a house convention riding on the standard, they are the standard's own syntax, which is why the emitted record stays a conformant superset rather than a dialect: conformant always, superset only where the source document genuinely carries more.

The questionnaire line, pre-answered

When the security review asks "what exactly goes in the bizTransaction field, and who controls it" — the answer is one sentence: a CBV 2.0 §8.5 identifier — an issuer-assigned GDTI in EPC URI or Digital Link form, or, for documents without GS1 identity, the §8.6 hash URI computed over the document bytes — enforced one-identifier-per-document at compile time. Nothing in that sentence is ours to define, which is precisely what makes it approvable.

If your document population is mostly case three — no GDTIs anywhere, a decade of ERP exports — that is a normal answer, not a disqualifying one. Say so in the access flow; the identifier questions in the survey exist because the answer changes what the compile does first.

966 words. The access flow is at /get-access/; the family's event door is epcis.dev.

get access All posts →