Why connect a source system at all

Almost nothing a digital product passport needs is new information. The product name and its translations, the marketing text, the images, the net weight and the packaging dimensions, the brand, the target market — all of that is already written down, curated and argued over, in a product information system or an ERP. What is missing is not the data but the shape: a GS1 identifier that is also a web address, a vocabulary the rest of the world reads, an access tier per field, and a place on the public web where a scan lands.

A connector does exactly that piece of work and nothing more. It reads a record from the system that owns it, maps it onto GS1 terms, and publishes it into the OpenEPCIS catalog under the product's GS1 Digital Link. The source system stays the place where a human edits a product; the platform becomes the place where that product is identified, published, resolved and observed. Nobody maintains the same fact twice.

One record, two passport forms

The interesting part begins after the data has arrived. The same master data carries two passport forms, and they sit beside each other rather than one above the other.

The first form is the master-data document itself: JSON-LD over the GS1 Web Vocabulary, stored and served by the GS1 Digital Link resolver and addressed by a GS1 Digital Link — /01/<gtin> for the model, /01/<gtin>/10/<lot> for a batch, /01/<gtin>/21/<serial> for a single item. This form carries its own semantics: every term is defined in the @context, so the document expands to RDF, serialises to Turtle or N-Triples and can be checked against SHACL shapes. It is also the form you can shape yourself. The vocabularies that describe a battery, a textile, a packaging unit or an EUDR-relevant commodity live in openepcis-dpp-ready as ontology files with their JSON Schemas and shapes beside them, and a connector mapping can target any term they define. You can publish it today, for a product group no regulation has reached yet, and it will still be readable by anything that speaks GS1.

The second form is the EN 18223:2026 DigitalProductPassport, served over the method set that CEN/CENELEC's EN 18222 defines for passport lifecycle management and searchability — CreateDPP, ReadDPPById, ReadDPPByProductId, ReadDPPVersionByIdAndDate, UpdateDPPById, DeleteDPPById and the rest. CEN publishes no OpenAPI document for that method set, so the contract OpenEPCIS serves is hand-authored: every path, verb, parameter and status code cites the EN 18222 clause it comes from, and the standard's own text is not reproduced. This form is not free-form: EN 18223 fixes an envelope, and the derivation fills it in a fixed order — digitalProductPassportId, uniqueProductIdentifier, granularity, dppSchemaVersion, dppStatus, lastUpdated, economicOperatorId, facilityId, contentSpecificationIds. Two of those the service refuses to do without at creation time: master data with no GS1 Digital Link to serve as the uniqueProductIdentifier, or with no economic operator identity, is rejected by CreateDPP rather than stored and served as a half-passport. That rigidity is the point. It is what a market surveillance authority, a customs system or somebody else's passport client can rely on without a bilateral agreement.

Neither form is a translation of the other, and neither is stored twice. The EN form is derived on read, and by a service of its own: the DPP API is a separate Quarkus application with its own address rather than a corner of the resolver. It reads the master data — configured with dpp.masterdata.backend=resolver it fetches it live back out of the Digital Link resolver, so the data flows in both directions — lays the time-stamped amendments over it as an overlay, and computes the passport from the result. Above the data elements sits the envelope, whose handful of keys map from fixed passport IRIs. Everything below it is derived per property with no hand-written mapping — the property IRI becomes the dictionaryReference, the ontology range becomes the valueDataType, and the shape of the value chooses the object type, so a literal becomes a SingleValuedDataElement, a set becomes a DataElementCollection and a document reference becomes a RelatedResource. Three JSON representations come out of the same computation: compressed (the EN 18223 §5.2 form, with operational as a silent alias — the master-data properties are echoed verbatim and their shape preserved under the operational @context, so a body written through the API round-trips), full (also expanded, the Annex A form with every data element spelled out) and gs1 (the stored GS1 body on its own). The same passport is also served as XML — Annex B compressed or expanded — and as Turtle, N-Triples or N-Quads.

Why keep both, then? Because each can do something the other cannot. EN 18223 specifies plain JSON and deliberately keeps semantic definitions out of the payload, reachable out of band through a dictionaryReference, so that catalogues built on IRDIs — IEC 61360, eCl@ss, the Asset Administration Shell — can take part without re-minting their definitions as web IRIs; the price is that an IRDI cannot be dereferenced, where a web IRI can. The GS1 form pays the opposite price and gets the opposite benefit. Keeping them as two derivations of one record, rather than two records, is what stops them from drifting apart.

Changes are recorded the same way: an amendment is an overlay on the immutable master data — either a whole-document RFC 7396 merge patch or a targeted edit at one element path — and each amendment is time-stamped. Those stamps are the version history. They are what lets a reader ask for the passport as it stood on a given date, and they are what EN 18221 archiving, which begins with the first change, is built on.

