Tutorial: Define data entities

Data entities describe the shape of business records your team uses (fields, types, constraints) as JSON Schema-style documents. They can back workflow steps, forms, and public-site leads. This tutorial covers every control exposed in Data entities admin for a normal team account.

Where: /home/yourteam/admin/dataentities (replace yourteam with your slug).

Who: Any account member can create, update, or delete private entities for that account (enforced by row-level security). A checkbox labeled Public in the UI is reserved for platform-wide catalogs maintained by a super administrator (account_id null in the database). For day-to-day team work, keep Public unchecked so the entity stays private to your team.

1. Screen layout

The page is split into:

Status messages (saved, errors) appear under the sidebar actions.

2. List and open an entity

Click a row in the sidebar to load that entity into the editor. The Schema JSON textarea and preview update to match the selected row.

You can select different versions of the same logical model as separate rows (for example Customer v1.0 and Customer v2.0)—see Versioning below.

3. Create a new entity (New)

1. Click New. The editor clears selection and switches to create mode.
2. Set Name (logical name, stable over time—for example LoanApplication).
3. Set Version (string—for example 1.0). Default in the UI is often 1.0.
4. Optionally set Description.
5. Leave Public off unless you are a platform operator publishing a global template.
6. Paste or write Schema JSON that describes your record (object shape, properties, required, additionalProperties, etc.—match the JSON Schema conventions your organization uses).
7. Click Save.

Save performs an insert when no row is selected. On success, the sidebar refreshes and the new row is selected.

4. Edit an existing entity

1. Select the entity in the sidebar.
2. Change Name, Version, Description, Public, and/or Schema JSON.
3. Click Save.

Save performs an update on the same row (id unchanged). You are replacing that revision in place.

Important: The database enforces uniqueness on (account_id, name, version). If you change Version to a combination that already exists for the same Name, the save may fail with a uniqueness error. To release a new immutable version, prefer Clone (below) or New with a new Version string.

5. Versioning model (how control works)

Versioning is not a hidden Git branch inside one row. It works like this:

• Each row in the catalog is one named + versioned definition: Name + Version identifies that snapshot for your account (plus account_id).
• Multiple rows with the same Name and different Version values = multiple coexisting versions (for example 1.0, 1.1, 2.0).
• Workflows and forms reference a specific form schema / entity by id (and display name + version in pickers). Old workflow instances keep pointing at the ids they were created with.
• Editing a row updates that snapshot only; it does not automatically migrate running workflow instances or historical data.

Recommended patterns

• Patch typos or non-breaking fixes: edit the same row (same Name + Version) if your governance allows in-place updates.
• Breaking changes: create Clone or New with a bumped Version (2.0), update new workflows and forms to the new row, and leave old rows for historical instances.

6. Clone

1. Select an entity.
2. Click Clone. The UI copies schema and description, suggests a new name (for example MyEntity-copy), keeps the same Version string initially, and clears the id so the next Save creates a new row.

Adjust Name and/or Version before saving to avoid unique constraint clashes.

7. Delete

1. Select an entity.
2. Click Delete and confirm.

Deletion removes that row only. Anything still referencing that id (workflow steps, forms, transformations) may break—check dependencies first.

8. Schema JSON and preview

• Schema JSON must be valid JSON. Invalid JSON shows Invalid schema JSON in the Schema preview card and Save is blocked.
• Schema preview pretty-prints the parsed object for a quick sanity check.

9. Visibility and security (RLS)

• Private entity (Public unchecked, scoped to your team): any member of the account can select / insert / update / delete per policy.
• Global public template (Public checked with no team account_id): only super admins may publish or maintain those rows. Team users still see them in lists for reuse, depending on select policy.

This is catalog security, not field-level security inside a form. Who may submit or view captured data on a given workflow step is configured in Workflow admin (step permissions) and public-site API behavior.

10. Generated entities from forms

When you save a form schema with auto-create linked data entity (or when public site forms sync internal artifacts), the platform may insert a data entity row and set generated_from_form_schema_id in the database. In the Data entities UI you still see Name, Version, schema, etc.—treat these as system-maintained companions unless your process allows manual edits.

11. Related: Form transformations (entity → form mapping)

For versioned mappings from a source entity into a destination form, use Form transformations (separate admin screen):

/home/yourteam/admin/formtransformations

There you can create, edit, clone, delete, and preview transformations that store:

• Source data entity (+ source_version string)
• Destination form schema (+ dest_version string)
• Mapping JSON (array of rules: to, from, constant, expression, etc.)

This is optional but important when the same entity feeds multiple forms or when you need explicit ETL-style rules between versions.

Checklist

• [ ] Entity has a clear Name and Version strategy.
• [ ] Schema JSON validates and matches how workflows / forms will consume it.
• [ ] New versions are new rows (or clone), not silent overwrites, when instances already exist.
• [ ] Public is off for normal tenant-owned entities.
• [ ] Optional: Form transformations configured when mapping entity → form across versions.