Data Model
The central model file is the single source of truth for every entity, relationship, and property in a NeoArc project. Abstract database-agnostic types, key roles, per-property projections for persistence, search, and API, governance classifications (PII, confidential, retention policies), shared property sets with live inheritance, comprehensive validation rules, and import/export across a wide range of formats.
The data model (model.neoarc) is the foundation of everything in NeoArc Studio. Every entity, relationship, and property is defined here. API schemas, database DDL, search index mappings, ERD diagrams, graph views, governance documentation, all of these are projections of this single file. When you change the model, every downstream artefact reflects the change. When you break a contract, the validation engine tells you immediately. The model is the single source of truth that makes model-first architecture possible.
The model uses database-agnostic abstract types that map to any vendor via profiles. Each property carries three independent projection configurations (persistence, search, API), governance metadata (data classification, encryption, retention), and validation constraints. Shared property sets provide live inheritance for common patterns. Validation rules check for errors at design time.
Key Capabilities
Model Structure
The model organises data around a small set of core concepts.
| Concept | Description |
|---|---|
| Entity (Node) | A named data object with properties, key roles, and governance metadata. Rendered as a node in the graph. |
| Relationship (Edge) | A labelled connection between two entities, with optional source and target labels for cardinality. |
| Property | A typed field on an entity: name, abstract type, key role, validation constraints, projections, governance, and derivation mode. |
| Group | A logical subdomain grouping entities together. Rendered as a convex hull boundary with colour coding. |
| Composite Constraint | A multi-property constraint (e.g. composite unique keys) applied across properties on the same entity. |
| Foreign Key Resolution | Links a foreign key property to its target entity and target property, generating visual edges in the model. |
Property System
Abstract Types
Properties use database-agnostic abstract types. Database profiles map each abstract type to a concrete type for a specific vendor (e.g. string maps to NVARCHAR in SQL Server, TEXT in PostgreSQL). Parameterised templates such as NVARCHAR({maxLength}) use property constraints to produce the final DDL type.
| Abstract Type | Category | Typical Use |
|---|---|---|
| string | Text | Short text values, identifiers, codes |
| text | Text | Long-form content, descriptions, notes |
| integer | Numeric | Whole numbers, counts, quantities |
| float | Numeric | Floating-point values, measurements |
| decimal | Numeric | Precise values, monetary amounts |
| boolean | Logic | True/false flags, feature toggles |
| date | Temporal | Calendar dates without time |
| datetime | Temporal | Timestamps with date and time |
| uuid | Identity | Universally unique identifiers |
| json | Structured | Arbitrary JSON payloads |
| binary | Binary | Binary data, file contents |
| enum | Enumeration | Fixed set of allowed values |
Key Roles
Every property has a key role that describes its function in the entity's identity and relationships.
| Role | Badge | Description |
|---|---|---|
| none | - | No key significance. The default for ordinary data fields. |
| primary | PK | The primary identifier for the entity. Validation warns if an entity has zero or more than one primary key. |
| natural | NK | A business-meaningful unique identifier (e.g. email address, SKU code). |
| surrogate | SK | A system-generated unique identifier with no business meaning. |
| composite-part | CK | One field in a multi-field composite key, defined via composite constraints. |
| foreign | FK | References a key property on another entity. Requires foreign key resolution to specify the target entity and property. |
Derivation Modes
Properties support three derivation modes that indicate how values are produced.
| Mode | Description |
|---|---|
| stored | Value is persisted directly in the data store. This is the default. |
| derived | Value is calculated from other properties during write or ETL processes. |
| computed-on-read | Value is computed at query time, not stored. Useful for aggregations and calculated fields. |
Projections
Each property carries per-channel projections that control how it appears in different output targets. The property table editor offers four lens modes: schema (the base definition), persistence, search, and API.
Governance
Validation
The model editor runs validation rules across three categories. Rules are mode-aware: structural rules always apply, semantic rules apply in conceptual and graph-db modes, and domain rules apply only in graph-db mode.
Data Views
Data Views are interactive, model-derived visualisations that display entities as nodes on a force-directed graph canvas with edges inferred from relationships. Click any node to open the Entity Overlay with the full property table. Two view modes target different concerns.
Groups and Subdomains
Entities are organised into groups that represent logical subdomains. Each group has a name, a colour, and a list of member entities. The editor renders groups as convex hull boundaries around their members, with group-aware physics in the force simulation to keep related entities together. The entity picker supports group filtering to narrow selection when working with large models (the 50-entity cap per view makes this essential for navigation).
Entity Lifecycle Management
The model supports lifecycle tagging on every entity. Each entity carries a status of active, planned, or deprecated. When an entity is deprecated, it can be linked to its replacement via a replaced-by edge (the reverse evolved-from edge is created automatically). The repoint wizard migrates downstream references from deprecated entities to their replacements. Deprecation impact reports show remaining reference counts, and the safe-to-delete report confirms when deprecated entities can be removed.
Import and Export
The data model supports importing entities from a wide range of external file formats and exporting to numerous schema and DDL formats.
Getting Started
Begin by creating a project in NeoArc Studio, which generates the model.neoarc file automatically. Add entities manually, or import them from existing SQL DDL, diagram files, or other schema formats. Define properties with abstract types and key roles, then create views to visualise specific subsets of the model.
Define data structures with field types covering strings, numbers, booleans, objects, arrays and more, type specialisations for fine-grained modelling, and validation rules covering type safety, cardinality, referential integrity and cross-field constraints. Create reusable schemas that stay synchronised across your documentation.
Create interactive force-directed graph diagrams in three authoring modes: mindmap, conceptual, and graph-db. Graph-db mode adds typed properties with 12 abstract types, 6 key roles, per-property projections, composite constraints, and Cypher DDL export. Includes 18-rule validation, version snapshots, architecture transitions, group and tag filtering, and search. Graph-db mode also serves as the editing canvas for the project model (model.neoarc).
Create named version snapshots, manage entity lifecycles with active, planned, and deprecated states, and track architectural evolution across diagrams, graph diagrams, and documentation pages.