Beside the passports: the event half

Master data answers what this product is. It cannot answer what became of this particular one, and it should not try. That question belongs to EPCIS 2.0, which OpenEPCIS runs as a separate repository with its own address and its own rights — capture to write, query to read — even where a deployment happens to host both on one machine.

The class/instance distinction runs through everything here. A bare GTIN is the model. A GTIN with a lot number (AI 10) is an LGTIN and therefore class level, so it travels in an event's quantityList as an epcClass. A GTIN with a serial number (AI 21) is an SGTIN, a single item, and travels in the epcList. An SSCC (AI 00) identifies a logistic unit and becomes the parentID of an aggregation. Putting an LGTIN in an epcList produces an event that validates and means the wrong thing, which is why the connectors derive these identifiers rather than letting anyone type them: every one of them is a canonical GS1 Digital Link URI on id.gs1.org — an identity, not an address, so two companies describing the same pallet produce byte-identical strings.

Event identity is derived too, and it is derived from the event itself: the eventID is the canonical CBV event hash, ni:///sha-256;…?ver=CBV2.0, computed over everything the event asserts apart from a short exclusion list — the identifier itself, recordTime, an error declaration, the @context. Anybody holding the event can recompute it, so it names the statement rather than the sender. A repeat poll, a nightly sweep or a retry after a half-done publish therefore arrives at the same identifier, and the repository recognises the repetition twice over: it de-duplicates on that hash, and it separately refuses an eventID it has already seen. The connectors send GS1-Capture-Error-Behaviour: proceed, so a re-capture becomes a no-op rather than a failed job.

The precondition is that the time comes from the source — date_done on an Odoo transfer, creation on a Frappe document, created_at on a UnoPim product — and never from the clock at reporting time. The event time is part of the statement and therefore part of the identity; inventing one would rename the same movement on every attempt. Where the source is silent, no event is made, and the connector says so where somebody will see it.

What each connector contributes to that half differs. The Java connectors mint exactly one kind of event: a commissioning ObjectEvent (action=ADD, bizStep=commissioning) the first time a batch or a serial number is published, and only when the connection has epcis.enabled and the article itself consents through commissionCaptureEnabled. It deliberately carries no ilmd: a production date copied into an event is a second copy that can go stale, while the instance's own master data stays resolvable through the gs1:masterData link registered for that exact instance path. The Odoo connector goes further and reports movement: a validated stock transfer becomes an ObjectEvent with action=OBSERVE, whose bizStep and disposition come from the operation type as data rather than from code, whose read point and business location are SGLNs derived from the location's GLN, and whose bizTransactionList ties the physical record to the commercial one. Packing becomes its own AggregationEvent under a minted SSCC, emitted before the movement event because that is the order of reality.

Above everything: the resolver as the web layer

The layer that makes all of this reachable is the GS1 Conformant Resolver, and its job is short to describe: it turns an identifier into a URL, that URL into a linkset, and each request into a decision about who may see what.

The linkset is served as RFC 9264 application/linkset+json with a Link header pointing back at itself and another at its JSON-LD context. Each entry is a typed destination on the same anchor. gs1:masterData points at the master-data document. gs1:dpp points at the DPP API's ReadDPPByProductId endpoint for this product's canonical Digital Link, which is how the two passport forms end up reachable from the same printed code. That entry exists only once a deployment tells the resolver where its DPP API lives, through a single property — openepcis.digital-link-resolver.dpp-base-url, bound to the environment variable OPENEPCIS_DLR_DPP_BASE_URL and empty by default. With no value set, no gs1:dpp entry is emitted at all; what the value should be is a deployment decision, and no address is baked into the code. gs1:pip points at a consumer-facing product page, which is where a PIM's own published passport page belongs. gs1:epcisRepository points at the event half. Link types resolve in any spelling — the full IRI https://ref.gs1.org/voc/pip, the CURIE gs1:pip and the bare pip all land on the same storage key — and where a requested link type has several equally good targets, the resolver can answer 300 Multiple Choices with the linkset rather than silently picking one.

Access is the second half of the resolver's job, and it uses the same three tiers as the passport API, spelled identically so a tier travels unchanged between stored document, served document and search-index role filter: Public, AuthorizedOnly and Restricted. The vocabulary says what those tiers are meant to express, in the words of ESPR Article 9 — Public for everyone including market surveillance and customs, AuthorizedOnly for authorities alone, Restricted for named authorised economic operators. What a running resolver enforces is narrower and purely mechanical: Restricted for a caller who holds the restricted role and belongs to the owning tenant, AuthorizedOnly for any authenticated member of that tenant, Public for everybody else — an authority outside the tenant included. At runtime there is no such actor as customs, only tenant membership and a role, and who holds the restricted role is a deployment decision in the identity provider rather than something the code can promise.

