Skip to content

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.

ClassKey (scheme)EPCIS / CBV role
SiteGLN (AI 414)bizLocation / readPoint, urn:epc:id:sgln:….0
FacilityGLNbizLocation
DockSGLN (GLN + AI 254 extension)readPoint / bizLocation (sub-location)
ZoneSGLNbizLocation (sub-location)
YardSlotSGLNbizLocation (sub-location)
VehicleGIAI (AI 8004)epcList / parentID
TrailerGIAIepcList / parentID
ContainerISO 6346 (BIC)epcList / parentID, urn:epc:id:bic:…
LogisticUnitSSCC (AI 00)epcList / parentID
AssetGIAIepcList
ReturnableAssetGRAI (AI 8003)epcList / parentID (serialised GRAI only)
DeviceGIAIsensorMetadata.deviceID
SensorGIAIsensorReport (type, uom, minValue/maxValue)
ShipmentGSIN (AI 402)bizTransactionList (desadv, bol)
Ordernone (issuer’s number)bizTransactionList (po)
LotLGTIN (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.

RelationExampleEPCIS
locatedInTrailer → YardSlotObjectEvent, bizLocation; bizStep arriving / receiving / storing, ended by departing
isPartOfDock → Facility, Sensor → Devicemaster data (the SGLN hierarchy; sensorMetadata.deviceID)
measuresSensor → TrailerObjectEvent with sensorElementList; bizStep sensor_reporting
carriesVehicle → Trailer → ContainerAggregationEvent, parentID = carrier; loading / unloading
assignedToTrailer → Dock, Device → Trailernone: a plan, not an observation; maps to bizTransaction or master data
fulfilsShipment → Ordershared bizTransaction (po + desadv/bol) on the shipping event
containedInLogisticUnit → LogisticUnit, Lot → LogisticUnitAggregationEvent (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) Trailer

The 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, source siteplan:<plan id>:<element id> (the element id carries the IFC GlobalId or the DXF handle) and the person who confirmed it in x_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 as x_ properties;
  • the plan’s Site and Facility, named after the plan and written once. Facility, zones and docks are isPartOf it; 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.