Skip to main content

Nodes and Node Relationships

In the DSM, a node is the atomic unit of personal data. Nodes are connected to each other through relationships, forming a graph that represents a user's complete data profile.

What is a node?​

A node represents a discrete piece of profile data owned by a user — an identity document, an address, a qualification, a medical record, or any other structured information. Nodes are deliberately generic: each one stores its data as a JSON object and classifies itself using a set of labels (such as passport, address, or person).

This design means the same node structure can represent any type of personal data, without requiring a separate table or schema for each data type.

Key characteristics​

  • User-owned — every node belongs to exactly one user and is isolated to a single tenant
  • Schema-driven — the structure of a node's data is defined by a JSON schema, ensuring consistency
  • Label-indexed — labels enable efficient queries like "find all nodes with label passport" without scanning the full dataset

Temporary nodes​

Nodes can be staged in a temporary holding area before they become part of a user's permanent profile. This supports workflows where data needs to be reviewed or processed before inclusion — for example, when identity documents are being verified.

What are node relationships?​

A node relationship is a directed edge between two entities. It creates a typed connection — such as belongs_to, verified_by, or lives_at — that captures how pieces of data relate to each other.

Dual target design​

A relationship can point to either:

  • Another node — for example, linking a passport node to a person node
  • A sharing instance — for example, linking a node to the sharing event that created or received it

This flexibility allows the graph to capture both internal data relationships (how a user's own data fits together) and external data flows (how data was shared with others).

Relationship integrity​

Creating a relationship requires appropriate permissions on both the source and target. A user cannot create links to nodes they cannot see, preventing phantom connections in the graph.

How nodes form a profile graph​

Together, nodes and relationships create a directed graph for each user:

This graph is the foundation for data sharing — when a user shares data through an access application, they select specific nodes from their profile. The relationships between those nodes provide context about how the data fits together.

Visibility model​

Nodes use a three-tier visibility model:

  1. Owner access — the user who owns the node always has full access
  2. Granted permissions — other users can be granted viewer, editor, or admin access, either directly or through a permission group
  3. Administrative access — administrative users with the appropriate table-level permissions can see all nodes within their tenant

When a node is created, the system automatically records an ownership tuple that grants the creator full access. Additional permissions can be layered on top as needed.

Client-side encryption and visibility​

When a node's data is encrypted client-side (before being stored or transmitted), administrative users with table-level permissions will only see the encrypted data. They cannot decrypt this data — that capability resides exclusively with the user who holds the encryption key. This means administrators have visibility over the existence and metadata of encrypted nodes, but not their contents.