Commons Reference

The platform ships with a set of built-in classes in the commons namespace. These are always available to all tenants. Your custom classes can inherit from them or extend them.

Alongside commons, the platform also ships a test namespace — a small always-available data model used as the starting point for a tenant created without a linked Git repository. See Test namespace below.

Inheritance tree

commons.item (ABSTRACT)
├── commons.entity (ABSTRACT)
│   ├── commons.person (BASIC)
│   │   └── commons.employee (ABSTRACT)
│   ├── commons.company (BASIC)
│   │   ├── commons.groupCompany (ABSTRACT)
│   │   └── commons.supplier (ABSTRACT)
│   ├── commons.customer (ABSTRACT)
│   └── commons.emailAccount (ABSTRACT)
│       ├── commons.emailSender (ABSTRACT)
│       ├── commons.emailReceiver (ABSTRACT)
│       └── commons.emailCcReceiver (ABSTRACT)
├── commons.dossier (ABSTRACT)
│   └── commons.agreement (ABSTRACT)
├── commons.content (ABSTRACT)
│   ├── commons.document (BASIC)
│   ├── commons.memo (BASIC)
│   ├── commons.task (BASIC)
│   ├── commons.reminder (BASIC)
│   ├── commons.emailMessage (BASIC)
│   └── commons.invoice (BASIC)
├── commons.invoiceLine (BASIC)
├── commons.territory (ABSTRACT)
│   ├── commons.country (BASIC)
│   ├── commons.region (BASIC)
│   └── commons.state (BASIC)
├── commons.intake (ABSTRACT)
└── commons.aiTask (BASIC)

commons.registerCompany (EXTENSION → commons.company)

Why use commons classes

Build on commons classes wherever possible, rather than creating entirely custom class hierarchies. The platform and the web application recognize commons types and treat them accordingly:

• Specialized UI — commons.document objects are rendered with a document viewer and file management UI. commons.memo objects get a rich-text editor. Using these classes gives you that behaviour for free; a generic custom class does not.
• Platform modules — certain features are activated automatically based on type. For example, a company verification module can look up and validate commons.company objects against external registries such as the Dutch KvK. This integration only works because the platform knows the object is a company.
• Interoperability — relations, scripts, and views across the platform use commons types as shared vocabulary. A relation typed to commons.entity accepts both persons and companies without any extra configuration.
• Archetypes — several commons classes bind archetypes (commons.document, commons.task/commons.reminder, the email family, commons.invoice/commons.invoiceLine), so AI/MCP consumers and gateways can reason about them generically.

When a commons class does not cover all the fields you need, extend it with an EXTENSION class or inherit from it with a custom ABSTRACT or BASIC class — rather than bypassing it entirely.

---

The name field

Every class inherits the name field (TEXT, required) from commons.item. It is the primary display identifier used throughout the platform: in list views, relation pickers, page titles, and search results.

name is almost always computed via a formula — it is rarely entered manually by users. Define a formula that produces a meaningful human-readable label for each object:

"formulas": [
  { "valueType": "name", "template": "{{firstName}} {{lastName}}" }
]

Common patterns:

Object type	Recommended formula
Person / contact	{{firstName}} {{lastName}}
Memo, task, ticket	{{title}} or {{subject}}
Agreement, dossier	Based on related parties or a descriptive field
Document, invoice	Generated reference number via identifier(), or based on related parties

name is not unique. Multiple objects can have the same name. If you need a unique identifier (e.g. an invoice number), generate it in a separate field using the identifier() formula function and store it there — do not rely on name for uniqueness.

The label of name can be overridden per class in translations. A ticket class might display it as "Ticket reference", a document as "Title". See Translations.

---

Core classes

commons.item

Type: ABSTRACT | Inherits: — (root)

The root of the entire class hierarchy. Every class eventually inherits from commons.item.

Value types:

Field	Type	Required	Description
name	TEXT	yes	Display name of the object. Typically computed by a formula.

---

commons.entity

Type: ABSTRACT | Inherits: commons.item

Base class for persons and companies — anything that can be a party in a legal or business relationship.

No additional value types beyond commons.item.

---

commons.person

Type: BASIC | Inherits: commons.entity

Represents a natural person.

Value types:

Field	Type	Required	Description
firstName	TEXT	no	First name
lastName	TEXT	yes	Last name
emailAddress	EMAIL	no	Email address
birthdate	DATE	no	Date of birth (disabled by default)

