Getting started

On this page

Install
Create your first model
The workspace
Draw object types and fact types
Add constraints
Check the verbalization
Generate a database schema
Import an existing NORMA model

Install

Install Factum — Object-Role Modeling (ORM 2) from the Visual Studio Marketplace, or from the Extensions view (Ctrl/Cmd + Shift + X) by searching for Factum ORM.

To install a build yourself:

code --install-extension factum-orm-0.1.0.vsix

There are no external dependencies — no database, no Java, no NORMA installation.

Create your first model

Run ORM: New ORM Model from the Command Palette (Ctrl/Cmd + Shift + P) and choose where to save it. Models are saved as *.orm.json.
The diagram opens with a small starter schema — Person, Company, Skill and a subtype — so you have something to take apart rather than a blank canvas.
Open an existing model any time by clicking a .orm.json file. To see the text behind the picture, run ORM: Open Model Source (JSON).

The workspace

The editor has three parts:

The toolbar — drawing tools on the left, constraint buttons in the middle (they act on the roles you have selected), view and export actions on the right.
The canvas — your diagram. Drag to move shapes, drag empty space to marquee-select, scroll to zoom, press F to fit.
The side panel — Properties, Verbalization, Relational, Graph and Problems.

Draw object types and fact types

Press a tool key, then click the canvas:

Key	Adds	Notation
`E`	Entity type	Solid rounded rectangle
`T`	Value type	Dashed rounded rectangle
`1` `2` `3`	Unary, binary or ternary fact type	A strip of role boxes
`S`	Subtype link	Arrow from subtype to supertype
`C`	Connect a role to an object type	Drag from a role box to a shape

Naming. Double-click an object type to rename it in place. Typing Person(.nr) sets the name and the reference mode in one go — the shape then reads Person with (.nr) underneath, meaning each Person is identified by a person number.

Readings. Double-click a fact type to edit its reading. Readings use {0} and {1} placeholders for the role players, so {0} works for {1} verbalizes as Person works for Company. Add a second, reverse reading ({0} employs {1}) in the Properties tab and the verbalizer will use whichever direction reads better.

A new fact type arrives with a uniqueness constraint already on it — the pattern most models start from. Adjust it rather than starting from nothing.

Add constraints

Constraints apply to roles, so select role boxes first: click one, then Shift-click to add more. The constraint buttons light up as soon as a selection makes them possible.

Button	Constraint	Says
U	Uniqueness	Each player of these roles appears at most once
P	Preferred identifier	This uniqueness constraint identifies the object type
●	Mandatory	Every instance plays this role
n	Frequency	Players appear a bounded number of times
↺	Ring	Irreflexive, acyclic, symmetric … over two roles of one type
⊆ ✕ =	Subset, exclusion, equality	Compare role sequences across two fact types

Select the constraint itself to tune it in the Properties tab — frequency bounds, ring types, or switching a constraint from alethic (cannot be violated) to deontic (should not be).

Check the verbalization

Open the Verbalization tab as you draw. This is the step that makes ORM worth the effort: the sentences are generated from the constraints, so if they say something you did not mean, the model is wrong — not the wording.

Each Person works for exactly one Company.

Remove the mandatory dot and the same fact type reads:

Each Person works for at most one Company.

Click any sentence to select the element it describes.

Generate a database schema

The Relational and Graph tabs show both mappings live, each with a copy button. To open a full script in its own editor:

ORM: Generate Relational Schema (SQL DDL) — set the dialect with orm.ddl.dialect.
ORM: Generate Property Graph Schema (LadybugDB) — Cypher DDL.

If the model still has errors you will be asked whether to generate anyway; the output is honest about what it could not map. See Mapping rules for the details.

Import an existing NORMA model

Right-click a .orm file in the Explorer and choose Import NORMA (.orm) File, or run the command and pick the file. Factum reads the objects, fact types, readings, constraints, subtypes, value restrictions and the diagram geometry, then writes an .orm.json beside the original and opens it.

The original file is never modified. Anything the importer could not read is reported so you know what to check.