Schema Design

Naming Conventions

Thing	Convention	Examples
Entity keys	`snake_case`, plural	`tasks`, `contacts`, `inventory_items`
Entity names	Title Case, plural	”Tasks”, “Contacts”, “Inventory Items”
Field keys	`snake_case`	`due_date`, `is_complete`, `contact_email`
Field names	Title Case	”Due Date”, “Completed”, “Contact Email”

Best Practices

Use `select` over `text` for constrained values

If a field has a known set of valid values (status, priority, category), use select rather than text. This ensures data consistency and enables efficient filtering.

✓  status: select ["open", "in_progress", "done"]
✗  status: text (free-form — "Open", "In Progress", "DONE" are all different)

Use `multi_select` for tags

When a record can belong to multiple categories simultaneously, use multi_select:

tags: multi_select ["frontend", "backend", "design", "devops"]

Mark truly required fields

Only mark a field as required if the record is meaningless without it. Overly strict required fields frustrate users and complicate imports.

Use `relation` for cross-entity references

When a record in one entity refers to a record in another entity in the same app, use type: relation rather than a plain text field:

✓  project_id: relation → related_entity: "projects", display_field: "name"
✗  project_id: text (free-form string — no referential integrity or validation)

HASP validates that the referenced record exists when creating or updating a record.

Keep entities focused

One entity per concept. Don’t combine “tasks” and “comments” into one entity — make two entities and use a relation field in the comments entity to point back to the task.

Set a `display_field`

Every entity should have a designated display_field — the field shown in lists and the HASP dashboard. Usually this is the main name or title field.

Example Schemas

Task Tracker

Field	Key	Type	Required	Notes
Title	`title`	text	Yes	display_field
Description	`description`	textarea	No
Status	`status`	select	Yes	open, in_progress, done
Priority	`priority`	select	No	low, medium, high, critical
Due Date	`due_date`	date	No
Assignee Email	`assignee_email`	email	No

Contact Directory

Field	Key	Type	Required
Name	`name`	text	Yes
Email	`email`	email	Yes
Company	`company`	text	No
Role	`role`	text	No
Website	`website`	url	No
Tags	`tags`	multi_select	No
Notes	`notes`	textarea	No

Inventory

Field	Key	Type	Required	Notes
Name	`name`	text	Yes	display_field
SKU	`sku`	text	Yes
Category	`category`	select	Yes
Quantity	`quantity`	number	Yes	min: 0
Unit Price	`unit_price`	number	No
Low Stock	`is_low_stock`	boolean	No
Last Restocked	`last_restocked`	date	No

​Naming Conventions

​Best Practices

​Use select over text for constrained values

​Use multi_select for tags

​Mark truly required fields

​Use relation for cross-entity references

​Keep entities focused

​Set a display_field

​Example Schemas

​Task Tracker

​Contact Directory

​Inventory