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.

Inheritance tree

commons.item (ABSTRACT)
├── commons.entity (ABSTRACT)
│   ├── commons.person (BASIC)
│   │   └── commons.employee (ABSTRACT)
│   └── commons.company (BASIC)
│       ├── commons.groupCompany (ABSTRACT)
│       └── commons.counterparty (ABSTRACT)
├── commons.dossier (ABSTRACT)
│   ├── commons.agreement (ABSTRACT)
│   │   ├── commons.employmentAgreement (BASIC)
│   │   └── commons.generalAgreement (BASIC)
│   ├── commons.taxAndFinance (ABSTRACT)
│   │   └── commons.taxDossier (BASIC)
│   └── commons.generalDossier (BASIC)
├── commons.content (ABSTRACT)
│   ├── commons.document (BASIC)
│   ├── commons.memo (BASIC)
│   └── commons.task (BASIC)
├── commons.territory (ABSTRACT)
│   ├── commons.superTerritory (ABSTRACT)
│   ├── commons.country (BASIC)
│   └── commons.region (BASIC)
└── commons.taxPeriod (BASIC)

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.

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()

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. Used as a relation type on commons.generalAgreement.

---

commons.counterparty

Type: ABSTRACT | Inherits: commons.entity

An abstract class used to mark an entity as the external party in an agreement. Used as a relation type on commons.generalAgreement.

---

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.

---

commons.employmentAgreement

Type: BASIC | Inherits: commons.agreement

An employment agreement between a company and an employee.

Value types:

Field	Type	Required
jobTitle	TEXT	yes

Formulas:

• name = {{jobTitle}}

Relations:

Relation	Type	Required	Multiple
Company	commons.company	yes	no
Employee	commons.employee	yes	no

Scripts:

• complete (functionGateway, MANUAL) — extracts job title and dates from attached documents using OpenAI

---

commons.generalAgreement

Type: BASIC | Inherits: commons.agreement

A generic agreement between an internal group company and an external counterparty.

Relations:

Relation	Type	Required	Multiple
Group company	commons.groupCompany	yes	no
Counterparty	commons.counterparty	yes	no

---

commons.taxAndFinance

Type: ABSTRACT | Inherits: commons.dossier

Base class for tax and finance dossiers. Adds a required relation to an entity.

Relations:

Relation	Type	Required	Multiple
Entity	commons.entity	yes	no

---

commons.taxDossier

Type: BASIC | Inherits: commons.taxAndFinance

A dossier for tax-related cases.

Value types:

Field	Type	Required
taxType	TEXT	yes

Formulas:

• name = {{taxType}}

Relations:

Relation	Type	Required	Multiple
Entity	commons.entity	yes	no
Tax period	commons.taxPeriod	yes	no

---

commons.generalDossier

Type: BASIC | Inherits: commons.dossier

A generic dossier type for cases that do not fit a more specific class.

Relations:

Relation	Type	Required	Multiple
Entity	commons.entity	yes	no

---

commons.content

Type: ABSTRACT | Inherits: commons.item

Base class for content items — objects that belong to a dossier. Documents, memos, and tasks 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.

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)

Formulas:

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

Scripts:

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

---

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, optionally assigned to a person.

Value types:

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

Formulas:

• name = {{title}}

Relations:

Relation	Type	Required	Multiple	Description
Dossier	commons.dossier	yes	no	Inherited from commons.content
Assignee	commons.person	no	no	Person responsible for this task

---

commons.territory

Type: ABSTRACT | Inherits: commons.item

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

---

commons.superTerritory

Type: ABSTRACT | Inherits: commons.territory

An abstract marker class for large geographic groupings (e.g. continents, economic zones) that sit above countries in a hierarchy.

The platform includes a commons.territoryHierarchy EXTENSION class that adds a superTerritory relation to every commons.territory. This extension must be explicitly imported in your index.json to activate the hierarchy:

{
  "class": "my-project.index",
  "type": "NONE",
  "imports": [
    "commons.territoryHierarchy"
  ]
}

Once imported, any territory (country, region, or super territory) can be linked to one or more parent territories:

Relation	Type	Required	Multiple
Super territory	commons.superTerritory	no	yes

---

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.taxPeriod

Type: BASIC | Inherits: commons.item

Represents a tax period. Standalone item not tied to the dossier hierarchy.

---

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.