Task description content
Stored Plate JSON contract — canonical field, allowed nodes, security, and write rules.
Task descriptions are a Plate rich-text document, not a markdown string. The in-app editor, REST (/api/v1), and MCP (planeward-task-*) share one store and one validator.
Canonical field
| Column | Type | Role |
|---|---|---|
descriptionContent | JSON array or null | Source of truth. What the editor persists. |
description | string or null | Derived plain text for search and API consumers. The editor does not write this column. |
descriptionContent: null (or omit on create) is an empty description. An empty document serializes to null.
Write rules (REST and MCP)
descriptionContentwins. When it is present,descriptionis ignored and the stored plain-text field is derived from the document.- Plain
descriptiononly when content is omitted. Each non-empty line becomes a paragraph node (type: "p"). - Sending
descriptionContent: nullclears both fields. - The server normalizes node
ids. Clients do not need to generate them. - Invalid documents are rejected. The API does not strip unknown types or unsafe URLs.
Document shape
The document is a JSON array of element nodes (Plate Value).
[
{
"id": "p1",
"type": "p",
"children": [{ "text": "Hello", "bold": true }]
}
]- Elements have
typeandchildren. - Text leaves have a
textstring. Marks are booleans on the leaf (bold,italic,underline,strikethrough,highlight). - Void nodes (
hr,img,video,file,media_embed,link_preview) still includechildren: [{ "text": "" }]. - Extra properties on allowed types are kept (Plate adds indent, table spans, and similar).
__proto__,prototype, andconstructorare rejected.
Allowed element types
These match the in-app task editor. Any other type is rejected (script, iframe, blockquote, h4, …).
| Type | Kind |
|---|---|
p | Paragraph. Also used for lists (see below). |
h1 h2 h3 | Headings |
hr | Horizontal rule |
a | Inline link. url required. |
code_block code_line code_syntax | Fenced code |
table tr td th | Tables |
img video file | Workspace media |
media_embed | YouTube / Vimeo only |
link_preview | Unfurled URL card |
Lists are not wrapper nodes. A list item is a paragraph (or heading) with indent (integer 0–24) and listStyleType:
{
"type": "p",
"indent": 1,
"listStyleType": "disc",
"children": [{ "text": "Item" }]
}Allowed listStyleType values: disc, circle, square, decimal, decimal-leading-zero, lower-alpha, upper-alpha, lower-roman, upper-roman, todo. Checklist items may set checked (boolean). Ordered lists may set listStart (integer ≥ 1).
Media and attachments
Workspace uploads store references, not file bytes, in the document:
{
"type": "file",
"attachmentId": "…",
"fileAssetId": "…",
"name": "brief.pdf",
"mimeType": "application/pdf",
"url": "",
"children": [{ "text": "" }]
}urlmay be""whenattachmentId/fileAssetIdpoint at workspace files. The product editor writes it that way.- A non-empty
urlonimg,video, orfilemust behttpswith no credentials.data:,javascript:, andhttpare rejected. media_embed.urlmust behttpsonyoutube.com,www.youtube.com,youtube-nocookie.com,www.youtube-nocookie.com,vimeo.com, orplayer.vimeo.com.
The public API does not upload files. Referencing attachmentId values you did not create in this workspace will not attach a downloadable file.
Platform announcements (staff /admin/announcements, not task API) reuse the same Plate shape. Inline images may set platformImageKey to an object under platform/announcements/<announcementId>/ in the images bucket; url is cleared on save and filled at display time. This field is announcement-only.
Link previews
{
"type": "link_preview",
"url": "https://example.com/post",
"title": "Example",
"description": "…",
"siteName": "Example",
"imageObjectKey": "workspaces/<workspaceId>/link-previews/<64-hex>.png",
"faviconObjectKey": null,
"fetchedAt": "2026-08-25T00:00:00.000Z",
"children": [{ "text": "" }]
}urlishttpsonly. The server refuses private, loopback, link-local, and credentialed hosts (SSRF protection).imageUrlandfaviconUrlare not allowed. Preview images are object keys underworkspaces/<workspaceId>/link-previews/only.- Title / description / site name are length-capped.
Hyperlinks
a.url must be http or https with no credentials. javascript:, data:, vbscript:, and file: are rejected.
Size and integrity limits
| Limit | Value |
|---|---|
| Serialized JSON | 100,000 characters |
| Nodes (walk of the tree) | 2,500 |
| Nesting depth | 16 |
| Children per node | 500 |
| Characters per text leaf | 20,000 |
| URL length | 2,048 |
The document must be a JSON array. Objects, strings, and non-object nodes are rejected.
Minimal examples
Paragraphs from plain text (description only):
[{ "type": "p", "children": [{ "text": "Ship the invoice flow." }] }]Clear the description:
{ "descriptionContent": null }
Planeward Docs