Class File Format

Each class is defined in its own JSON file. The file name corresponds to the class name part of the qualified name (e.g., my-project.employee → employee.json).

Top-level structure

{
  "$schema": "https://api.mosterd.com/schema/definition-v1.schema.json",
  "version": 1,
  "class": "my-project.employmentAgreement",
  "kind": "BASIC",
  "inherits": "commons.agreement",
  "fields": [...],
  "relations": [...],
  "formulas": [...],
  "archetypeDefinitions": [...],
  "archetypes": [...],
  "scripts": [...],
  "reports": [...],
  "lists": [...],
  "views": [...],
  "layouts": [...],
  "assets": [...],
  "translations": [...],
  "accessControl": [...],
  "roles": [...],
  "data": [...],
  "migration": {...}
}

Property	Type	Description
$schema	URL	Optional editor hint: the JSON Schema of the file's format. Ignored by the platform. See Editor support.
version	integer	The definition format the file is written in. The current format is 1; a file without version is format 0.
class	QualifiedName	Qualified name of this class.
kind	BASIC | ABSTRACT | CONFIG | EXTENSION	The role of the class. See Class Kinds.
inherits	QualifiedName	The class this class inherits from. Required for BASIC and ABSTRACT classes.
extends	QualifiedName	For an EXTENSION: the class being extended. Use instead of inherits.
imports	QualifiedName[]	Classes to load. Used in index.json.
modules	Module[]	Optional bundles of imports. See Modules.
fields	FieldDefinition[]	The class's own fields. See Fields.
nameField	string	The field that holds the object's display name. Defaults to the inherited name field.
customKeyField	string	A field whose value can be used as an alternative key for objects of this class, for example during an import.
relations	RelationDefinition[]	Relation definitions. See Relations.
formulas	Formula[]	Computed field definitions. See Formulas.
archetypeDefinitions	Archetype[]	Semantic archetype declarations (slots). Usually on a CONFIG class. See Archetypes.
archetypes	ArchetypeBinding[]	Bindings mapping this class's fields/relations onto archetype slots. See Archetypes.
scripts	Script[]	Action definitions. See Scripts.
reports	Report[]	Document generation definitions. See Reports.
pipeline	Pipeline	Automated processing of new objects. See Pipeline.
lists	StandardList[]	Named value lists for LIST fields. See Lists.
views	View[]	Table/list view definitions. See Views.
layouts	Layout[]	UI layout definitions. See Layouts.
assets	Asset[]	Static files (kind LOGO or STYLESHEET) served from the repository.
translations	Translation[]	Language-specific labels for this class and its fields. See Translations.
accessControl	AccessControlDefinition[]	Access-control definitions. Each names the objects that carry its identifier and, optionally, the users who do. See Access Control and the schema reference.
roles	Role[]	Roles bundling access-control definitions, referenced from system.userProfile.accessRoles. A separate branch from accessControl, usually declared alongside it on the same class. See the schema reference.
data	DefaultData[]	Fixture objects to create when loading default data. See Default Data.
indexed	boolean	Whether objects of this class appear in the general search. Default true. See Search.
generalSearchClasses	QualifiedName[]	The classes the app's general search box searches. See Search.
migration	MigrationDefinition	Migration mapping from a legacy system (beta). See Migration.

Strict checking

The platform checks every file when it loads the model. An unknown or misspelled property, a reference to a field, script or file that does not exist, or a field name that is not lowerCamelCase refuses the model, with a message per file and JSON pointer. The previously loaded model keeps serving the tenant until the errors are fixed. See Loading a model.

Complete example

A custom EmploymentAgreement class that inherits from commons.dossier:

{
  "$schema": "https://api.mosterd.com/schema/definition-v1.schema.json",
  "version": 1,
  "class": "my-project.employmentAgreement",
  "kind": "BASIC",
  "inherits": "commons.dossier",

  "fields": [
    { "name": "jobTitle", "required": true },
    { "name": "salary", "dataType": "CURRENCY" },
    { "name": "hoursPerWeek", "dataType": "INTEGER" }
  ],

  "formulas": [
    {
      "field": "name",
      "template": "{{jobTitle}}"
    }
  ],

  "relations": [
    { "class": "commons.company", "required": true, "multiple": false },
    { "class": "commons.employee", "required": true, "multiple": false }
  ],

  "scripts": [
    {
      "name": "extractFromDocument",
      "type": "FUNCTION_GATEWAY",
      "scope": "OBJECT",
      "trigger": ["MANUAL"],
      "gateway": "Ai",
      "parameters": [
        {
          "name": "documents",
          "templateFile": "templates/dossierAndDocuments.hbs"
        },
        {
          "name": "jobTitle",
          "value": "The job title if mentioned"
        },
        {
          "name": "salary",
          "value": "The monthly gross salary"
        }
      ],
      "targets": [
        { "name": "jobTitle", "actionType": "OVERWRITE" },
        { "name": "salary", "actionType": "OVERWRITE" }
      ]
    }
  ],

  "lists": [
    {
      "name": "my-project.contractType",
      "items": [
        { "key": "permanent", "color": "#1a7f37", "backgroundColor": "#dafbe1" },
        { "key": "fixedTerm", "color": "#9a6700", "backgroundColor": "#fff8c5" },
        { "key": "freelance", "color": "#0969da", "backgroundColor": "#ddf4ff" }
      ]
    }
  ]
}

EXTENSION class example

Add a custom field to commons.person without creating a new class:

{
  "version": 1,
  "class": "my-project.person",
  "kind": "EXTENSION",
  "extends": "commons.person",
  "fields": [
    { "name": "employeeNumber" },
    { "name": "department" }
  ]
}

After loading, every commons.person in the tenant has the extra fields employeeNumber and department.

ABSTRACT class example

An abstract Shareholder class that can be applied to both persons and companies:

{
  "version": 1,
  "class": "my-project.shareholder",
  "kind": "ABSTRACT",
  "inherits": "commons.entity",
  "fields": [
    { "name": "sharePercentage", "dataType": "PERCENTAGE" }
  ]
}

File naming

File names are derived from the class name portion of the qualified name:

QualifiedName	File
my-project.employee	employee.json
my-project.employmentAgreement	employmentAgreement.json
my-project.taxDossier	taxDossier.json

All class files of a repository are in the same directory as its index.json: the repository root, or the directory configured for the tenant. Files that a class refers to — scripts, templates, prompts — may be organized in subdirectories; they are referenced by their path relative to the repository root, including the extension (scripts/logNoteChange.js).