Data Modelling with the Project Model
Define entities, properties, relationships, and key roles in the central data model (model.neoarc). Create ERD views and graph views to visualise the model for different audiences and database platforms.
Data modelling in NeoArc Studio centres on the project model (model.neoarc), a single file that defines all entities, properties, relationships, and constraints. The model uses the GraphDocument format with isProjectModel: true and authoringMode: "graph-db". All structural editing happens in the model editor; views are read-only representations that derive their data from this single source of truth.
The Central Model
The model file lives at the project workspace root, configured in project.neoarc via modelConfig.modelFilePath (defaults to model.neoarc). It stores entities as graph nodes and relationships as graph edges.
Entity Properties
Each entity node contains an array of properties. Properties use abstract types that are database-agnostic; concrete types are resolved at view time via database profiles.
| Field | Description |
|---|---|
| name | Property name (e.g. firstName, orderId) |
| type | Abstract type: string, integer, float, decimal, boolean, date, datetime, uuid, json, text, binary, enum |
| keyRole | Key semantics: primary, foreign, natural, surrogate, composite-part, none |
| required | Whether the property is required |
| nullable | Whether null values are permitted |
| unique | Unique constraint |
| indexed | Whether the property is indexed |
| defaultValue | Default value expression |
| maxLength / minLength | String length constraints |
| maxValue / minValue | Numeric range constraints |
| pattern | Regular expression validation pattern |
| enumValues | Allowed values for enum types |
| description | Documentation for the property |
| fkResolution | Foreign key target: targetNodeId, targetPropertyName, showEdge |
| governance | Classification, retention policy, compliance notes, encryption, access restriction |
| projections | Persistence, search, API, and custom projection configurations |
Key Roles
Key roles express the identity semantics of a property. They are intrinsic to the field, not inferred from relationships.
| Role | Indicator | Description |
|---|---|---|
| primary | PK | Canonical identifier for the entity |
| foreign | FK | References another entity's key (resolved via fkResolution) |
| natural | NK | Business-meaningful identifier (e.g. email, tax number) |
| surrogate | SK | System-generated identifier (e.g. UUID, auto-increment) |
| composite-part | CP | Participates in a composite key |
| none | (none) | No key role (default) |
Abstract Types
The model uses 12 abstract types. These map to concrete database types via database profiles and to search index types via search profiles.
| Abstract Type | Description |
|---|---|
| string | Variable-length character data |
| integer | Whole number |
| float | Floating-point number |
| decimal | Fixed-precision decimal number |
| boolean | True/false value |
| date | Date without time |
| datetime | Date with time |
| uuid | Universally unique identifier |
| json | Structured JSON data |
| text | Large/unbounded text |
| binary | Binary data |
| enum | Enumerated set of allowed values |
Creating Views from the Model
The model supports three types of read-only views. Each view references the model via modelFilePath and selects which entities to include via includedEntityIds.
| View Type | File Extension | Layout | Profile Type | Use Case |
|---|---|---|---|---|
| ERD View | .erd-view.json | Tabular (entity tables with columns) | Database profile | Physical/logical data models for specific database vendors |
| Graph View | .graph-view.json | Force-directed (circles and edges) | Database profile | Conceptual/domain models, graph database schemas |
| Search View | .search-view.json | Tabular (search index fields) | Search profile | Search index configurations for Azure AI Search, Elasticsearch, etc. |
Conceptual, Logical, and Physical Distinction
The conceptual/logical/physical distinction is achieved through view configuration and database profile selection, not separate model files.
Validation
The model editor validates entities against 18 rules grouped into three categories.
| Category | Rules | Description |
|---|---|---|
| Structural | Always enforced | Invalid references, corrupt identifiers |
| Semantic | graph-db mode | Unnamed relationships, missing properties |
| Domain | graph-db mode | Missing primary keys, orphan nodes, circular dependencies, naming conventions |