Twin ontology & graph
FACE models an operation as a twin graph: entities (a site, a dock, a reefer trailer, a sensor) and the relations between them, each fact stamped with where it came from, how it is known and when it was true. The vocabulary is GS1 EPCIS 2.0 + CBV 2.0: every class and relation maps to an EPCIS role, as the tables below show.
- The ontology (classes, relations, validators, URI forms) is served by
TwinOntologyService(GetTwinOntology,ValidateTwinIdentifier). - The graph is Runink’s twin store (append-only, bitemporal) on FACE’s appfs tenant root, served by
TwinGraphService(ListTwinEntities,GetTwinEntity,TraverseTwin,UpsertTwinEntity,LinkTwinEntities,ListTwinDevices). - In the FACE app, the twin lives on Actionable Twins › Map. The Entities panel over the map is the entity browser (filter by class, search). The map plots located entities as points, and tapping one opens its detail. A device connection’s card on Ask opens the devices that connection reported into the twin.
Classes
Every identifier property is optional. An entity whose GLN or SSCC is not known has none; FACE never pads, derives or guesses one.
| Class | Key (scheme) | EPCIS / CBV role |
|---|---|---|
| Site | GLN (AI 414) | bizLocation / readPoint, urn:epc:id:sgln:….0 |
| Facility | GLN | bizLocation |
| Dock | SGLN (GLN + AI 254 extension) | readPoint / bizLocation (sub-location) |
| Zone | SGLN | bizLocation (sub-location) |
| YardSlot | SGLN | bizLocation (sub-location) |
| Vehicle | GIAI (AI 8004) | epcList / parentID |
| Trailer | GIAI | epcList / parentID |
| Container | ISO 6346 (BIC) | epcList / parentID, urn:epc:id:bic:… |
| LogisticUnit | SSCC (AI 00) | epcList / parentID |
| Asset | GIAI | epcList |
| ReturnableAsset | GRAI (AI 8003) | epcList / parentID (serialised GRAI only) |
| Device | GIAI | sensorMetadata.deviceID |
| Sensor | GIAI | sensorReport (type, uom, minValue/maxValue) |
| Shipment | GSIN (AI 402) | bizTransactionList (desadv, bol) |
| Order | none (issuer’s number) | bizTransactionList (po) |
| Lot | LGTIN (AI 01 + AI 10) | quantityList, ilmd (cbvmda:lotNumber, expiry) |
Quantities carry UN/CEFACT Recommendation 20 unit codes, as EPCIS does: CEL (°C), KGM,
MTR, MTK, P1 (percent), SEC, DD (degree). The full property list per class, with
required/optional and the EPCIS field each maps to, is what GetTwinOntology returns.
Relations
Each relation is directed (from rel to), and the ontology lists which class pairs it allows.
A write outside that domain/range is refused.
| Relation | Example | EPCIS |
|---|---|---|
locatedIn | Trailer → YardSlot | ObjectEvent, bizLocation; bizStep arriving / receiving / storing, ended by departing |
isPartOf | Dock → Facility, Sensor → Device | master data (the SGLN hierarchy; sensorMetadata.deviceID) |
measures | Sensor → Trailer | ObjectEvent with sensorElementList; bizStep sensor_reporting |
carries | Vehicle → Trailer → Container | AggregationEvent, parentID = carrier; loading / unloading |
assignedTo | Trailer → Dock, Device → Trailer | none: a plan, not an observation; maps to bizTransaction or master data |
fulfils | Shipment → Order | shared bizTransaction (po + desadv/bol) on the shipping event |
containedIn | LogisticUnit → LogisticUnit, Lot → LogisticUnit | AggregationEvent (childEPCs or childQuantityList); packing / unpacking |
Lots are produced by EPCIS TransformationEvents.
Identifiers
ValidateTwinIdentifier accepts a plain key, a GS1 element string ((414)…(254)…), an EPC URI
or a GS1 Digital Link, checks it (GS1 mod-10 check digits; ISO 6346 mod-11) and returns its other
forms. The FACE app’s identifier field calls it on every edit: the server is the only place a check
digit is computed, and a server it cannot reach reads not checked, never valid.
The EPC URI needs the GS1 Company Prefix length, which a plain key does not carry. When the caller does not supply it, the EPC URI is reported absent with that reason, and the twin stores the Digital Link instead. It is never formed from an assumed split, because a wrong split is a well-formed URI naming another company’s object.
The validators are tested against the published examples of the GS1 EPC Tag Data Standard 2.1
(§7), for instance urn:epc:id:sscc:9521141.1234567890 ↔ (00)195211412345678900, and against
the ISO 6346 code CSQU3054383.
Example: a DC with a reefer at the door
The keys below use GS1’s example company prefix 9521141 from the Tag Data Standard. They show
the shape, not a real site.
Site "DC Nord" gln = urn:epc:id:sgln:9521141.12345.0
Dock door "7" sgln = urn:epc:id:sgln:9521141.12345.D7 isPartOf → Site
YardSlot slot "Y12" sgln = urn:epc:id:sgln:9521141.12345.Y12 isPartOf → Site
Trailer plate "AB-123-CD" giai = (absent: not known) locatedIn → YardSlot Y12
trailer_type = reefer assignedTo → Dock 7
Device reefer logger giai = urn:epc:id:giai:9521141.LOG42 assignedTo → Trailer
heartbeat_every_s = 300
Sensor return-air probe measurement_type = gs1:Temperature isPartOf → Device
uom = CEL, spec_min = 2, spec_max = 8 measures → Trailer
LogisticUnit pallet sscc = urn:epc:id:sscc:9521141.1234567890 (carried by) TrailerThe trailer’s GIAI is absent because nobody stated one. The graph still knows the trailer, by its plate and by its relations.
Evidence and the device registry
Every fact carries an evidence kind from a closed vocabulary, strongest first:
OPERATOR_CONFIRMED, OBSERVED, DECLARED, INFERRED, GUESSED. Edits made in the FACE app are
OPERATOR_CONFIRMED with source operator:<subject>. A session that names no person is refused,
and nothing is recorded as anonymous. Writes need the editor or admin role.
ListTwinDevices judges each Device and Sensor against its heartbeat_every_s:
- Reporting: it was heard from within that interval.
- Device fault: it missed its heartbeat, or was never heard from after the first interval.
- Awaiting first report: it is new and its first heartbeat is not due yet.
- Not judged: no interval is stated, so its silence cannot be judged.
None of these states is shown as “all fine”.
Site plans in the twin
A factory or warehouse plan (IFC, DXF, PDF or a picture; IFC and DXF are BIM/CAD plan files) is shown on Actionable Twins › Map, in the Site plans panel over the map: the values inferred from the plan, with their twin bindings. The map draws its footprint for physical-storage awareness, and tapping the footprint opens the plan over the map. A plan becomes part of the twin only through an operator. When an editor or admin confirms a zone, a dock or a yard slot, FACE writes it to the twin graph:
- a Zone, Dock or YardSlot per confirmed element, named after the element (its
door number or slot label for a dock or a slot), with evidence
OPERATOR_CONFIRMED, sourcesiteplan:<plan id>:<element id>(the element id carries the IFC GlobalId or the DXF handle) and the person who confirmed it inx_confirmed_by. Its level, outline (x_polygon, in plan units), position, width and area (x_area_m2: the area the file states, else computed from the outline when the plan’s unit is known) are kept asx_properties; - the plan’s Site and Facility, named after the plan and written once. Facility, zones
and docks are
isPartOfit; a yard slot is part of the Site.
Elements read from a file but never confirmed, and everything the vision model proposed, are never written. Identifiers are not derived from a plan: an SGLN appears only when an operator enters it on the twin entity, and a later re-confirm keeps it. Confirming again or editing the element writes a new version of the same entity. Rejecting it, or changing it to a kind with no twin class, writes a tombstone, but only if it was bound before. A kind change between zone, dock and yard slot retires the old entity and writes the new one.
Both sides link to each other. The site plan on the map shows the selected element’s twin entity and opens its detail; the entity’s detail names the plan and element it came from and opens the plan on that element.
The plan’s live overlay places a reading on a zone when its location names the zone, and also
when the reading’s sensor is a Device that is locatedIn a zone the plan bound, or a
Sensor that isPartOf such a device. The reading says which rule placed it: zone id,
zone name, or twin locatedIn (with via <device> for a sensor). A sensor whose twin names two
of the plan’s zones is not placed.
Reading the results
- Operators build the graph, directly or by confirming site-plan elements. An empty twin is shown as empty.
- A GIAI is checked for form. GIAI has no check digit, so a well-formed GIAI can still be a mistyped one.
- Supply the GS1 Company Prefix length to form an EPC URI. A plain key does not carry it, and without it the EPC URI is reported absent with that reason.