Core Fields — Project
Every column on the projects table (and its siblings) of the Mockomat metadata schema, with notes on what each value drives in the product. Use the anchors (#projects.<column>) to deep-link a specific field from the app's Read docs icons.
TIP
This page is reference, not tutorial. For the how-to side of project creation, see Getting Started. For sharing mechanics, see Preview & Hints.
Identity
These columns identify a project and never change shape, even when the display name does.
uuid
string · required · immutable
Stable identifier used in URLs, share links, and cross-references. Generated when the project is created and never modified — even renaming the project keeps the same uuid. Use this whenever you need to reference the project programmatically (API, exports, integrators).
name
string · required
The display name shown in lists, on the board, and on every share link. Treated as opaque text — pick whatever a human will recognise. Renaming is safe: nothing internal keys off the name, so existing links and integrations continue to work.
INFO
Names need not be globally unique. Two users can each have a project called Demo Shop. If you need a unique handle for URLs or external tools, that's what slug is for.
slug
string · required · URL-safe
Human-readable handle used in URLs and mock-API endpoints (e.g. mock/demo-shop/graphql). Auto-derived from the name when you first save the project but editable afterwards.
- Must be lowercase, with hyphens instead of spaces.
- Must be unique within your tenant — two projects in the same tenant cannot share a slug.
- Changing the slug rewrites the public mock endpoint. Existing integrations stop resolving until they're updated.
icon
string · optional
Material icon name (e.g. auto_awesome, shopping_cart). Picked from the icon picker in the project dialog. Falls back to a generic project icon when unset.
subtitle
string · optional
Short one-liner shown under the project name on the workspace tile and in the project header — think tagline, not description. Plain text; no markdown.
color
string · optional
Theme colour for the project tile and board accents. Selected from a small palette in the project dialog. Stored as a token name (e.g. pink), not a raw hex value — the actual hue is resolved against the theme so dark and light modes look consistent.
Storage and ownership
These columns decide who can see and edit the project.
tenant_id
int · optional internally, effectively required for registered users
The workspace tenant (owning organisation) the project belongs to. Set automatically when a registered user creates a project. Anonymous / session-only projects can have a null tenant — those projects belong to a browser session, not an organisation.
workspace_id
int · optional
The workspace inside the tenant this project lives in. null means the tenant's default workspace — useful for backwards compatibility when a project was created before workspaces existed. Moving a project between workspaces is purely a workspace_id update; ownership (tenant_id) does not change.
user_id
string · optional
The user who originally created the project. Mainly used for audit and billing attribution. Workspace membership — not this field — controls access. Transferring a project to a new owner is supported via the project settings dialog.
session_id
string · optional
For anonymous try-Mockomat-without-signing-up projects. Holds the browser session ID that owns the project. As soon as the visitor signs up, the project is migrated to that user's tenant and session_id is cleared.
Publication & visibility
These columns control whether the project is private, listed publicly, or featured as a blueprint.
visibility
boolean · required · default false
When false (the default), the project is private to its tenant. When true, the project is published as a public blueprint — visible on mockomat.com/blueprints and importable by other users.
WARNING
Publishing is an admin-only operation, available through the Admin Zone tab of the project dialog. Publication is one-way until an admin unpublishes; the public listing is generated from the published copy, not the live project.
complexity_level
enum · optional
Difficulty rating shown next to a published blueprint (beginner, intermediate, advanced). Helps prospective users self-select. Only used when visibility is true.
teaser
text · optional
Two-to-three sentence sales pitch that appears on the public blueprint listing. Plain text; markdown is rendered as plain characters. Only relevant when visibility = true.
description
text · optional · markdown
Long-form description shown on the blueprint detail page. Supports inline markdown for emphasis, lists, and headings (no images). Empty by default for private projects.
display_order
int · optional
Integer sort key used to rank published blueprints inside their section. Lower numbers come first. Leave empty to use the default chronological order.
cover_image
string · optional
URL of the light-mode cover image for the blueprint listing (1200×630 recommended). Uploaded through the cover-image dropzone in the Admin Zone tab. Only used when visibility is true.
cover_image_dark
string · optional
Same as cover_image but for dark-mode display. When unset, the light-mode image is reused.
Sharing & collaboration
These columns control read-only preview links and read-write collaboration links shared with people outside your workspace.
preview_access
enum · required · default DISABLED
Controls whether a public, read-only preview link is generated for this project.
| Value | Meaning |
|---|---|
DISABLED | No preview link. Project is only visible to workspace members. |
PUBLIC | Anyone with the link can browse the project (no edits). |
TOKEN | Same as PUBLIC, but the URL includes a random token; rotating the token invalidates old links. |
preview_token
string · optional
Random opaque token appended to the preview URL when preview_access is TOKEN. Regenerated via the Regenerate token button; old URLs stop resolving immediately.
collaboration_access
enum · required · default DISABLED
Controls the read-write collaboration link — the one you share with people who should be able to edit the project even though they aren't formal workspace members.
| Value | Meaning |
|---|---|
DISABLED | No collaboration link. |
LINK | Anyone with the link can join. |
PASSWORD | Same as LINK, plus a password gate. |
WARNING
A collaboration link grants write access. Use PASSWORD and a TTL (see below) for anything beyond a quick pairing session.
collaboration_token
string · optional
The token portion of the collaboration URL. Rotating it (via the Regenerate token button) instantly invalidates all outstanding collaboration links.
collaboration_password
string · optional
When collaboration_access is PASSWORD, the password collaborators must enter to join. Stored hashed; never returned by the API.
collaboration_ttl_hours
int · optional
Hours the collaboration link stays valid after creation. Lets you hand out a link that auto-expires (e.g. 24h, 1 week, until cancelled). The expiry is computed at link creation and stored in collaboration_expires_at.
collaboration_expires_at
datetime · optional
Concrete expiry timestamp for the active collaboration link. After this moment, the link is no longer accepted; collaborators must be re-invited with a fresh link.
Board state
The Mockomat modelling board persists its viewport so opening a project returns you to the same zoom and pan as last time.
board_zoom
float · optional
Last zoom level the user had on the board (e.g. 1 = 100%, 0.5 = 50%). Auto-saved while modelling; rarely edited by hand.
board_pan_x · board_pan_y
float · optional · float · optional
Last pan offsets of the board viewport, in pixels. Saved alongside board_zoom.
Internals
These columns exist for the runtime and aren't meant to be edited in the dialog. They're documented here for integrators and support.
mock_token
string · required
Legacy internal token, kept for database compatibility. It does not authenticate anything: consumers call /mock/{slug}/graphql with an API key of the project, guest projects with their preview share token.
models
string · required
Snapshot of the project's modelling schema (tables + attributes + relations) used by the runtime. Maintained automatically as you edit the board.
queries
string · required
Snapshot of the project's GraphQL query surface used by the runtime. Regenerated whenever the model or API design changes.
id · created_at · updated_at · deleted
int · required · datetime · required · datetime · required · boolean · required
Inherited from BaseEntity. Internal primary key, auto-timestamps, and the soft-delete flag. Active queries always filter deleted = false, so deleting a project doesn't physically remove the row — it makes the project invisible to everyone except admins running undelete tooling.
Related tables
The project domain has two sibling tables that complete the picture:
project_collaborators— one row per collaborator who joined via a collaboration link. Tracksjoined_via(link vs. password) and when they joined.project_langs— translated copies of the human-facing fields (name,subtitle,description,teaser) for published blueprints. Auto-managed; end users don't editproject_langsdirectly.