# Workspace item and surface types _Every kind of item in the workspace tree, which kinds are surfaces, what they open, and where they can nest._ Canonical: https://snoze.dev/help/workspace-items/ A workspace item is the named, ordered entry that appears in navigation. Most items point at a separate product resource through `targetId`: the item says where something lives and the target contains what opens. A Folder is the one targetless kind. Items may sit at the workspace root or inside a Folder or a mounted provider folder. They cannot nest directly inside a page, database, dashboard, or other ordinary item. Moving a folder inside its own descendants is rejected. ## Canonical contract lists Canonical contract values: - `page` - `note` - `dashboard` - `canvas` - `view` - `form` Canonical contract values: - `page` - `dashboard` - `canvas` - `view` - `form` Canonical contract values: - `folder` - `page` - `note` - `dashboard` - `canvas` - `view` - `form` - `database` - `file` - `data_source` - `action` - `automation` - `external_resource` - `calendar` Canonical contract values: - `folder` - `page` - `dashboard` - `canvas` - `view` - `form` - `database` - `file` - `data_source` - `action` - `automation` - `external_resource` Canonical contract values: - `folder` - `page` - `database` - `dashboard` - `form` - `automation` - `canvas` ## Item kinds ### Folder `folder` A Folder organises other workspace items. It has no `targetId`; its item row is the resource. Folders and mounted provider folders are the only legal parents. A Folder can be saved as a template, in which case the template can include its portable descendant tree. ### Page `page` A Page item points at a `page` surface. The surface owns an ordered tree of page blocks, publishing settings, and page metadata. Pages can contain prose, media, layouts, and live workspace embeds. A Page can be created and used as a template root. ### Note `note` A Note points at a legacy `note` surface and uses the same block model as a Page. Existing notes remain readable and editable, but `note` is deliberately absent from the creatable surface and item lists: new writing surfaces are Pages. Notes are not template roots. ### Dashboard `dashboard` A Dashboard item points at a `dashboard` surface. It uses page blocks placed on a two-dimensional grid and adds tabs, parameters, and theme settings. A Dashboard can be created and saved as a template root. ### Canvas `canvas` A Canvas item points at a `canvas` surface. Its target stores positioned, rotated, layered elements rather than page blocks. A Canvas can be created and saved as a template root. ### View `view` A standalone View item points directly at a row in `views`, not at a surface. That row belongs to one database, so the standalone item and the database tab open the same saved filters, sorts, grouping, layout, and field settings. A new View item may briefly have no target while its source is being selected. Views can be created but are not template roots. ### Form `form` A Form item points at a `form` surface. The form configuration selects a target database, exposes supported database fields as questions, and controls steps, theme, and public collection settings. A Form can be created and saved as a template root. ### Database `database` A Database item points at a database row. The target owns the field schema, records, and saved views. Record bodies are separate block surfaces and are not workspace items of their own. A Database can be created and saved as a template root. ### File `file` A File item points at a file row containing the uploaded asset's metadata and storage reference. File fields on database records refer to uploaded files; they do not turn every attachment into a nested workspace item. Files can be created but are not template roots. ### Data source `data_source` A Data source item points at a configured data-source row. It describes an external or synchronised source and may manage a target database. Snoze hides a managed database's duplicate database item from normal listing so the source is the navigation entry. Data sources can be created but are not template roots. ### Action `action` An Action item points at a saved action row. The target contains one typed operation and its settings; it can be run directly, from a button, or from an automation. Actions can be created but are not template roots. ### Automation `automation` An Automation item points at an automation row. The target owns the trigger, immutable published versions, draft graph, and run history. Automations can be created and saved as template roots. ### External resource `external_resource` An External resource item points at an external-resource placement, not at the provider object directly. The placement retains the connection and external identity needed to open the connected item. When its provider resource has the `folder` surface kind, other workspace items may nest under it. Availability and behaviour depend on the connected provider. External resources can be created but are not template roots. ### Calendar `calendar` Calendar is the system-owned access-control root for the permanent Calendar surface. People do not create it and it does not appear as an ordinary item in the workspace tree. It is neither a surface kind in the block-surface contract nor a template root. ## Item metadata and targets Every item also carries its workspace and item IDs, title, optional parent, icon and colour, order, archive state, access mode (`open` or `restricted`), free-form metadata, and timestamps. Except for Folder and the temporary unbound View state, an item must have a target of the matching kind in the same workspace. A target can be mounted by only one item of a given kind. The surface vocabulary is narrower than the item vocabulary: Page, legacy Note, Dashboard, Canvas, View, and Form are called surface kinds by the shared contract. View is the exception in persistence: its workspace item targets a view row rather than a block surface.