Entity Schema Reference

This document provides the authoritative reference for Stack9 entity schema definitions. All properties listed here are validated by the Stack9 schema validators and represent the complete set of available configuration options.

Source of Truth

This reference is generated from the Joi validators in packages/stack9-sdk/src/schema/validators/v2/. When in doubt, the validators are the definitive source.

Entity Structure

An entity definition consists of the following top-level properties:

{
  "head": { /* Entity metadata */ },
  "fields": [ /* Field definitions */ ],
  "notifications": [ /* Optional notification definitions */ ],
  "workflowDefinition": { /* Optional workflow configuration */ }
}

Entity Head Properties

The head section defines metadata about the entity. These properties control the entity's behavior and features.

Custom Entity Head

For custom entities (EntityType.custom), the following properties are available:

Property	Type	Required	Description
key	string	Yes	Unique identifier for the entity. Must be lowercase, alphanumeric with underscores. Max 57 characters. Cannot start with _ or knex.
name	string	Yes	Display name for the entity (singular form).
pluralisedName	string	Yes	Plural form of the entity name for lists and collections.
isActive	boolean	Yes	Whether the entity is active and available in the system.
allowComments	boolean	Yes	Enable the comments feature for entity records.
allowTasks	boolean	Yes	Enable the tasks feature for entity records.
maxAttachmentSizeAllowed	number | null	No	Maximum attachment size in bytes. Set to null for no limit.
acceptedAttachmentFileTypes	string[]	No	Array of allowed MIME types for attachments (e.g., ["image/jpeg", "application/pdf"]).

Native Entity Head

For native entities (EntityType.native), only the following property is available:

Property	Type	Required	Description
key	string	Yes	Entity key with same validation rules as custom entities.

Example Head Configuration

{
  "head": {
    "key": "customer",
    "name": "Customer",
    "pluralisedName": "customers",
    "isActive": true,
    "allowComments": true,
    "allowTasks": false,
    "maxAttachmentSizeAllowed": 10485760,
    "acceptedAttachmentFileTypes": [
      "image/jpeg",
      "image/png",
      "application/pdf"
    ]
  }
}

Field Types

Stack9 supports the following field types:

• TextField
• CustomUIComponent
• MapLocation
• MonacoEditorField
• RichTextEditor
• NumericField
• Checkbox
• FileField
• DateField
• SingleDropDown
• MultiDropDown
• Grid
• PrivilegiesMatrix
• OptionSet
• WorkflowStep
• ColorPickerField

Common Field Properties

All fields share these common properties:

Property	Type	Required	Description
key	string	Yes	Field identifier. Must be lowercase, alphanumeric with underscores. Cannot use reserved names.
label	string	Yes	Display label for the field.
type	string	Yes	One of the supported field types listed above.
description	string | null	No	Help text or description for the field.
placeholder	string | null	No	Placeholder text for input fields.
index	boolean | string[]	No	Create database index. Can be boolean for single index or array of field names for composite index.
unique	boolean | string[]	No	Enforce uniqueness. Can be boolean for single field or array for composite unique constraint.
validateRules	object	No	Validation rules (see Validation Rules section).
behaviourOptions	object	No	UI behavior options (see Behaviour Options section).
typeOptions	object	No	Type-specific options (varies by field type).
relationshipOptions	object	Conditional	Required for relationship fields (SingleDropDown, MultiDropDown, Grid).

Reserved Field Names

The following field names are reserved and cannot be used:

• id
• _created_by
• _updated_by
• _created_at
• _updated_at
• _version
• _active
• _is_deleted
• _workflow_outcome
• _workflow_outcome_reason
• _workflow_outcome_user_id
• _workflow_definition
• _workflow_definition_version_id
• _workflow_current_owner
• _workflow_current_step
• _workflow_current_step_name

Validation Rules

The validateRules object supports the following properties:

Property	Type	Applies To	Description
required	string | boolean	All	Field is required. Can be boolean or custom error message.
maxLength	number	Text fields	Maximum character length.
minLength	number	Text fields	Minimum character length.
max	number	Numeric fields	Maximum numeric value.
min	number	Numeric fields	Minimum numeric value.
pattern	string	Text fields	Regular expression pattern for validation.

Example Validation Rules

{
  "validateRules": {
    "required": true,
    "maxLength": 100,
    "minLength": 3,
    "pattern": "^[A-Za-z0-9]+$"
  }
}

Behaviour Options

The behaviourOptions object supports:

Property	Type	Description
readOnly	boolean	Field is read-only in the UI.
hidden	boolean	Field is hidden in the UI (still exists in database).
displayAsDefaultFilter	boolean	Include field in default filter options.

Example Behaviour Options

