Threads — Loom's Data Model

Intermediate May 3, 2026 · 2 min read

A Thread is a YAML file that describes one entity in your domain. It's the only thing you write by hand; everything else (the API, the UI, the database) is woven from it.

A minimal Thread

model: Customer
label: Customer
icon: users
description: A business customer or prospect

fields:
  - name: company_name
    type: text
    required: true
    searchable: true

  - name: email
    type: email
    required: true
    unique: true

permissions:
  - role: Admin
    can: all

Save that as threads/customer.yaml, run loom check and loom weave, and you have a working CRUD API on /api/customers.

What "thread" means

The metaphor runs through the framework: a Thread is a strand the loom weaves into outputs. The five sub-weavers (SQL, Go, SvelteKit, HTMX, Routes) each consume the same Thread and produce their respective artefacts. Same input, multiple outputs, simultaneously — that's the whole framework in one sentence.

Required vs optional sections

Section Required Purpose
model yes PascalCase identifier; becomes the Go struct name
label yes Human-readable name; used in UI and logs
icon yes Lucide icon name; powers the UI's nav and forms
fields yes At least one field
permissions recommended Role-based access; without it, only --no-auth mode reaches the model
relationships optional Links to other Threads
list_view / form_view optional Customise the generated UI
hooks optional Names of Go functions to call on lifecycle events

Naming conventions

Loom enforces these at validation time:

  • Model name: PascalCase (Customer, InvoiceItem)
  • Field name: snake_case (company_name, email)
  • Relationship target: PascalCase (must match another Thread's model)
  • Hook function name: valid Go identifier (NormalizeInvoiceNumber)

The validator rejects bad names with a clear error pointing at the offending field. See Validation Error Catalogue for the full list of rules.

Round-tripping

Every value Loom understands round-trips cleanly through gopkg.in/yaml.v3. You can read a Thread, mutate it programmatically, and write it back without losing comments or field ordering — useful if you build tooling on top of Loom.

Where to go next

  • Concepts → The Five Field Types Worth Knowing — practical field-type guidance
  • Reference → Thread YAML Schema — every field, every option
  • Tutorials → Build a Simple CRM — multi-Thread example with relationships
Was this article helpful?