Define a data model

A data model is the shape of one business entity: an order, a customer, an inventory item. It is a field list with a type per field, a description where that helps, and one field marked as the entity's primary key.

Everything downstream leans on it. Workflows map payloads onto it, the warehouse groups records by its primary key, and dashboard widgets offer its fields as things to chart. It is the one place where the messy names your sources use get turned into the names your organization uses.

Outcome

A data model your workflows can write to and your dashboards can read from.

Before you start

Know which field identifies the entity — the order number, the customer email, the SKU. That becomes the primary key, and it cannot be changed once the model holds records.

Data models live under Warehouse in the sidebar. That page lists every model with its Identifier, its record count, and when it was last written to.

1. Create it

New Data Model offers two routes:

• Create manually — add fields one at a time with names, types, and constraints.
• From JSON Schema — paste a sample JSON object and Hodoflow detects fields automatically.

Manual creation is a three-step wizard: Name & Description, then Add Fields, then Review. The Identifier is generated from the name and is what URLs and API references use. Pick the name carefully, because the identifier cannot be changed afterwards.

Checkpoint: the model appears on the Warehouse list with zero records.

Importing the shape instead

The import route asks for a Sample JSON Payload and infers one field per top-level key:

Every detected field comes back marked required, and a key called id, a key called email, or a key ending in _id is guessed as the primary key. Nested keys are not walked. Detect Fields → drops you into step one of the same wizard with the results filled in, so you can correct all of that before saving.

2. Add the fields

+ Add Field opens a modal with two tabs.

Single takes one field at a time: Field Name (lowercase letters, numbers, and underscores, starting with a letter), an optional Description, the Type, and then the type's own constraint inputs. Save and add another keeps the modal open so you can work down a list.

Six types exist, and the type you pick decides which constraints and aggregations are available later:

Two checkboxes matter more than the rest:

• Required — records fail to be created when the field is not populated.
• Primary Key — identifies the business entity for grouping and aggregating records. Only string and integer fields are eligible, and a model can have only one.

Bulk add takes one field per line as name:type[:required][:pk], so pasting a schema someone sent you is a single operation:

email:string:required
age:integer
is_active:boolean
ordered_at:datetime

Type-only lines are accepted and default to optional. Lines starting with # are ignored, and any line that fails to parse is reported with its line number instead of silently dropped.

Checkpoint: exactly one field carries the PK badge, and every field a workflow will always supply is marked Required.

3. Check the generated schema

Opening a model's Schema page is where the real editing happens. The header carries Usage, + Add Field, Edit Details, and Archive.

The View dropdown switches the section between Fields and JSON Schema — a Draft-7 schema generated from your fields, with a Copy button, which is useful when something outside Hodoflow needs to validate the same shape.

Edit Details changes the name and the description. The identifier stays fixed.

Verify the result

• The model appears on Warehouse with the identifier you expect.
• Exactly one field is the primary key, and it is a string or an integer.
• The JSON Schema view matches the payload your workflow will map from.

Changing fields after data exists

Hodoflow protects records that already exist. Once a model has data, a field's type can only widen — integer to float or string, float to string, boolean to string, datetime to string — and the primary key designation cannot be changed at all.

Fields can no longer be removed at all once records exist — a record is keyed and queried by the shape it was written under. Adding fields stays open.

Changing fields once a workflow uses the model

A model a workflow maps onto is frozen whole, not field by field. While any workflow references it, no field can be removed, and no field's name, type, Required or Primary Key can change — including fields nothing maps to, because a rename is all it takes to turn one into a mapping target. Adding a field is still allowed: it orphans nothing.

The refusal names the workflows holding the model, and View usage takes you to them so you can fix the mappings first. Descriptions and the per-type constraint hints stay editable throughout.

Who is using this model

Usage answers the question you have before changing anything: every dashboard widget and workflow that references this data model.

The Dashboards tab lists widgets by Widget, Type, Source, and Used on, marking anything that lives in the library but is not currently placed on a dashboard.

The Workflows tab groups by workflow and then by version, showing how many mappings each version has and whether it is active, published, or a draft, with links straight into the builder.

When both tabs are empty you get Not used yet, and it is safe to archive.

Archiving

Archive is a soft delete with a grace period. The model disappears from the default list, and after seven days it and all of its records are permanently deleted. Until then a banner on the page counts down, and Restore brings it back.

Archiving is refused while any dashboard widget or workflow mapping still references the model. Remove or reassign those first — View usage takes you to the list.

Right after archiving, a toast offers Undo. Later, the State filter on the Warehouse list switches between Active and Archived so you can find it again.

Delete now on an archived model skips the wait and removes it and its records immediately. That one cannot be undone.

Common problems

I picked the wrong primary key and the model has records. The designation cannot be changed once data exists. Create a new model with the right key and repoint the workflow's mapping step.

A field will not accept my name. Field names are lowercase letters, numbers, and underscores, starting with a letter.

I cannot change a field's type. Types can only widen once records exist — integer to float or string, and so on. Narrowing would invalidate stored records.

Renaming a field is blocked. A workflow mapping references it. View usage lists which; fix those mappings first.

Activation says the model has no primary key. Mark one string or integer field as Primary Key. See Activation errors.

Archiving is refused. A widget or mapping still points at it.

Next step

Persist workflow data — a data model on its own holds nothing until a workflow fills it.