Earlier formats
Validation
The checks every ui spec passes, the messages agents get back, and how artifacts_validate catches problems before saving.
When validation runsLink to this section
- Before saving, when the agent calls
artifacts_validate. Nothing is saved. - On save, in
artifacts_create,artifacts_update, and the web editor. A spec with errors is refused with the same report. - While you type, in the web editor and the playground.
- On render, again, so a page never trusts what is stored. Props that hold dynamic values are checked once they resolve.
All four use one function, validateUiSpec in src/lib/ui/validate.ts. It checks the JSON, the limits, the version, every element's props against its schema, cross-field rules, the element tree, events and actions, and json-render's own structural checks.
artifacts_validateLink to this section
Agents should validate before every save. It costs one read call, reports every problem at once, and each line names the element and says how to fix it.
{
"name": "artifacts_validate",
"arguments": {
"kind": "ui",
"content": "{\"version\":1,\"root\":\"page\",\"elements\":{\"page\":{\"type\":\"Stack\",\"props\":{\"gap\":\"md\"},\"children\":[\"title\",\"body\"]},\"title\":{\"type\":\"Heading\",\"props\":{\"text\":\"Hello, artifacts\",\"level\":1}},\"body\":{\"type\":\"Text\",\"props\":{\"text\":\"This page is one JSON object: a root key and a flat map of elements.\"}}}}"
}
}Valid ui content. It is ready to save.Errors and warningsLink to this section
- Errors stop a save. Most errors belong to one element: the page still renders, and that element shows a small notice in its place.
- Some errors stop the whole page from rendering, because there is no safe way to draw it:
invalid_json,too_large,not_object,too_deep_json,unsafe_path,unsupported_version,missing_root,root_not_found,too_many_elements,invalid_elements,shared_child,root_is_child,too_deep,nested_repeat,too_many_rendered,repeat_too_long,typed_text_in_link. - Warnings never stop a save: a missing
version, unknown props (ignored), children on a leaf (hidden), and elements the root never reaches (ignored).
Real messagesLink to this section
Each block below is the exact text artifacts_validate returns, computed from the validator when these docs were built.
{
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Stack",
"props": { "gap": "md" },
"children": ["title", "chart", "link", "widget", "notes"]
},
"title": { "type": "Heading", "props": { "text": "Fix me", "level": 1 } },
"chart": {
"type": "Chart",
"props": {
"type": "line",
"labels": ["Mon", "Tue", "Wed", "Thu"],
"series": [{ "name": "Deploys", "values": [3, 5, 4] }]
}
},
"link": {
"type": "Link",
"props": { "label": "Run this", "href": "javascript:alert(1)" }
},
"widget": { "type": "Gauge", "props": { "value": 72 } },
"notes": {
"type": "Text",
"props": {
"text": "Read the issues under the editor, fix each one, and watch the page render."
}
}
}
}Invalid ui content. Fix these and validate again:
- Error: Element "chart" (Chart): Series "Deploys" has 3 values but there are 4 labels. Give each series one value per label (use null for a gap).
- Error: Element "link" (Link): props.href: Use an absolute http, https, or mailto URL, or leave `href` out for a link that goes nowhere.
- Error: Element "widget": unknown component "Gauge". Use one of: Section, Stack, Grid, Card, Tabs, Accordion, Separator, Box, Heading, Text, Markdown, Code, Callout, Badge, List, Steps, Link, Quote, Icon, Avatar, AvatarGroup, Kbd, Rating, Table, Metric, Chart, KeyValue, Progress, Timeline, Diagram, Board, Calendar, Checklist, Checkbox, Select, Switch, Slider, Button, Input, Textarea, Image, File, Placeholder.Valid ui content, with warnings:
- Warning: Add "version": 1 at the top level so the spec keeps its meaning as components evolve.
- Warning: Element "page" (Stack): prop "padding" is not a Stack prop and is ignored. Known props: direction, gap, align.
- Warning: Element "title" (Heading) does not show children, so its 1 children are hidden. Wrap them in a Stack or Card instead.
- Warning: Elements not reachable from the root are ignored: draft.Invalid ui content. Fix these and validate again:
- Error: The content is not valid JSON: Expected double-quoted property name in JSON at position 32 (line 1 column 33). A ui artifact is one JSON object: { "version": 1, "root": "…", "elements": { … } }.Fix it yourself
Spec limitsLink to this section
| Limit | Value |
|---|---|
| Spec size | 200,000 bytes of JSON |
| Elements | 500 |
| Nesting depth | 20 levels, root is 1 |
| Items per repeat | 200 |
| Rendered elements | 5,000, once repeats expand |
| JSON nesting anywhere | 64 levels |
| Element key length | 100 characters |
| Issues reported at once | 25, then a count of the rest |
Props have their own limits, such as 200 points per series or 500 table rows. Each component page lists them in its props table.
Issue codesLink to this section
Each issue has a code, a severity, a message, and usually an elementKey. Agents only need the message; the codes are stable names for tooling.
| Code | Severity | Stops the page | Meaning |
|---|---|---|---|
| invalid_json | error | Yes | The content is not JSON. |
| too_large | error | Yes | The spec is over the byte limit. |
| not_object | error | Yes | The JSON is not an object. |
| too_deep_json | error | Yes | JSON nests too deep anywhere in the spec. |
| unsafe_path | error | Yes | A key or state path uses __proto__, constructor, or prototype. |
| unsupported_version | error | Yes | version is not a supported number. |
| missing_root | error | Yes | root is missing. |
| root_not_found | error | Yes | root names a key that does not exist. |
| too_many_elements | error | Yes | More elements than the limit. |
| invalid_elements | error | Yes | elements is not an object. |
| shared_child | error | Yes | One element has two parents. |
| root_is_child | error | Yes | The root is listed as a child. |
| too_deep | error | Yes | Elements nest deeper than the limit. |
| nested_repeat | error | Yes | A repeat sits inside another repeat. |
| too_many_rendered | error | Yes | Repeats expand past the rendered-element limit. |
| repeat_too_long | error | Yes | One repeat has more items than the limit. |
| typed_text_in_link | error | Yes | A text field is bound to state and a link address, Markdown, Steps, or Diagram prop uses an expression. Typed text must never reach a link. The error names every bound text field; past 4 of them it names the first 3 and counts the rest. |
| invalid_props | error | No | A prop fails its schema or a cross-field rule. |
| unknown_component | error | No | The type is not in the catalog. The element renders nothing. |
| invalid_element | error | No | An entry in elements is not an object with a type. |
| missing_child | error | No | children names a key that does not exist. |
| children_mismatch | error | No | Tabs, Accordion, or a Grid with `spans` has a different number of children and entries, or a Grid has both `spans` and `repeat`. |
| invalid_event | error | No | on uses an event the component does not emit. |
| invalid_action | error | No | on runs an action other than the five state actions. |
| unsupported_expression | error | No | A prop uses $computed. |
| unsupported_field | error | No | The element has watch or slots. |
| invalid_key | error | No | An element key is too long. |
| invalid_state | error | No | state is not an object. |
| structure | error | No | json-render's own catalog check failed. |
| missing_version | warning | No | The spec has no version field. |
| unknown_prop | warning | No | A prop the component does not have. It is ignored. |
| leaf_children | warning | No | A component that does not show children has some. |
| repeated_pairing | warning | No | Tabs or an Accordion repeats its child with `repeat`, so its panels may not line up with its entries. It still draws. |
| orphaned_element | warning | No | An element the root never reaches. It is ignored. |
| announce_follows_typing | warning | No | A Text or Callout with announce (true, or an expression that can be true) shows words read from state that a text field writes, so it would be spoken on every key. |
json-render's own structural checks can add a few more codes; their messages name the element too.