Formulas:

• name = {{firstName}} {{lastName}}

Scripts:

• invite (consumerGateway, MANUAL) — sends a user invitation via email

---

commons.employee

Type: ABSTRACT | Inherits: commons.person

An abstract class added to a person when they are linked as an employee on an employment agreement.

---

commons.company

Type: BASIC | Inherits: commons.entity

Represents a legal entity or organization.

No additional value types beyond commons.entity.

---

commons.groupCompany

Type: ABSTRACT | Inherits: commons.company

An abstract class used to mark a company as the internal group company (the "our side") in agreements.

---

commons.supplier

Type: ABSTRACT | Inherits: commons.company

An abstract class used to mark a company as the issuing party on an invoice. Used as the (optional) supplier relation type on commons.invoice.

---

commons.customer

Type: ABSTRACT | Inherits: commons.entity

An abstract class used to mark an entity as the billed party on an invoice. Used as the (required) customer relation type on commons.invoice.

---

commons.emailAccount

Type: ABSTRACT | Inherits: commons.entity

Base class for anything that can send or receive email. Binds the commons.emailAddress archetype.

Value types:

Field	Type	Required	Description
emailAddress	EMAIL	no	Unique email address
emailAliases	EMAIL (multiple)	no	Additional addresses that also resolve to this account

Not used directly — always specialized via commons.emailSender, commons.emailReceiver, or commons.emailCcReceiver below.

---

commons.emailSender / commons.emailReceiver / commons.emailCcReceiver

Type: ABSTRACT | Inherits: commons.emailAccount

Role markers with no additional fields. An entity (typically commons.person or commons.company) gains one of these classes when it is linked as the sender, a to recipient, or a cc recipient on a commons.emailMessage — see How relations add classes.

---

commons.dossier

Type: ABSTRACT | Inherits: commons.item

Base class for all dossier types. A dossier has an active period.

Value types:

Field	Type	Required	Description
activeDate	DATE	no	Start date (labeled "start date")
inactiveDate	DATE	no	End date (labeled "end date")

---

commons.agreement

Type: ABSTRACT | Inherits: commons.dossier

Base class for agreements and contracts. No additional value types beyond commons.dossier.

No BASIC agreement class ships directly in commons — inherit from it in your own model, or see test.employmentAgreement / test.generalAgreement in the test namespace for worked examples.

---

commons.content

Type: ABSTRACT | Inherits: commons.item

Base class for content items — objects that belong to a dossier. Documents, memos, tasks, reminders, email messages, and invoices all inherit from this class.

Relations:

Relation	Type	Required	Multiple
Dossier	commons.dossier	yes	no

---

commons.document

Type: BASIC | Inherits: commons.content

A file attachment. Documents are linked to a dossier via the inherited commons.dossier relation. Binds the commons.document archetype.

Value types:

Field	Type	Required	Description
file	FILE	yes	The uploaded file
date	DATE	no	Date on the document
documentNumber	TEXT	no	Auto-generated document number
abstract	TEXTBLOCK	no	AI-generated summary
content	TEXTBLOCK	no	Extracted text content (hidden)
folder	TEXT	no	Subpath used for folder-style grouping under the dossier

Formulas:

• documentNumber = DOC{{identifier('documentNumber')}}

Scripts:

• summarize (functionGateway, triggered on file update) — extracts a short summary and document date from the file using Gemini

---

commons.memo

Type: BASIC | Inherits: commons.content

A free-text note linked to a dossier.

Value types:

Field	Type	Required	Description
title	TEXT	yes	Memo title
memo	TEXTBLOCK	yes	Memo body

Formulas:

• name = {{title}}

Relations: (inherited from commons.content)

Relation	Type	Required
Dossier	commons.dossier	yes

---

commons.task

Type: BASIC | Inherits: commons.content

A task or action item linked to a dossier. Binds the commons.event archetype (when → dueDate).

Value types:

Field	Type	Required	Description
title	TEXT	yes	Task title
dueDate	DATE	no	Due date

Formulas:

• name = {{title}}

Relations: (inherited from commons.content)

Relation	Type	Required	Multiple	Description
Dossier	commons.dossier	yes	no	Inherited from commons.content

---

commons.reminder

Type: BASIC | Inherits: commons.content

A dated reminder linked to a dossier. Binds the commons.event archetype (when → date), the same archetype as commons.task.