{
  "behaviourOptions": {
    "readOnly": false,
    "hidden": false,
    "displayAsDefaultFilter": true
  }
}

Type-Specific Options

Each field type has its own typeOptions configuration:

TextField

Property	Type	Description
multiLine	boolean	Enable multi-line text input.
text	boolean	Use text database column type instead of varchar.
sensitive	boolean	Mark field as containing sensitive data.

Note: For SingleDropDown fields with _id suffix, the key must match pattern /[a-z0-9_]{2,}_id/.

NumericField

Property	Type	Description
precision	number	Number of decimal places.

Note: There is no allowNegative or decimals property. Use validation rules min: 0 to prevent negative values.

DateField

Property	Type	Required	Description
time	boolean	Yes	Include time component (datetime vs date only).

FileField

Property	Type	Required	Description
accept	string[]	Yes	Array of accepted MIME types.
isPublic	boolean	Yes	Whether files are publicly accessible.
maxSizeBytes	number	No	Maximum file size in bytes.
maxNumberFiles	number	Conditional	Required when multiple is true. Must be greater than 1.
multiple	boolean	No	Allow multiple file uploads.
allowCameraCapture	boolean	No	Enable camera capture on mobile devices.

SingleDropDown (Relationship)

Property	Type	Required	Description
label	string	Yes	Field from related entity to display.

relationshipOptions:

Property	Type	Required	Description
ref	string	Yes	Key of the related entity.
where	object	No	Filter conditions for related records.

MultiDropDown (Many-to-Many)

Property	Type	Required	Description
value	string	Yes	Field to use as value (typically "id").
label	string	Yes	Field or template to display.

relationshipOptions: Same as SingleDropDown.

Grid (One-to-Many)

Property	Type	Required	Description
relationshipField	string	Yes	Foreign key field in the child entity.

relationshipOptions:

Property	Type	Required	Description
ref	string	Yes	Key of the related child entity.
where	object	No	Filter conditions for related records.

MonacoEditorField

Property	Type	Required	Description
language	string	Yes	Editor language. One of: json, handlebars, html, text, css.

PrivilegiesMatrix

Property	Type	Required	Description
scope	string	Yes	Privilege scope. One of the PrivilegesScopes enum values.

OptionSet

Property	Type	Required	Description
values	string[]	Yes	Array of option values.

CustomUIComponent

Property	Type	Required	Description
component	string	Yes	Name of the custom UI component.
dependsOn	string[]	No	Array of field keys this component depends on.

RichTextEditor

No specific typeOptions required.

ColorPickerField

No specific typeOptions required.

MapLocation

No specific typeOptions required.

WorkflowStep

No specific typeOptions required.

Checkbox

No specific typeOptions required.

Complete Field Examples

TextField Example

{
  "key": "email",
  "label": "Email Address",
  "type": "TextField",
  "description": "Primary contact email",
  "placeholder": "user@example.com",
  "validateRules": {
    "required": true,
    "maxLength": 255,
    "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
  },
  "typeOptions": {
    "multiLine": false
  },
  "behaviourOptions": {
    "readOnly": false
  },
  "index": true,
  "unique": true
}

NumericField Example

{
  "key": "price",
  "label": "Price",
  "type": "NumericField",
  "description": "Product price",
  "validateRules": {
    "required": true,
    "min": 0,
    "max": 999999
  },
  "typeOptions": {
    "precision": 2
  }
}

DateField Example

{
  "key": "birth_date",
  "label": "Date of Birth",
  "type": "DateField",
  "typeOptions": {
    "time": false
  },
  "validateRules": {
    "required": true
  }
}

SingleDropDown Example

{
  "key": "customer_id",
  "label": "Customer",
  "type": "SingleDropDown",
  "relationshipOptions": {
    "ref": "customer",
    "where": {
      "is_active": true
    }
  },
  "typeOptions": {
    "label": "name"
  },
  "validateRules": {
    "required": true
  }
}

MultiDropDown Example

{
  "key": "tags",
  "label": "Tags",
  "type": "MultiDropDown",
  "relationshipOptions": {
    "ref": "tag"
  },
  "typeOptions": {
    "label": "name",
    "value": "id"
  }
}

Grid Example

{
  "key": "order_items",
  "label": "Order Items",
  "type": "Grid",
  "relationshipOptions": {
    "ref": "order_item"
  },
  "typeOptions": {
    "relationshipField": "order_id"
  }
}

FileField Example

{
  "key": "attachments",
  "label": "Attachments",
  "type": "FileField",
  "typeOptions": {
    "accept": ["image/jpeg", "image/png", "application/pdf"],
    "isPublic": false,
    "maxSizeBytes": 5242880,
    "multiple": true,
    "maxNumberFiles": 10,
    "allowCameraCapture": true
  }
}