Document-level access is enforced today by OpenSearch document-level security against the stored accessLevel, which decides whether a record resolves at all. Field-level filtering decides which of a record's fields are served; it touches read paths only — a write or a patch is never filtered, or an operator's edit would silently drop the fields they cannot see — and it fails closed, falling back to a minimal policy when the policy store is unreachable. It is also still behind a rollout gate: dlr.field-access.enforce defaults to false, and until it is switched on no field is filtered on any read path. The tiers themselves come from the vocabulary rather than from code: a property annotated with an access level contributes it as the semantic default, and an annotation naming a mandating authority locks that term outright — a deployment or tenant policy can then neither loosen nor tighten it. For every term that is not mandated, policy may tighten but never loosen, and a property that says nothing at all falls back to AuthorizedOnly — closed toward the public, not open.

Where the connectors stand

Four source systems are served today.

UnoPim is the furthest along and has two halves. The Java adapter polls updated_at, listens to one webhook on product.created / product.updated, and publishes products and batches — a PIM knows about models and lots, not about serial numbers or parties. Where the GTIN comes from is a per-connection decision, source.options.gtin-from: composed, the default, builds it from the connection's company prefix, the SKU as the article reference and a computed check digit; sku treats the SKU as already being the GTIN, for merchandise carrying somebody else's EAN; and any other value is read as an attribute code, dpp_gtin — UnoPim's own passport field for a GS1 key — being the obvious one. A SKU that is not numeric, or too long, or a missing prefix, is named in the log and the record skipped, rather than turned into a key that points at somebody else's product. Values are read from all four of UnoPim's value sections, with the more specific one winning, translations become a GS1 language map, images become referencedFile entries of type PRODUCT_IMAGE, and measurement attributes are resolved against the platform's UN/CEFACT Recommendation 20 table so a value in grams arrives as {"value": 250, "unitCode": "GRM"}. Very little is written back — the canonical GTIN into dpp_gtin, because a thirteen-digit key derived from a five-digit SKU exists nowhere a human can see it, and ddm_action_required as a plain yes or no. Deliberately not the identity status: it reads unverified when the GS1 registry was merely unreachable, and a merchant who takes that for a data error goes looking for a mistake that is ours. Beside the adapter there is an optional PHP package that adds the interactive half inside UnoPim's own product form: a panel showing the platform's current verdict on the product's identity, its licensee and company prefix, its Digital Link and a QR code; a GPC picker that searches by words instead of eight-digit codes; and, for a product with no GTIN yet, two equally weighted options — draw the next number from your own prefix, or deposit one you already hold.

ERPNext needs no Frappe app installed. An API key and secret on a user, two custom fields and five webhooks (Item, Supplier, Customer, Batch, Serial No) are the whole footprint, and the GTIN is read from the item's barcode child table. It is the one adapter that carries instance level out of the source system: a Batch becomes an LGTIN document under /products/{gtin}/10/{lot} and a Serial No becomes an SGTIN document under …/21/{serial} — but only for items actually flagged as batched or serialised, because the others are ERP bookkeeping rather than catalog instances.

metasfresh needs nothing installed at all: an API token issued against a read-only role, and the REST v2 interface. It polls — metasfresh has no webhooks, so the webhook rung of the diagnosis ladder simply reports itself as not applicable. GTINs come from the product's ean field and GLNs from the business partner's locations, taking the first address whose GLN passes its check digit. Writing a back-reference into metasfresh through its External References API is available, off by default, and the one thing that asks the role for a write permission. The coupling is deliberately thin, and stays thin by rule rather than by habit: no metasfresh dependency in any Maven scope and no copied schemas or field lists, the network boundary being the only connection.

Odoo is a separate matter, and lives in its own public repository under LGPL-3 because Odoo brings its own runtime, packaging and licensing world. On both maintained branches — 18.0 and 19.0 — it is six addons: a base connector that queues products and contacts into an outbox for a scheduled job to publish, with publication opt-in per record; a stock addon that publishes lots and serial numbers as instance documents; an expiry addon contributing mapping rows; the events addon described above; a manufacturing bridge that reports a production order as a transformation; and a point-of-sale bridge that recognises a till and reports retail_selling / retail_sold instead of a plain delivery. Events that come back are read into an inbox, where they are made visible on the lot or the package and where they deliberately never move stock — another company's event is an observation, not a document. The Odoo walkthrough follows one warehouse day through all of it, screen by screen, with the event each step produces.

What they share

Everything system-specific lives in an adapter, which is thin on purpose. Four methods are all it must supply: what system type it is, what changed since a given cursor, one record fetched in full, and a reachability ping. Everything else is optional and defaults to doing nothing — writing something back after a publish, verifying a webhook signature, contributing consumer-facing links, taking values from the catalog. The loop itself is shared — cursor, changes, mapping, key, hash comparison, PUT, state, cursor forward — and runs identically whether a poll or a webhook started it.

