field-relations

# Fields & Relations Complete reference for the `fields` and `relations` MCP tools — field types, interfaces, and relationship workflows. ## Fields Tool ### Creating Fields **Critical: `data` is ALWAYS an array**, even for a single field. ```text Tool: fields Input: { "action": "create", "collection": "posts", "data": [{ "field": "title", "type": "string", "meta": { "interface": "input", "note": "Post title", "required": true }, "schema": { "is_nullable": false } }] } ``` ### Reading Fields ```text Tool: fields Input: { "action": "read", "collection": "posts" } ``` Or read a specific field: ```text Tool: fields Input: { "action": "read", "collection": "posts", "field": "title" } ``` ### Deleting Fields ```text Tool: fields Input: { "action": "delete", "collection": "posts", "field": "deprecated_field" } ``` ## Field Types Reference | Type | Description | Typical Interface | |------|-------------|-------------------| | `string` | Short text (max 255) | `input` | | `text` | Long text (unlimited) | `input-multiline`, `input-rich-text-md`, `input-rich-text-html` | | `uuid` | UUID identifier | `input` (auto-generated for PKs) | | `hash` | Hashed value | `input-hash` | | `integer` | Whole number | `input` | | `bigInteger` | Large whole number | `input` | | `float` | Floating point | `input` | | `decimal` | Exact decimal | `input` | | `timestamp` | Date + time (with timezone) | `datetime` | | `datetime` | Date + time (no timezone) | `datetime` | | `date` | Date only | `datetime` | | `time` | Time only | `datetime` | | `boolean` | True/false | `boolean`, `toggle` | | `json` | JSON data | `input-code`, `select-multiple-dropdown` | | `csv` | Comma-separated values | `tags` | | `alias` | Virtual field (no column) | Used for O2M, M2M, M2A | ## Common Interface Mappings | Use Case | Type | Interface | Meta Options | |----------|------|-----------|--------------| | Short text | `string` | `input` | — | | Rich text | `text` | `input-rich-text-md` | — | | Dropdown | `string` | `select-dropdown` | `options.choices: [{text, value}]` | | Tags | `json` | `tags` | — | | Toggle | `boolean` | `boolean` | — | | Number | `integer` | `input` | — | | Currency | `decimal` | `input` | `options.prefix: "$"` | | Date picker | `datetime` | `datetime` | — | | Color picker | `string` | `select-color` | — | | Slug | `string` | `input` | `options.slug: true` | | Image (single) | `uuid` | `file-image` | `special: ["file"]` | | File (single) | `uuid` | `file` | `special: ["file"]` | ## Relationship Types ### M2O (Many-to-One) Example: Many posts belong to one author. **Step 1: Create the M2O field** (uuid type in the "many" collection): ```text Tool: fields Input: { "action": "create", "collection": "posts", "data": [{ "field": "author", "type": "uuid", "meta": { "interface": "select-dropdown-m2o", "special": ["m2o"], "display": "related-values", "display_options": { "template": "{{first_name}} {{last_name}}" } }, "schema": {} }] } ``` **Step 2: Create the relation:** ```text Tool: relations Input: { "action": "create", "collection": "posts", "field": "author", "data": { "collection": "posts", "field": "author", "related_collection": "authors", "schema": { "on_delete": "SET NULL" }, "meta": {} } } ``` ### O2M (One-to-Many) Example: One author has many posts. This is the reverse side of M2O — an alias field on the "one" collection. **The M2O side must exist first.** Then add an alias field to the "one" collection: ```text Tool: fields Input: { "action": "create", "collection": "authors", "data": [{ "field": "posts", "type": "alias", "meta": { "interface": "list-o2m", "special": ["o2m"], "display": "related-values" } }] } ``` Then create the relation from the O2M side: ```text Tool: relations Input: { "action": "create", "collection": "posts", "field": "author", "data": { "collection": "posts", "field": "author", "related_collection": "authors", "schema": { "on_delete": "SET NULL" }, "meta": { "one_field": "posts" } } } ``` ### M2M (Many-to-Many) Example: Posts can have many tags, tags can belong to many posts. **Step 1: Create junction collection:** ```text Tool: collections Input: { "action": "create", "data": [{ "collection": "posts_tags", "schema": {}, "meta": { "hidden": true, "icon": "import_export" } }] } ``` **Step 2: Create M2O fields in junction:** ```text Tool: fields Input: { "action": "create", "collection": "posts_tags", "data": [ { "field": "posts_id", "type": "uuid", "meta": { "hidden": true } }, { "field": "tags_id", "type": "uuid", "meta": { "hidden": true } } ] } ``` **Step 3: Create alias fields on both parent collections:** ```text Tool: fields Input: { "action": "create", "collection": "posts", "data": [{ "field": "tags", "type": "alias", "meta": { "interface": "list-m2m", "special": ["m2m"], "display": "related-values", "display_options": { "template": "{{tags_id.name}}" } } }] } ``` ```text Tool: fields Input: { "action": "create", "collection": "tags", "data": [{ "field": "posts", "type": "alias", "meta": { "interface": "list-m2m", "special": ["m2m"], "display": "related-values" } }] } ``` **Step 4: Create relations:** ```text Tool: relations Input: { "action": "create", "collection": "posts_tags", "field": "posts_id", "data": { "collection": "posts_tags", "field": "posts_id", "related_collection": "posts", "schema": { "on_delete": "CASCADE" }, "meta": { "one_field": "tags", "junction_field": "tags_id" } } } ``` ```text Tool: relations Input: { "action": "create", "collection": "posts_tags", "field": "tags_id", "data": { "collection": "posts_tags", "field": "tags_id", "related_collection": "tags", "schema": { "on_delete": "CASCADE" }, "meta": { "one_field": "posts", "junction_field": "posts_id" } } } ``` ### M2A (Many-to-Any) Polymorphic relation — items can relate to different collection types. Used for page builders, flexible content blocks. **Step 1: Create junction collection** with `item` (uuid) and `collection` (string) fields: ```text Tool: collections Input: { "action": "create", "data": [{ "collection": "page_sections", "schema": {}, "meta": { "hidden": true } }] } ``` **Step 2: Add junction fields:** ```text Tool: fields Input: { "action": "create", "collection": "page_sections", "data": [ { "field": "pages_id", "type": "uuid" }, { "field": "item", "type": "uuid", "meta": { "hidden": true } }, { "field": "collection", "type": "string", "meta": { "hidden": true } }, { "field": "sort", "type": "integer", "meta": { "hidden": true } } ] } ``` **Step 3: Add M2A alias on parent:** ```text Tool: fields Input: { "action": "create", "collection": "pages", "data": [{ "field": "sections", "type": "alias", "meta": {