Value types:

Field	Type	Required	Description
title	TEXT	yes	Reminder title
date	DATE	no	Reminder date

Formulas:

• name = {{title}}

---

commons.emailMessage

Type: BASIC | Inherits: commons.content

Records an inbound or outbound email, linked to the sending and receiving persons or companies. Binds the commons.email archetype.

Value types:

Field	Type	Required	Description
subject	TEXT	yes	Email subject
date	DATETIME	yes	Sent/received timestamp
bodyHtml	TEXTBLOCK	no	HTML body
bodyText	LONGTEXT	no	Plain-text body
headers	LONGTEXT	no	Raw headers (hidden)
attachments	FILE (multiple)	no	Attached files

Relations:

Relation	Type	Required	Multiple
Sender	commons.emailSender	yes	no
Receivers	commons.emailReceiver	yes	yes
Cc receivers	commons.emailCcReceiver	no	yes
Dossier	commons.dossier	no	no

Formulas:

• name = {{subject}}

---

commons.invoice

Type: BASIC | Inherits: commons.content

An invoice linked to a customer and an optional supplier, with line items via the reverse commons.invoiceLine relation. Binds the commons.invoice archetype.

Value types:

Field	Type	Required	Description
invoiceNumber	TEXT	yes	Invoice reference
invoiceDate	DATE	yes	Invoice date
dueDate	DATE	no	Payment due date
netAmount	CURRENCY	no	Sum of line amounts (formula)
taxAmount	CURRENCY	no	Tax amount
amount	CURRENCY	no	netAmount + taxAmount (formula)
status	LIST (commons.invoiceStatus)	no	DRAFT / SENT / PAID / OVERDUE / CANCELLED
attachments	FILE (multiple)	no	Supporting files

Relations:

Relation	Type	Required	Multiple
Customer	commons.customer	yes	no
Supplier	commons.supplier	no	no

Formulas:

• name = {{supplier.name}} ({{invoiceDate}})
• netAmount = sum(invoiceLines.amount)
• amount = netAmount + taxAmount

The default and relation views use navigateBehaviour: OVERLAY_PAGE, so rows open as an overlay rather than a full page navigation — see Navigate behaviour.

---

commons.invoiceLine

Type: BASIC | Inherits: commons.item

A single line item on an invoice. Binds the commons.invoiceLine archetype.

Value types:

Field	Type	Required	Description
description	TEXT	yes	Line description
quantity	DECIMAL	yes	Quantity
unitPrice	CURRENCY	yes	Price per unit
amount	CURRENCY	no	unitPrice * quantity, rounded (formula)

Relations:

Relation	Type	Required	Multiple
Invoice	commons.invoice	yes	no

Formulas:

• name = {{description}}
• amount = round(unitPrice * quantity, 2)

---

commons.territory

Type: ABSTRACT | Inherits: commons.item

Base class for geographic entities such as countries, states, and regions. No additional value types beyond commons.item.

A territory hierarchy (superTerritory) is available in the test namespace as test.territoryHierarchy / test.superTerritory, not directly in commons.

---

commons.country

Type: BASIC | Inherits: commons.territory

Represents a country. Comes with built-in default data for a set of common countries.

Value types:

Field	Type	Required	Description
countryCode	TEXT	no	ISO country code (e.g. NL, DE)

Default data: NL, DE, BE, FR, ES, IT, GB, LU, US, CA — loaded via POST /data/{tenantId}/loadDefaultData.

---

commons.region

Type: BASIC | Inherits: commons.territory

Represents a geographic region within a country or territory. No additional value types beyond commons.territory.

---

commons.state

Type: BASIC | Inherits: commons.territory

Represents a state or province within a country.

Value types:

Field	Type	Required	Description
stateCode	TEXT	no	State/province code

---

commons.registerCompany

Type: EXTENSION | Extends: commons.company

Adds company-register enrichment fields to every commons.company — legal name, registration number, addresses, and verification metadata — plus the scripts to look up and refresh that data from an external register (e.g. the Dutch KvK).

Key value types:

Field	Type	Description
registrationNumber	TEXT	Register identifier (e.g. KvK number)
legalName	TEXT (required, history-enabled)	Officially registered name
reportingName	TEXT	Preferred display name, falls back to legalName
registrationDate / startDate / endDate	DATE	Register lifecycle dates
visitAddress* / mailingAddress*	TEXT	Visiting and mailing address fields
active / bankrupt / verified	BOOLEAN	Register status flags
verificationDate	DATETIME	Last time the register data was refreshed

