Graph Schema
Complete graph schema covering the Digital Thread (L1) and Digital Twin evolution layers (L2-L4)
Table of Contents
- Overview
- Node Types — Digital Thread (L1)
- Requirement
- DesignElement
- BOMItem
- TestProcedure
- TestExecution
- Evidence
- Certification
- RiskItem
- DecisionRecord
- Gate
- Session
- CAPARecord (P2)
- InterfaceContract (P2)
- KnowledgeSource (P2)
- Node Types — Twin Instance & Simulation (L2-L4)
- TwinModel (P2)
- DeviceInstance (P2)
- TelemetrySource (P3)
- BehavioralModel (P3)
- SimulationRun (P3)
- FleetGroup (P4)
- Relationship Types
- Digital Thread Relationships (L1)
- Cross-Domain Ontology Relationships (L1)
- Twin Instance & Simulation Relationships (L2-L4)
- Neo4j Constraints & Indexes
- Uniqueness Constraints (P1)
- Twin Instance Constraints (P2-P3)
- Performance Indexes
- Example Queries
- Traceability: Requirement to Test Evidence (L1)
- Gate Readiness Check (L1)
- Device Fleet Health (L3-L4)
- Related Documents
Overview
The MetaForge graph schema defines the node types, relationships, and constraints that form the Digital Twin’s data model. The schema is layered to support phased delivery:
| Layer |
Phase |
Scope |
| L1 — Digital Thread |
P1 (MVP) |
Artifact graph, traceability, versioning, constraints |
| L2 — Operational Twin |
P2 |
Device provisioning, test telemetry, CAPA workflows |
| L3 — Live Twin |
P3 |
Real-time device synchronization, telemetry sources |
| L4 — Simulation Twin |
P3-P4 |
Behavioral models, simulation runs, fleet analytics |
All nodes carry common base properties:
| Property |
Type |
Description |
id |
UUID |
Unique identifier |
version |
Integer |
Optimistic concurrency version counter |
createdAt |
DateTime |
Creation timestamp |
updatedAt |
DateTime |
Last modification timestamp |
createdBy |
String |
Actor ID (agent code, user ID, or device ID) |
Node Types — Digital Thread (L1)
These nodes form the core traceability graph delivered in Phase 1 (MVP).
Requirement
| Property |
Required |
Type |
Description |
title |
Yes |
String |
Short requirement title |
description |
Yes |
String |
Full requirement description |
category |
Yes |
String |
Requirement category |
priority |
Yes |
String |
Priority level |
status |
Yes |
Enum |
draft / active / approved / deprecated |
acceptanceCriteria |
No |
String |
Acceptance criteria |
source |
No |
String |
Origin of the requirement |
rationale |
No |
String |
Justification |
DesignElement
| Property |
Required |
Type |
Description |
name |
Yes |
String |
Element name |
domain |
Yes |
Enum |
mechanical / electrical / firmware / system |
type |
Yes |
String |
Element type within domain |
description |
No |
String |
Description |
parameters |
No |
Map |
Key-value parameters |
BOMItem
| Property |
Required |
Type |
Description |
mpn |
Yes |
String |
Manufacturer part number |
manufacturer |
Yes |
String |
Manufacturer name |
description |
Yes |
String |
Part description |
quantity |
Yes |
Integer |
Quantity required |
package |
Yes |
String |
Package type |
unitPrice |
No |
Float |
Unit price |
stock |
No |
Integer |
Available stock |
leadTime |
No |
String |
Lead time |
lifecycle |
No |
String |
Lifecycle status |
specifications |
No |
Map |
Technical specifications |
TestProcedure
| Property |
Required |
Type |
Description |
name |
Yes |
String |
Procedure name |
category |
Yes |
Enum |
functional / environmental / emc / safety |
requirementIds |
Yes |
List |
Linked requirement IDs |
description |
No |
String |
Procedure description |
automationLevel |
No |
Enum |
manual / semi / full |
TestExecution
| Property |
Required |
Type |
Description |
procedureId |
Yes |
String |
Linked TestProcedure ID |
timestamp |
Yes |
DateTime |
Execution timestamp |
status |
Yes |
Enum |
passed / failed / skipped |
duration |
Yes |
Duration |
Execution duration |
notes |
No |
String |
Execution notes |
artifactIds |
No |
List |
Related artifact IDs |
commit |
No |
String |
Git commit hash |
Evidence
| Property |
Required |
Type |
Description |
type |
Yes |
Enum |
test-report / certification / analysis |
status |
Yes |
Enum |
pending / submitted / approved / rejected |
artifactId |
No |
String |
MinIO artifact reference |
reviewedBy |
No |
String |
Reviewer ID |
reviewNotes |
No |
String |
Review comments |
Certification
| Property |
Required |
Type |
Description |
regime |
Yes |
Enum |
UKCA / CE / FCC / PSTI |
standard |
Yes |
String |
Standard reference |
market |
Yes |
String |
Target market |
status |
No |
String |
Certification status |
expiryDate |
No |
Date |
Expiry date |
notifiedBody |
No |
String |
Notified body name |
RiskItem
| Property |
Required |
Type |
Description |
type |
Yes |
Enum |
single-source / eol / long-lead / safety / cybersecurity |
severity |
Yes |
String |
Severity level |
description |
Yes |
String |
Risk description |
mitigation |
No |
String |
Mitigation strategy |
owner |
No |
String |
Risk owner |
dueDate |
No |
Date |
Mitigation due date |
fmeaId |
No |
String |
FMEA reference |
DecisionRecord
| Property |
Required |
Type |
Description |
title |
Yes |
String |
Decision title |
status |
Yes |
Enum |
proposed / accepted / rejected / superseded |
date |
Yes |
Date |
Decision date |
context |
No |
String |
Decision context |
options |
No |
List |
Considered options |
outcome |
No |
String |
Chosen outcome |
rationale |
No |
String |
Decision rationale |
Gate
| Property |
Required |
Type |
Description |
type |
Yes |
Enum |
EVT / DVT / PVT |
status |
Yes |
Enum |
not-ready / at-risk / ready / passed |
score |
No |
Float |
Readiness score |
blockers |
No |
List |
Blocking items |
passedAt |
No |
DateTime |
Gate passage timestamp |
approvedBy |
No |
String |
Approver ID |
Session
| Property |
Required |
Type |
Description |
skill |
Yes |
String |
Skill name executed |
status |
Yes |
String |
Session status |
agentCode |
Yes |
String |
Agent identifier |
input |
No |
Map |
Session input data |
output |
No |
Map |
Session output data |
traces |
No |
List |
Execution trace references |
CAPARecord (P2)
| Property |
Required |
Type |
Description |
type |
Yes |
Enum |
corrective / preventive |
severity |
Yes |
String |
Severity level |
status |
Yes |
String |
CAPA status |
rootCause |
No |
String |
Root cause analysis |
action |
No |
String |
Corrective/preventive action |
owner |
No |
String |
Action owner |
verifiedAt |
No |
DateTime |
Verification timestamp |
InterfaceContract (P2)
| Property |
Required |
Type |
Description |
name |
Yes |
String |
Interface name |
fromDomain |
Yes |
String |
Source domain |
toDomain |
Yes |
String |
Target domain |
protocol |
Yes |
String |
Interface protocol |
schema |
No |
Map |
Interface schema definition |
version |
No |
String |
Contract version |
testIds |
No |
List |
Validation test IDs |
KnowledgeSource (P2)
Represents a document or data source that has been ingested into the Knowledge Layer. Each KnowledgeSource maps to one or more embedding fragments in pgvector.
| Property |
Required |
Type |
Description |
sourceType |
Yes |
Enum |
datasheet / application_note / design_guide / errata |
title |
Yes |
String |
Document title |
artifactId |
Yes |
String |
MinIO artifact reference |
fragmentCount |
No |
Integer |
Number of embedding chunks created |
embeddingModel |
No |
String |
Model used for embedding (e.g., all-MiniLM-L6-v2) |
status |
Yes |
Enum |
pending / indexing / indexed / failed |
indexedAt |
No |
DateTime |
When indexing completed |
partNumber |
No |
String |
Associated part number (for datasheets) |
metadata |
No |
Map |
Additional metadata (tags, version, etc.) |
Node Types — Twin Instance & Simulation (L2-L4)
These nodes extend the graph for device synchronization, behavioral simulation, and fleet analytics.
TwinModel (P2)
| Property |
Required |
Type |
Description |
name |
Yes |
String |
Product model name |
version |
Yes |
String |
Model version |
productId |
Yes |
String |
Product identifier |
schema |
Yes |
Map |
Model schema definition |
behavioralModels |
No |
List |
Linked behavioral model IDs |
constraints |
No |
List |
Model-level constraints |
syncPolicy |
No |
Map |
Default synchronization policy |
DeviceInstance (P2)
| Property |
Required |
Type |
Description |
serialNumber |
Yes |
String |
Unique serial number |
twinModelId |
Yes |
String |
Linked TwinModel ID |
status |
Yes |
Enum |
provisioned / active / maintenance / decommissioned |
location |
No |
String |
Physical location |
firmwareVersion |
No |
String |
Deployed firmware version |
deployedAt |
No |
DateTime |
Deployment timestamp |
lastSyncAt |
No |
DateTime |
Last synchronization timestamp |
TelemetrySource (P3)
| Property |
Required |
Type |
Description |
instanceId |
Yes |
String |
Linked DeviceInstance ID |
sensorType |
Yes |
String |
Sensor type |
dataSchema |
Yes |
Map |
Data schema for readings |
sampleRate |
Yes |
Float |
Sample rate in Hz |
unit |
No |
String |
Measurement unit |
range |
No |
Map |
Valid measurement range |
calibration |
No |
Map |
Calibration data |
BehavioralModel (P3)
| Property |
Required |
Type |
Description |
name |
Yes |
String |
Model name |
modelType |
Yes |
Enum |
differential-equation / transfer-function / thermal-rc / lookup-table |
domain |
Yes |
String |
Engineering domain |
inputs |
No |
List |
Named inputs with units |
outputs |
No |
List |
Named outputs with units |
parameters |
No |
Map |
Model constants |
validationData |
No |
Map |
Validation dataset reference |
SimulationRun (P3)
| Property |
Required |
Type |
Description |
modelId |
Yes |
String |
Linked BehavioralModel ID |
instanceId |
Yes |
String |
Linked DeviceInstance ID |
timestamp |
Yes |
DateTime |
Simulation timestamp |
status |
Yes |
String |
Run status |
type |
Yes |
Enum |
prediction / what-if / validation |
inputs |
No |
Map |
Simulation inputs |
results |
No |
Map |
Simulation results |
duration |
No |
Duration |
Execution duration |
accuracy |
No |
Float |
Prediction accuracy metric |
FleetGroup (P4)
| Property |
Required |
Type |
Description |
name |
Yes |
String |
Fleet group name |
twinModelId |
Yes |
String |
Linked TwinModel ID |
criteria |
Yes |
Map |
Membership criteria |
memberCount |
No |
Integer |
Number of members |
aggregateMetrics |
No |
Map |
Fleet-level metrics |
Relationship Types
Digital Thread Relationships (L1)
| Relationship |
Source |
Target |
Phase |
Description |
SATISFIED_BY |
Requirement |
DesignElement |
P1 |
Design element satisfies requirement |
MANUFACTURED_BY |
DesignElement |
BOMItem |
P1 |
Design element implemented by BOM parts |
TESTED_BY |
BOMItem / DesignElement |
TestProcedure |
P1 |
Artifact has test procedure |
PRODUCES |
TestProcedure |
Evidence |
P1 |
Test produces evidence |
JUSTIFIES |
Evidence |
Certification |
P1 |
Evidence justifies certification |
DERIVED_FROM |
Requirement |
Requirement |
P1 |
Requirement decomposition |
DEPENDS_ON |
BOMItem |
BOMItem |
P1 |
Component dependency |
MITIGATES |
DesignElement |
RiskItem |
P1 |
Design mitigates risk |
BLOCKS |
RiskItem |
Gate |
P1 |
Risk blocks gate passage |
PRODUCED_BY |
Any |
Session |
P1 |
Provenance: artifact created by session |
SUPERSEDES |
Any |
Any (same type) |
P1 |
Revision chain |
APPROVED_BY |
Gate / DecisionRecord |
User |
P1 |
Governance trail |
EXECUTED_IN |
TestExecution |
TestProcedure |
P1 |
Execution of procedure |
RAISES |
TestExecution |
CAPARecord |
P1 |
Failed test raises CAPA |
Cross-Domain Ontology Relationships (L1)
These relationships encode physical and logical couplings between design elements across engineering domains. They are the foundation for cross-domain constraint propagation.
| Relationship |
Source |
Target |
Description |
THERMALLY_COUPLED_TO |
DesignElement |
DesignElement |
Thermal path between components (conduction, convection, radiation) |
ELECTRICALLY_CONNECTED_TO |
DesignElement |
DesignElement |
Electrical connection (power rail, signal trace, ground plane) |
MOUNTED_TO |
DesignElement |
DesignElement |
Physical mounting relationship (component on PCB, PCB in enclosure) |
CONTROLLED_BY |
DesignElement |
DesignElement |
Control relationship (sensor → MCU, MCU → actuator, firmware → peripheral) |
SHARES_RESOURCE |
DesignElement |
DesignElement |
Shared resource contention (SPI bus, power rail, cooling channel) |
CONSTRAINS |
DesignElement |
DesignElement |
One element constrains another (keep-out zone, timing dependency, voltage level) |
Example: Cross-domain coupling for a motor driver
-- The MOSFET is thermally coupled to the heatsink
MATCH (mosfet:DesignElement {name: 'Q1_MOSFET'})-[:THERMALLY_COUPLED_TO]->(heatsink:DesignElement {name: 'HS1'})
-- The MOSFET is electrically connected to the motor rail
MATCH (mosfet)-[:ELECTRICALLY_CONNECTED_TO]->(rail:DesignElement {name: 'VMOTOR_RAIL'})
-- The MOSFET is controlled by the MCU via PWM
MATCH (mosfet)-[:CONTROLLED_BY]->(mcu:DesignElement {name: 'MCU_STM32'})
-- The MCU firmware controls the PWM output
MATCH (mcu)-[:CONTROLLED_BY]->(pwm_driver:DesignElement {domain: 'firmware', name: 'pwm_driver'})
These ontology relationships enable the constraint engine to answer questions like:
- “If the ambient temperature rises, which components exceed thermal limits?” (traverse
THERMALLY_COUPLED_TO)
- “If we change the MCU, which firmware modules and peripherals are affected?” (traverse
CONTROLLED_BY)
- “Which components share this power rail and what’s the total current draw?” (traverse
ELECTRICALLY_CONNECTED_TO + SHARES_RESOURCE)
Twin Instance & Simulation Relationships (L2-L4)
| Relationship |
Source |
Target |
Phase |
Description |
INSTANCE_OF |
DeviceInstance |
TwinModel |
P2 |
Device is an instance of a product model |
FEEDS |
TelemetrySource |
DeviceInstance |
P3 |
Sensor feeds data to twin instance |
SIMULATED_BY |
DeviceInstance |
BehavioralModel |
P3 |
Device behavior predicted by model |
CALIBRATED_FROM |
BehavioralModel |
TestExecution |
P3 |
Model calibrated from real test data |
MEMBER_OF |
DeviceInstance |
FleetGroup |
P4 |
Device belongs to fleet group |
Neo4j Constraints & Indexes
Uniqueness Constraints (P1)
-- Core graph uniqueness
CREATE CONSTRAINT req_id IF NOT EXISTS FOR (r:Requirement) REQUIRE r.id IS UNIQUE;
CREATE CONSTRAINT bom_id IF NOT EXISTS FOR (b:BOMItem) REQUIRE b.id IS UNIQUE;
CREATE CONSTRAINT design_id IF NOT EXISTS FOR (d:DesignElement) REQUIRE d.id IS UNIQUE;
CREATE CONSTRAINT test_proc_id IF NOT EXISTS FOR (t:TestProcedure) REQUIRE t.id IS UNIQUE;
CREATE CONSTRAINT gate_id IF NOT EXISTS FOR (g:Gate) REQUIRE g.id IS UNIQUE;
CREATE CONSTRAINT session_id IF NOT EXISTS FOR (s:Session) REQUIRE s.id IS UNIQUE;
Twin Instance Constraints (P2-P3)
CREATE CONSTRAINT device_serial IF NOT EXISTS FOR (d:DeviceInstance) REQUIRE d.serialNumber IS UNIQUE;
CREATE CONSTRAINT twin_model_id IF NOT EXISTS FOR (t:TwinModel) REQUIRE t.id IS UNIQUE;
CREATE CONSTRAINT sim_run_id IF NOT EXISTS FOR (s:SimulationRun) REQUIRE s.id IS UNIQUE;
-- Digital Thread indexes
CREATE INDEX req_status IF NOT EXISTS FOR (r:Requirement) ON (r.status);
CREATE INDEX bom_lifecycle IF NOT EXISTS FOR (b:BOMItem) ON (b.lifecycle);
CREATE INDEX bom_mpn IF NOT EXISTS FOR (b:BOMItem) ON (b.mpn);
CREATE INDEX gate_type IF NOT EXISTS FOR (g:Gate) ON (g.type);
CREATE INDEX evidence_status IF NOT EXISTS FOR (e:Evidence) ON (e.status);
-- Twin Instance indexes
CREATE INDEX device_status IF NOT EXISTS FOR (d:DeviceInstance) ON (d.status);
CREATE INDEX device_model IF NOT EXISTS FOR (d:DeviceInstance) ON (d.twinModelId);
CREATE INDEX sim_run_type IF NOT EXISTS FOR (s:SimulationRun) ON (s.type);
Example Queries
Traceability: Requirement to Test Evidence (L1)
MATCH path = (r:Requirement)-[:SATISFIED_BY]->(d:DesignElement)
-[:MANUFACTURED_BY]->(b:BOMItem)
-[:TESTED_BY]->(tp:TestProcedure)
-[:PRODUCES]->(e:Evidence)
WHERE r.id = $requirementId
RETURN path
Gate Readiness Check (L1)
MATCH (g:Gate {type: 'EVT'})
OPTIONAL MATCH (risk:RiskItem)-[:BLOCKS]->(g)
WHERE risk.severity = 'critical'
OPTIONAL MATCH (r:Requirement {status: 'active'})
WHERE NOT (r)-[:SATISFIED_BY]->()
RETURN g, collect(risk) AS blockers, collect(r) AS unmetRequirements
Device Fleet Health (L3-L4)
MATCH (d:DeviceInstance)-[:INSTANCE_OF]->(tm:TwinModel {name: $modelName})
WHERE d.status = 'active'
OPTIONAL MATCH (d)<-[:FEEDS]-(ts:TelemetrySource)
OPTIONAL MATCH (sr:SimulationRun {instanceId: d.id})
WHERE sr.timestamp > datetime() - duration('P1D')
RETURN d.serialNumber, d.lastSyncAt, collect(ts.sensorType) AS sensors,
collect(sr.results) AS recentSimulations
Document Version: v1.1
Last Updated: 2026-02-28
Status: Technical Architecture Document