Entities and Properties
Define entities as graph nodes with typed properties, constraints, key roles, foreign key resolution, and derivation modes.
Entities are the fundamental building blocks of the data model. Each entity is a node in the graph, representing a distinct concept such as a customer, order, or product. Entities carry typed properties that describe their attributes, along with constraints and key roles that define identity and referential integrity.
Entity Structure
Every entity node in the model has the following core fields.
| Field | Type | Description |
|---|---|---|
| id | string | Unique identifier (UUID) for the entity |
| label | string | Display name shown inside the node circle |
| labels | string[] | Optional additional schema labels for graph DB design (e.g., ["Person", "Employee"]) |
| nodeType | string | Discriminator: "entity" (default) or "projection" |
| x, y | number | Canvas position coordinates (optional, calculated by force simulation if unset) |
| isPinned | boolean | Whether the node has a fixed position, exempt from force simulation |
| color | string | Stroke/outline colour (CSS colour value, defaults to theme colour) |
| properties | GraphNodeProperty[] | Typed attributes for this entity |
| tags | string[] | Labels for filtering and organisation |
Property Structure
Each property on an entity is a GraphNodeProperty with the following fields.
| Field | Type | Description |
|---|---|---|
| name | string | Property identifier (e.g., "customerId", "email") |
| type | string | Abstract type from the type system |
| description | string | Documentation for this property |
| required | boolean | Whether the property must have a value |
| nullable | boolean | Whether null is an acceptable value |
| unique | boolean | Uniqueness constraint |
| indexed | boolean | Whether the property should be indexed |
| defaultValue | string | Default value expression |
| keyRole | PropertyKeyRole | Key semantics: none, primary, natural, surrogate, composite-part, or foreign |
| fkResolution | ForeignKeyResolution | Target entity and property for foreign key resolution |
| derivationMode | string | How the value is obtained: stored, derived, or computed-on-read |
| derivationPaths | string[] | Dot-grammar source paths for derived properties |
Abstract Types
Properties use abstract types that are database-agnostic. Each abstract type maps to concrete types via database profiles.
| Type | Description | Typical Use |
|---|---|---|
| string | Variable-length text | Names, codes, short identifiers |
| integer | Whole numbers | Counts, quantities, sequence numbers |
| float | Floating-point numbers | Measurements, percentages, ratios |
| decimal | Fixed-precision numbers | Currency, financial calculations |
| boolean | True or false | Flags, toggles, status indicators |
| date | Calendar date without time | Birthdates, effective dates |
| datetime | Date with time component | Timestamps, audit trails, event logs |
| uuid | Universally unique identifier | Primary keys, correlation IDs |
| json | Structured JSON data | Configuration blobs, metadata |
| text | Long-form text content | Descriptions, notes, rich content |
| binary | Raw binary data | File attachments, images, certificates |
| enum | Enumerated value set | Statuses, categories, fixed option lists |
Key Roles
Each property has a key role that defines its identity semantics. Key roles are intrinsic to the property and are not inferred from relationships.
| Key Role | Abbreviation | Description |
|---|---|---|
| none | - | No key role (default for most properties) |
| primary | PK | Canonical identifier for the entity |
| natural | NK | Business-meaningful identifier (e.g., email, ISBN, tax number) |
| surrogate | SK | System-generated identifier (e.g., auto-increment, UUID) |
| composite-part | CP | Participates in a composite key alongside other CP properties |
| foreign | FK | References another entity's key, optionally resolved to a specific target |
Foreign Key Resolution
When a property has the foreign key role, it optionally links to a target entity and property. Resolution is explicit and user-initiated, never inferred automatically. A foreign key property exists in two states: marker-only (no resolution) or resolved (linked to a target).
interface ForeignKeyResolution {
/** The node (entity) this FK references */
targetNodeId: string;
/** Specific property on the target node (optional) */
targetPropertyName?: string;
/** Whether to create/show an edge for this resolution */
showEdge?: boolean;
}Advanced Validation Constraints
Beyond the basic required, nullable, unique, and indexed flags, properties support fine-grained validation.
| Constraint | Applicable Types | Description |
|---|---|---|
| minValue | integer, float, decimal | Minimum numeric value |
| maxValue | integer, float, decimal | Maximum numeric value |
| minLength | string, text | Minimum character length |
| maxLength | string, text | Maximum character length |
| pattern | string | Regex validation pattern |
| enumValues | enum | Array of allowed string values |
Property Derivation Modes
Properties specify how their values are obtained, which affects storage and computation behaviour.
Governance and Projections
Properties optionally carry governance metadata and projection configurations that control how data appears across different layers of the architecture.