ADR-004: Digital Twin Standards Alignment

Align MetaForge’s graph schema with Asset Administration Shell (AAS) conventions now; build export adapters in Phase 3+

Table of Contents

1. ADR Header
2. Context
   1. Key Standards Evaluated
3. Decision
   1. Principle: Align the data model now, build export adapters later
   2. Actions — Now (Phase 1)
      1. 1. Add globalAssetId to key graph nodes
      2. 2. Add supplier to BOMItem
      3. 3. Document AAS-aligned keys in specification maps
      4. 4. Add format and schemaVersion to conversion pipeline metadata
   3. Actions — Phase 3+
   4. Standards Not Adopted
4. Architecture
   1. How AAS Export Will Work (Phase 3+)
   2. Graph Schema Changes
5. Consequences
   1. Positive
   2. Negative
   3. Risks and Mitigations
6. Related Documents

ADR Header

Context

The digital twin standards landscape is consolidating around several key frameworks. MetaForge needs to decide which standards to align with, when, and how deeply.

Full analysis is documented in the Digital Twin Standards Landscape research doc. This ADR captures the decisions.

Key Standards Evaluated

Decision

Principle: Align the data model now, build export adapters later

MetaForge’s internal graph schema remains the source of truth. We do not adopt any external standard as our internal model. Instead, we ensure our schema properties align with key standards so that export adapters are trivial to build when needed.

Actions — Now (Phase 1)

1. Add globalAssetId to key graph nodes

Every asset that may need to be referenced externally gets a globally unique, resolvable identifier.

Property definition:

This is an optional property on each node. It does not affect existing functionality.

2. Add supplier to BOMItem

Distinct from manufacturer — a component has one manufacturer but may have multiple suppliers.

3. Document AAS-aligned keys in specification maps

The existing BOMItem.specifications and DesignElement.parameters maps are flexible enough to carry AAS-required data. Document the expected keys:

BOMItem.specifications — recommended keys:

DesignElement.parameters — recommended keys:

These are conventions, not schema constraints. Agents and IDE Assistants should populate these keys when data is available.

4. Add format and schemaVersion to conversion pipeline metadata

The STEP-to-GLB conversion metadata output (MET-151) must include versioning:

{
  "format": "metaforge-twin-export",
  "schemaVersion": "1.0",
  "sourceFormat": "STEP-AP242",
  "parts": [...]
}

This enables future consumers (AAS export, USD export) to parse metadata reliably.

Actions — Phase 3+

Standards Not Adopted

Architecture

How AAS Export Will Work (Phase 3+)

flowchart LR
    GRAPH["Neo4j\nArtifact Graph"] --> QUERY["Cypher Query\nSubset Selection"]
    QUERY --> MAP["AAS Mapper\ngraph → submodels"]
    MAP --> PACK["AASX Packager\nJSON + files"]
    PACK --> OUT["AASX File\nor AAS REST API"]

The AAS export adapter is a read-only projection of the graph — consistent with the architectural principle that all surfaces are projections of Digital Twin state.

Graph Schema Changes

graph TD
    subgraph "Phase 1 Changes"
        A["BOMItem\n+ globalAssetId\n+ supplier\n+ specifications keys"]
        B["DeviceInstance\n+ globalAssetId"]
        C["TwinModel\n+ globalAssetId"]
        D["Conversion Metadata\n+ format\n+ schemaVersion"]
    end

    subgraph "Phase 3+ Additions"
        E["AAS Export Adapter"]
        F["AAS REST API"]
        G["SysML v2 Adapter"]
    end

    A --> E
    B --> E
    C --> E
    E --> F

Consequences

Positive

• Future-proofed for European market — AAS alignment is a sales differentiator with minimal upfront cost
• No schema disruption — changes are additive optional properties, not structural changes
• No vendor lock-in — internal model remains MetaForge-native; standards are export formats only
• Low effort now — 3 optional properties + documentation of map keys

Negative

• Slight schema complexity — globalAssetId is another property to populate (but it’s optional)
• Convention enforcement — recommended specifications keys rely on agents/users to populate correctly

Risks and Mitigations

Related Documents