Skip to main content

Qualified Names

Every class in the platform is identified by its qualified name: a two-part identifier in the format

namespace.name

For example:

  • commons.person — the built-in Person class
  • commons.entity — the built-in Entity class
  • my-project.employee — a custom Employee class in the my-project namespace

Lists and archetypes are named the same way (my-project.contractType, commons.invoice).

Namespace​

The namespace corresponds to the project or repository the class belongs to. Built-in classes use the commons and system namespaces. Your custom classes use the namespace you configure for your repository.

Name​

The name is a unique identifier for the class within the namespace, written in camelCase (e.g., employmentAgreement, person, company). The name also determines the class's file (employmentAgreement.json) and its REST names in the API (employmentAgreement / employmentAgreements).

Usage in JSON​

Within class files, a class is always referenced by its qualified name — as the class itself, as the class it inherits from or extends, and as the target of a relation:

{
  "version": 1,
  "class": "my-project.employmentAgreement",
  "kind": "BASIC",
  "inherits": "commons.dossier",
  "relations": [
    { "class": "commons.company", "required": true, "multiple": false },
    { "class": "my-project.employee", "required": true, "multiple": false }
  ]
}

The same holds where a class file points at a related class, such as archetype relation slots and report contexts. REST names (employees) are only used in the API and in scripts, which work with URLs.

Reserved namespaces​

The system namespace is reserved for the platform's own classes, such as system.userProfile. A tenant model may not declare, import, inherit from, extend or relate to a system.* class; the platform refuses such a model. The commons namespace holds the built-in classes your model builds on — see the Commons Reference.

Stability​

A qualified name is a stable, permanent identifier. Renaming a class is a breaking change — treat it the same way you would treat renaming a database table. References to the old name in other class definitions and in stored data will break.