OptionSet Example

{
  "key": "status",
  "label": "Status",
  "type": "OptionSet",
  "typeOptions": {
    "values": ["Draft", "Pending", "Approved", "Rejected"]
  },
  "validateRules": {
    "required": true
  }
}

MonacoEditorField Example

{
  "key": "config",
  "label": "Configuration",
  "type": "MonacoEditorField",
  "typeOptions": {
    "language": "json"
  }
}

Notifications

The notifications array allows configuring email notifications for entity events. This is validated by the NotificationsValidator.

Workflow Definition

The workflowDefinition object configures workflow steps and actions for the entity. This is validated by the WorkflowDefinitionValidator.

Complete Entity Example

{
  "head": {
    "key": "order",
    "name": "Order",
    "pluralisedName": "orders",
    "isActive": true,
    "allowComments": true,
    "allowTasks": true,
    "maxAttachmentSizeAllowed": 10485760,
    "acceptedAttachmentFileTypes": ["application/pdf"]
  },
  "fields": [
    {
      "key": "order_number",
      "label": "Order Number",
      "type": "TextField",
      "validateRules": {
        "required": true,
        "pattern": "^ORD-[0-9]{6}$"
      },
      "behaviourOptions": {
        "readOnly": true
      },
      "index": true,
      "unique": true
    },
    {
      "key": "customer_id",
      "label": "Customer",
      "type": "SingleDropDown",
      "relationshipOptions": {
        "ref": "customer"
      },
      "typeOptions": {
        "label": "name"
      },
      "validateRules": {
        "required": true
      }
    },
    {
      "key": "total_amount",
      "label": "Total Amount",
      "type": "NumericField",
      "typeOptions": {
        "precision": 2
      },
      "validateRules": {
        "required": true,
        "min": 0
      },
      "behaviourOptions": {
        "readOnly": true
      }
    },
    {
      "key": "order_date",
      "label": "Order Date",
      "type": "DateField",
      "typeOptions": {
        "time": true
      },
      "validateRules": {
        "required": true
      }
    },
    {
      "key": "status",
      "label": "Status",
      "type": "OptionSet",
      "typeOptions": {
        "values": ["Draft", "Pending", "Processing", "Shipped", "Delivered", "Cancelled"]
      },
      "validateRules": {
        "required": true
      }
    },
    {
      "key": "order_items",
      "label": "Order Items",
      "type": "Grid",
      "relationshipOptions": {
        "ref": "order_item"
      },
      "typeOptions": {
        "relationshipField": "order_id"
      }
    },
    {
      "key": "notes",
      "label": "Notes",
      "type": "RichTextEditor",
      "description": "Internal notes about the order"
    }
  ]
}

Important Notes

1. No Icon Property: The head section does NOT have an icon property. Icons are configured in screens and apps, not in entity definitions.

2. No allowAttachments Property: There is no allowAttachments property. File attachments are controlled by maxAttachmentSizeAllowed and acceptedAttachmentFileTypes.

3. No Format Property: TextField does NOT have a format property in typeOptions. Use validation rules with patterns instead.

4. No Decimals Property: NumericField does NOT have a decimals property. Use the precision property instead.

5. No allowNegative Property: NumericField does NOT have an allowNegative property. Use validation rule min: 0 to prevent negative values.

6. Required typeOptions: Some field types REQUIRE typeOptions to be specified:

   • DateField requires time property
   • FileField requires accept and isPublic properties
   • MonacoEditorField requires language property
   • OptionSet requires values property
   • SingleDropDown requires label property in typeOptions
   • MultiDropDown requires label and value properties in typeOptions
   • Grid requires relationshipField property in typeOptions
   • PrivilegiesMatrix requires scope property

7. Relationship Fields: SingleDropDown, MultiDropDown, and Grid fields MUST have relationshipOptions with a ref property.

8. Field Key Constraints:

   • SingleDropDown fields with keys ending in _id must match pattern /[a-z0-9_]{2,}_id/
   • Field keys cannot use reserved names (see Reserved Field Names section)
   • Keys must be lowercase, alphanumeric with underscores only

Validation Hierarchy

Entity validation occurs in the following order:

1. Structural Validation: JSON structure and required properties
2. Field Type Validation: Field types and their required options
3. Relationship Validation: Relationship references and configurations
4. Custom Validation: Entity hooks and business rules

See Also

• Creating Entities - Step-by-step guide to creating entities
• Entity Relationships - Setting up relationships between entities
• Entity Hooks - Adding business logic to entities
• Validation Hooks - Custom validation rules