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.

tools/calljson
{
  "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.\"}}}}"
  }
}
Result for a valid spectext
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.

A spec with three mistakesjson
{
  "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."
      }
    }
  }
}
Reporttext
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.
Warnings only: no version, an unknown prop, a leaf with children, an unreachable elementtext
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.
Not JSONtext
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

The first block is the "Broken: fix me" seed in the playground. Fix each line and watch the page appear.

Spec limitsLink to this section

LimitValue
Spec size200,000 bytes of JSON
Elements500
Nesting depth20 levels, root is 1
Items per repeat200
Rendered elements5,000, once repeats expand
JSON nesting anywhere64 levels
Element key length100 characters
Issues reported at once25, 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.

CodeSeverityStops the pageMeaning
invalid_jsonerrorYesThe content is not JSON.
too_largeerrorYesThe spec is over the byte limit.
not_objecterrorYesThe JSON is not an object.
too_deep_jsonerrorYesJSON nests too deep anywhere in the spec.
unsafe_patherrorYesA key or state path uses __proto__, constructor, or prototype.
unsupported_versionerrorYesversion is not a supported number.
missing_rooterrorYesroot is missing.
root_not_founderrorYesroot names a key that does not exist.
too_many_elementserrorYesMore elements than the limit.
invalid_elementserrorYeselements is not an object.
shared_childerrorYesOne element has two parents.
root_is_childerrorYesThe root is listed as a child.
too_deeperrorYesElements nest deeper than the limit.
nested_repeaterrorYesA repeat sits inside another repeat.
too_many_renderederrorYesRepeats expand past the rendered-element limit.
repeat_too_longerrorYesOne repeat has more items than the limit.
typed_text_in_linkerrorYesA 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_propserrorNoA prop fails its schema or a cross-field rule.
unknown_componenterrorNoThe type is not in the catalog. The element renders nothing.
invalid_elementerrorNoAn entry in elements is not an object with a type.
missing_childerrorNochildren names a key that does not exist.
children_mismatcherrorNoTabs, Accordion, or a Grid with `spans` has a different number of children and entries, or a Grid has both `spans` and `repeat`.
invalid_eventerrorNoon uses an event the component does not emit.
invalid_actionerrorNoon runs an action other than the five state actions.
unsupported_expressionerrorNoA prop uses $computed.
unsupported_fielderrorNoThe element has watch or slots.
invalid_keyerrorNoAn element key is too long.
invalid_stateerrorNostate is not an object.
structureerrorNojson-render's own catalog check failed.
missing_versionwarningNoThe spec has no version field.
unknown_propwarningNoA prop the component does not have. It is ignored.
leaf_childrenwarningNoA component that does not show children has some.
repeated_pairingwarningNoTabs or an Accordion repeats its child with `repeat`, so its panels may not line up with its entries. It still draws.
orphaned_elementwarningNoAn element the root never reaches. It is ignored.
announce_follows_typingwarningNoA 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.