Metadata Format Specification

ObjectOS uses strict YAML schemas for defining application metadata. This document specifies the complete format for object definitions.

Object Schema

Basic Structure

name: <string> # Required: Internal API name (snake_case)
label: <string> # Optional: Human-readable display name
description: <string> # Optional: Object description
icon: <string> # Optional: Icon name (from icon library)
enable_api: <boolean> # Optional: Enable API endpoints (default: true)
enable_audit: <boolean> # Optional: Enable audit logging (default: false)

fields:
  <field_name>:
    type: <field_type> # Required: Field data type
    label: <string> # Optional: Display label
    description: <string> # Optional: Help text
    required: <boolean> # Optional: Is field required (default: false)
    unique: <boolean> # Optional: Must be unique (default: false)
    default: <any> # Optional: Default value

permission_set:
  allowRead: <boolean|array> # Who can read records
  allowCreate: <boolean|array> # Who can create records
  allowEdit: <boolean|array> # Who can edit records
  allowDelete: <boolean|array> # Who can delete records

Example: Complete Object Definition

name: contacts
label: Contact
description: Customer and prospect contact information
icon: user
enable_api: true
enable_audit: true

fields:
  first_name:
    type: text
    label: First Name
    required: true
    max_length: 100

  last_name:
    type: text
    label: Last Name
    required: true
    max_length: 100

  email:
    type: email
    label: Email Address
    unique: true
    required: true

  phone:
    type: text
    label: Phone Number
    pattern: '^\+?[1-9]\d{1,14}$'

  birthdate:
    type: date
    label: Birth Date

  account:
    type: lookup
    label: Account
    reference_to: accounts
    on_delete: set_null

  is_active:
    type: boolean
    label: Active
    default: true

  status:
    type: select
    label: Status
    options:
      - value: active
        label: Active
      - value: inactive
        label: Inactive
      - value: pending
        label: Pending
    default: pending

permission_set:
  allowRead: true # Everyone can read
  allowCreate: ['sales', 'admin'] # Sales and admin can create
  allowEdit: ['sales', 'admin'] # Sales and admin can edit
  allowDelete: ['admin'] # Only admin can delete

Field Types Reference

Text Fields

text

Short text field (up to 255 characters).

field_name:
  type: text
  label: Title
  max_length: 100 # Optional: Maximum length
  min_length: 3 # Optional: Minimum length
  pattern: '^[A-Za-z]+$' # Optional: Regex pattern

textarea

Long text field (unlimited length).

description:
  type: textarea
  label: Description
  rows: 5 # Optional: Display rows

email

Email address field with validation.

email:
  type: email
  label: Email Address
  unique: true

url

URL field with validation.

website:
  type: url
  label: Website

phone

Phone number field.

phone:
  type: text
  label: Phone
  pattern: '^\+?[1-9]\d{1,14}$'

Numeric Fields

number

Integer or decimal number.

quantity:
  type: number
  label: Quantity
  min: 0 # Optional: Minimum value
  max: 1000 # Optional: Maximum value
  precision: 2 # Optional: Decimal places

currency

Monetary value.

price:
  type: currency
  label: Price
  currency_code: USD # Optional: Currency code
  precision: 2 # Decimal places

percent

Percentage value (0-100).

discount:
  type: percent
  label: Discount Rate
  min: 0
  max: 100

Date and Time Fields

date

Date only (no time).

birth_date:
  type: date
  label: Birth Date
  min: '1900-01-01' # Optional: Minimum date
  max: '2100-12-31' # Optional: Maximum date

datetime

Date and time.

created_at:
  type: datetime
  label: Created At
  default: now # Special value: current timestamp

time

Time only (no date).

start_time:
  type: time
  label: Start Time

Boolean and Selection Fields

boolean

True/false checkbox.

is_active:
  type: boolean
  label: Active
  default: true

select

Dropdown selection (single value).

status:
  type: select
  label: Status
  options:
    - value: draft
      label: Draft
    - value: published
      label: Published
  default: draft

multiselect

Multiple selection.

tags:
  type: multiselect
  label: Tags
  options:
    - value: important
      label: Important
    - value: urgent
      label: Urgent

Relationship Fields

lookup

Many-to-one relationship (foreign key).

account:
  type: lookup
  label: Account
  reference_to: accounts
  on_delete: set_null # Options: set_null, cascade, restrict

master_detail

Master-detail relationship (cascade delete).

account:
  type: master_detail
  label: Account
  reference_to: accounts
  on_delete: cascade # Automatically cascades

Special Fields

autonumber

Auto-incrementing number.

ticket_number:
  type: autonumber
  label: Ticket #
  format: 'TKT-{0000}' # Format template
  start_number: 1 # Starting number

formula

Calculated field.

full_name:
  type: formula
  label: Full Name
  formula: 'first_name + " " + last_name'
  return_type: text

rollup_summary

Aggregation from related records.

total_opportunities:
  type: rollup_summary
  label: Total Opportunities
  reference_to: opportunities
  summary_type: count # Options: count, sum, min, max, avg

Field Attributes

Common Attributes

All fields support these attributes:

Attribute	Type	Description
type	string	Required. Field data type
label	string	Display label for UI
description	string	Help text shown in UI
required	boolean	Field is required (default: false)
unique	boolean	Value must be unique (default: false)
default	any	Default value for new records
readonly	boolean	Field cannot be edited (default: false)
hidden	boolean	Hide from UI (default: false)

Validation Attributes

Attribute	Applies To	Description
min	number, currency, percent, date	Minimum value
max	number, currency, percent, date	Maximum value
min_length	text, textarea	Minimum character length
max_length	text, textarea, email, url	Maximum character length
pattern	text, email, url, phone	Regex validation pattern
precision	number, currency, percent	Decimal places

Relationship Attributes

Attribute	Applies To	Description
reference_to	lookup, master_detail	Target object name
on_delete	lookup, master_detail	Cascade behavior
related_list_label	lookup, master_detail	Label in related list

Permission Schema

Permissions control who can access and modify records.

Object-Level Permissions

permission_set:
  allowRead: <boolean|array<string>>
  allowCreate: <boolean|array<string>>
  allowEdit: <boolean|array<string>>
  allowDelete: <boolean|array<string>>

• true: Everyone has permission
• false: No one has permission
• ['role1', 'role2']: Only specified roles have permission

Field-Level Permissions

fields:
  salary:
    type: currency
    label: Salary
    visible_to: ['hr', 'admin'] # Only HR and admin can see
    editable_by: ['hr'] # Only HR can edit

Validation Rules

Built-in Validation

ObjectOS automatically validates:

• Required fields
• Unique fields
• Data type correctness
• Min/max constraints
• Pattern matching
• Reference integrity

Custom Validation

Define custom validation in hooks (see Logic Hooks).