Relations:

Relation	Type	Required	Multiple
Country	commons.country	no	no

Formulas:

• name = ifNull(reportingName, legalName)

Scripts:

• CompanySearch (producerGateway, GENERAL) — searches the external company register
• CompanyRegister (functionGateway, triggered on registrationNumber change or manually) — fetches and overwrites the register fields above

See Function Gateways and the company-register validation case for how these scripts fit into the archetype design.

---

commons.intake and commons.aiTask

Type: ABSTRACT (commons.intake) / BASIC (commons.aiTask) | Inherits: commons.item

Drive the AI document-intake pipeline: commons.intake tracks a source file through markdown conversion and downstream extraction phases, and commons.aiTask records each parallel Gemini call made against it. Fully documented in Pipelines — not repeated here.

---

Extending commons classes

You can add fields to any commons class using an EXTENSION class:

{
  "class": "my-project.person",
  "type": "EXTENSION",
  "extends": "commons.person",
  "valueTypes": [
    { "name": "taxNumber" },
    { "name": "nationality" }
  ]
}

This adds taxNumber and nationality to every commons.person in the tenant. commons.registerCompany (above) is a real built-in example of the same pattern, extending commons.company.

---

Test namespace

Alongside commons and system, the platform ships a test namespace: a small, always-loadable data model used as the starting point when a tenant is created without a linked Git repository. Like commons, it loads from the platform itself — no repository configuration required.

test.demoConfig is the entry point (a type: NONE class, equivalent to an index.json): it imports a small base model and offers a set of opt-in modules.

Base model (always loaded)

Class	Type	Inherits	Notes
test.item	EXTENSION	commons.item	Adds an optional, multiple test.tag relation to every object (gated behind the Tags module).
test.tag	BASIC	commons.item	A free-form tag (tag, required, unique).
test.note	BASIC	commons.item	A note on a commons.company (required, cascade delete) with an optional commons.person and territory relation; triggers test.noteLog entries on create/update/delete.
test.noteLog	BASIC	commons.item	Append-only log of test.note changes (trigger, note).

Optional modules

Module	Imports	Description
Tags	test.item	Adds a free-form tag relation to every object in the model.
General Agreements	test.generalAgreement	Agreements between a group company and a counterparty.
Tax & Finance	test.taxDossier	Tax and finance dossiers.
HRM	test.employmentAgreement	Employment agreements, personnel files, and related HR data.
General Dossiers	test.generalDossier	General-purpose dossiers for companies and persons.
Company Registers	commons.registerCompany	Automatically update company information from external registers.
Countries	commons.country, commons.state, commons.region, test.superTerritory, test.territoryHierarchy	Countries, states, regions, and the territory hierarchy.
Email	commons.emailMessage	Inbound/outbound email messages, linked to sending and receiving persons or companies.
Invoice	commons.invoice, commons.invoiceLine	Invoices with line items, linked to a customer and an optional supplier.

Module classes

Class	Type	Inherits	Notes
test.counterparty	ABSTRACT	commons.entity	Marks an entity as the external party in a general agreement.
test.generalAgreement	BASIC	commons.agreement	Between a commons.groupCompany and a test.counterparty.
test.generalDossier	BASIC	commons.dossier	Linked to any commons.entity.
test.taxAndFinance	ABSTRACT	commons.dossier	Linked to any commons.entity.
test.taxDossier	BASIC	test.taxAndFinance	Adds taxType and a required relation to test.taxPeriod.
test.taxPeriod	BASIC	commons.item	Standalone tax period, not tied to the dossier hierarchy.
test.employmentAgreement	BASIC	commons.agreement	Between a commons.company and a commons.employee; includes an AI-assisted complete script that extracts job title and start date from attached documents.
test.superTerritory	ABSTRACT	commons.territory	Marker for large geographic groupings (continents, economic zones) above countries.
test.territoryHierarchy	EXTENSION	commons.territory	Adds a multi-valued superTerritory relation to every territory, forming a hierarchy.

Together these are a worked example of the abstract role-type pattern every self-referencing hierarchy must use — see Hierarchical filtering. They live in test, not commons, so a tenant that wants a territory hierarchy declares its own equivalent pair.