Model entities and relationships

Model entities and relationships

An entity spec is the source for generated persistence and CRUD metadata. Entity names identify generated classes; fields are keyed by stable application names.

version: 1
entity:
  name: WorkOrder
  label: Work order
  plural: Work orders
meta:
  timestamps: true
fields:
  number:
    type: string
    required: true
    unique: true
  due_date:
    type: date
    required: true
  instructions:
    type: text
    nullable: true
relationships:
  customer:
    type: belongsTo
    entity: Customer
    required: true

The relationship’s entity target must be another entity spec in the same consumer metadata set. Belongs-to relations feed the model, read/write DTOs, request validation, and migration metadata. The relation’s validation checks that the target key exists; it does not enforce business rules beyond that reference.

Create scaffolds with the CLI or copy the full templates:

php backend-laravel/bin/mettada mettada:entity:create WorkOrder --project=Workshop --relations=Customer:belongsTo
php backend-laravel/bin/mettada mettada:lint Workshop

The target entity must already exist. Supported relation types are belongsTo, hasMany, and belongsToMany; use the entity schema reference for relation-specific keys and constraints.

Field behavior

Use type for the storage/validation family, required for request requirements, and nullable when the database value may be absent. Enum fields require a non-empty values list. visible: false suppresses a field in the read-only detail dialog; visibility defaults to true.

What remains application-specific

Mettada generates structural CRUD, not aggregate consistency. For example, capturing a unit-price snapshot, checking inventory, or coordinating multiple related writes belongs in application services and tests.