Four design rules run through that loop and are worth knowing before you operate one.

A webhook is only a doorbell. Its payload is never used as a data source; the record is re-read from the source API after the ring. This is not caution for its own sake — a measured UnoPim create fires two deliveries whose bodies do not even contain the identifier set in the same request, and a failed delivery is never retried.

Readiness informs, it never blocks. A connection can report which terms a downstream registrar still wants for a given entity kind, and that information feeds a hint in a user interface or a report. It is never a gate that stops a record from being published.

Publishing is idempotent. The catalog's PUT is create-or-update and merges, and on the connector's side a canonical SHA-256 of the payload skips a record whose content has not changed. That stamp lives in the catalog record's own extensions slot, keyed by connection name, rather than in a table the connector has to keep in step.

A data problem and our problem are different types. A verdict about an identifier says more than yes or no: syntax, check digit, company-prefix boundary, registry status, licensee, a reason, and provenance per individual fact — a cached answer carries the time of the registry call, not the time of the cache hit, so a human can see how old the knowledge is. When the registry or the resolver cannot be reached the verdict comes back degraded, and every offline fact still stands, because it was computed before anything could fail. Code branches on whether a human editing the record could fix it, never on whether a registry happened to answer.

Two operational habits complete the picture: a connection ships with dry-run set to true and only writes after somebody deliberately turns it off — behind the catalog are real registrars, GS1 production among them — and every test key in this stack starts with 952, the GS1 test range.

Mappings are data, not code: one YAML file per connection, one document per entity family, each rule naming a source, a target GS1 term, a kind and a direction. Direction decides who owns a field — to-catalog for a field the source owns, from-catalog for one the platform owns and writes back, both for a field either side may edit. Identifiers are pointedly absent from these files: GTIN, GLN and lot number are read into the record's key rather than mapped like ordinary values.

Status

This is a young part of the platform, and it is worth being precise about its edges. Four source systems have adapters: UnoPim, ERPNext and metasfresh in the shared Java connector, and Odoo as its own set of addons. There is no adapter for any other system.

The EN 18223 passport is the one place where a first sync does not yet arrive at a finished result. Deriving it needs an economicOperatorId, and the deriver takes that from the record's gs1:manufacturer — either the organisation's own party Digital Link or a GLN it can build one from. None of the three shipped default mappings targets manufacturer or manufacturingPlace; organisations are synchronised, but as records of their own, and the product document does not point at them. Without that pointer the passport is not merely incomplete, it is absent: every read path refuses with missing mandatory EN 18223 fields: economicOperatorId. Two things therefore have to be done by hand for now — a mapping rule onto manufacturer, a term the connector vocabulary already carries with range gs1:Organization, and setting the DPP API's dpp.masterdata.backend to resolver, because its built-in default memory only knows passports that were written to it through CreateDPP, which no connector ever calls. Everything else a first sync promises does arrive: a complete GS1 master-data document, a resolving Digital Link with its linkset, and for UnoPim a published PIM passport page as gs1:pip.

Deletion is not handled either, and that is a decision rather than an oversight. A delta poll asks the source for records changed since the cursor and so never sees one that is gone; a webhook whose record has meanwhile disappeared is logged and the catalog document kept, because removing something from the catalog is treated as a deliberate act and not as the side effect of a delivery. Archiving in the source has no effect at all — a deactivated product keeps being published. Withdrawing a published passport page in UnoPim does not remove the gs1:pip entry pointing at it: the link stays and the page answers with a tombstone rather than a 404. Taking any of this back is a manual step on the catalog and linkset APIs, not something a connector follows.

The interactive half — a verdict panel, a GPC search, drawing a number from inside the host application — exists for UnoPim and Odoo. ERPNext and metasfresh are data paths only.

On the event side, the Java connectors emit commissioning events and nothing else: no movement, aggregation, transaction or transformation events, and no reading of events back. Four of the five event types exist in the Odoo connector instead, on both of its maintained branches, with aggregation over nested logistic units on 19.0 only because Odoo 18 has no nesting to report. AssociationEvent is produced nowhere in this stack, no connector ever states a TransactionEvent with action=ADD, and GS1 places are not published from Odoo at all.

There is no event-driven channel from the platform back into a source system. Corrections made on the platform reach a connected system through the ordinary poll and the payload hash comparison, not through a notification.

Nor is there a public way to obtain any of this yet. The Java connector is a Quarkus application shipped as a container image from a private registry, and the PHP package that adds the interactive half to UnoPim is declared proprietary and published in no repository we can point at. Odoo is the exception: its addons are public under LGPL-3.