Data model — Tag
A Tag is a workspace-scoped free-form label that can be applied to Locations and surfaced as a refinement option in the Finder widget.
Table: tags
| Column | Type | Nullable | Description |
|---|---|---|---|
| id | bigint (auto-increment) | no | Primary key |
| name | varchar (unique at creation) | no | Human-readable label shown in the widget |
| slug | varchar (unique at creation) | no | URL/SEO-safe identifier; used as the refinement value |
| description | text | yes | Optional internal description |
| workspace_id | bigint (FK → workspaces.id) | yes | Owning workspace; set to null on workspace deletion (nullOnDelete). Added in migration 2026_04_05 |
| created_at | timestamp | no | Laravel auto-managed |
| updated_at | timestamp | no | Laravel auto-managed |
⚠️ Warning: The original
tagsmigration creatednameandslugwith a database-levelunique()constraint. Theworkspace_idcolumn was added later. Ifworkspace_idis null the tag has no workspace affiliation — this is a legacy state from before the workspace-scoped migration. New tags always have aworkspace_id.
Relations
- belongsTo
Workspace— direct foreign keyworkspace_id. A Tag belongs to exactly one Workspace. - belongsToMany
Location— vialocation_tagpivot. The locations that have this tag applied.
Slug
The slug field is the stable identifier for the Tag in refinement rules and URL params. Slug generation is handled on the frontend or at the API layer before persisting. 🔴 [NEEDS CLARIFICATION: Is the slug auto-generated from name on the backend, or is it a required field the caller must supply?]
Tags are referenced by slug in refinement configuration — if a tag is renamed its slug should remain stable to avoid breaking active refinement rules.
Workspace scoping
Tags are scoped to a single workspace via workspace_id. The migration 2026_04_05_000003_add_workspace_id_to_tags_table.php back-filled workspace_id for all existing tags by joining through location_tag → location_workspace. Tags that could not be matched to a workspace were assigned the lowest-id workspace as a fallback.
Computed / virtual attributes
None. No $appends, no JSON casts.
Cross-links
- Location data model — Tags are applied to Locations
- Workspace data model — Tags belong to a Workspace
- API reference — Tags