Validation and compatibility

Szum validates chart meaning before rendering or saving. Public HTTP and MCP responses project compiler findings into stable diagnostic codes. Studio and Figma retain the detailed internal findings for editing and repair.

How validation works

Every durable or renderable input follows the same sequence:

1. identify the input shape and version;
2. parse it without mutating the submitted value;
3. convert a supported older config when necessary;
4. validate the current document’s chart semantics;
5. return the current document plus diagnostics, or a stable failure.

Three kinds of findings

Errors block invalid input

Errors mean the chart cannot be used safely. Examples include a missing required field, an incompatible value type, an invalid scale for a chart type, or an unsupported older chart composition.

Rendering, publishing, saving, and updating stop before quota or storage effects.

Warnings preserve usable work

Warnings flag a real concern but leave the chart renderable. Authoring tools keep the chart visible. MCP render and write actions require acknowledgement of the exact submitted value before they continue; changing the chart invalidates that acknowledgement. HTTP requests need no acknowledgement: /validate lists warnings and image renders report them in X-Chart-Diagnostics, but saves and updates succeed without returning them. Validate first if your product needs a review step.

Suggestions identify improvements

Suggestions are optional. They can identify a clearer field role, redundant setting, or simpler representation. They never block output and are never applied automatically.

Fixes are explicit and verified

When a deterministic fix exists, validation may return one complete, validated suggestedDocument. Review the proposed changes before using it as a whole-document replacement; validate again only if you modify it.

Every public suggested document has passed complete structural and semantic validation. Incremental repairs that leave blocking findings remain internal to the editor and are not returned as public replacements.

Response shape

POST /validate and validate_chart are free and read-only. Responses contain valid, one diagnostics array, and optionally one complete suggestedDocument. An older config also includes compatibility when conversion is attempted. There is no duplicate errors array or top-level message.

{
  "valid": false,
  "diagnostics": [
    {
      "code": "incompatible_data",
      "severity": "error",
      "path": "/config/values/field",
      "relatedPaths": [],
      "message": "Field \"revenue\" is missing from 1 of 1 data row. Every referenced field must exist on every row.",
      "details": {
        "reason": "data_field_missing",
        "affectedRows": 1,
        "field": "revenue",
        "roles": ["value"],
        "rowCount": 1,
        "samplePaths": ["/data/0/revenue"]
      }
    }
  ]
}

Use diagnostic code and path for program behavior. Messages are written for people and may improve over time. Fixability is independent from severity: an error or suggestion may carry a complete replacement.

Version errors identify the missing or invalid field: /version or /config/version. Document version must match config.version. Raw HTTP and MCP do not fill either field automatically. Wrap a standalone data-free config as { version, config, data } for validation, rendering, or saving.

The public codes are invalid_structure, invalid_preference, incompatible_data, incompatible_scale, duplicate_identity, unresolved_decoration, render_adjustment, and workspace_rule. Paths are RFC 6901 JSON Pointers: "" is the root; ~ and / within a field name become ~0 and ~1. details.reason carries the more specific finding. Any release can add codes, reasons, and detail fields, so handle a diagnostic you don’t recognize by its severity, path, and message.

Validation checks structure and semantics without laying out an image. Render warnings, such as suppressed labels, a subtitle or legend hidden on a small canvas, or category names too crowded to read, become available during rendering. MCP previews collect them with semantic warnings before quota or transient storage, and require acknowledgement of the complete warning set. Image responses carry render findings as percent-encoded JSON in X-Chart-Diagnostics; SDK renderWithMetadata decodes them into diagnostics.

Compatibility results

When the input is an older config, the response includes a compatibility object with its classification (exact, normalized, lossy, or unsupported) and lossCodes; unsupported input also carries unsupportedCode. Current documents have no compatibility object. Older config compatibility explains each classification and lists every loss and unsupported code.

Review in authoring tools

Studio and Figma collect current findings in Review. Invalid source edits do not replace the last valid preview. Safe actions replace the complete verified document as one undoable action, preserving document history.

Workspace chart rules

A Team workspace can hold every chart to house rules. Admins set each rule on the workspace’s Rules page:

A finding uses the workspace_rule code, with the rule in details.reason; an allowed_themes finding also lists the themes the workspace accepts in details.allowedThemes, shaped like those of GET /api/chart-rules, and an allowed_chart_types finding lists the chart types it accepts in details.allowedChartTypes. Warn adds a warning. Block adds an error and refuses publishing, updating, moving a chart into the workspace, and rendering an image of an unsaved chart with POST /chart or MCP render_chart. Drafts always save, and published charts keep serving until their next update, when the rules apply to them.

Every chart already gets a warning when a length leaves out zero, so that rule is always on and its switch decides whether it also blocks. The required title, caption, and accessibility description start Off; text made only of spaces counts as missing.

The limits are Szum’s, not a setting. Past five slices a pie’s angles get hard to compare, and past six colors they start to blur together. A pie counts the slices it draws, so a zero slice doesn’t count. Column, bar, line, area, and scatter charts count the colors they draw: each series or group colored from the theme’s palette is its own color, and colors you map in color.range count once each, so a highlighted line among eleven gray ones uses two. The limits apply once the chart compiles.

Charts use allowed themes keeps a workspace’s charts in the looks its admins pick: any of the workspace’s shared themes and Szum’s built-in themes. A chart passes when its theme matches an allowed one exactly, so a chart linked to an allowed shared theme passes, and a built-in theme with the chart’s own customization doesn’t. A chart that sets no theme is checked in the workspace’s default theme, the one a save gives it. Turning the rule on needs at least one allowed theme; if every allowed shared theme is later deleted, the rule stops checking until an admin picks again.

Charts use allowed chart types keeps a workspace to the chart types its admins pick. Turning it on starts with every type ticked, so admins untick the ones the workspace doesn’t use. At Block, the editor’s chart type picker closes the others.

Szum checks a workspace’s rules wherever it knows the workspace: Review in Studio and Figma, POST /validate with an API key, validate_chart on a signed-in MCP connection, and every save, update, move, and render. GET /api/chart-rules returns the levels and allowed themes in force. Rules stop applying when a Team plan’s grace period ends.

Limits of validation

Validation checks contract shape and chart semantics. It cannot prove that a number is factually correct, that a chosen chart answers the intended question, or that a public preview is appropriate for sensitive data. Those remain author and product decisions.

Validation also has no side effects: it reserves no render quota, creates or publishes nothing, and does not test a downstream consumer.