Validation and Review
How Szum checks chart definitions for structural errors, semantic problems, recoverable warnings, and safer canonical patterns.
Szum validates the chart. Structural validation confirms that the configuration follows the current schema. Semantic validation then checks whether its fields, values, scales, marks, labels, colors, and theme settings can produce a renderable result.
The same compiler runs before rendering, saving, publishing, updating, or inserting a chart. The web editor and Figma plugin present its findings in Review; the API and MCP server return them as structured diagnostics.
Three kinds of findings
| Severity | Meaning | Result |
|---|---|---|
error | The current definition cannot produce a valid chart. | The invalid change is blocked before rendering or another side effect. |
warning | The chart can render, but some input was omitted or needs attention. | The chart remains usable and the warning stays visible. |
suggestion | The chart works, but Szum has a safer or more canonical first-class way. | Nothing changes until the suggestion is applied explicitly. |
Validation is identical on every plan. A paid plan can change presentation, limits, or workflow conveniences, but never whether a chart is considered valid.
Errors block the invalid definition
Errors cover cases such as missing required fields, incompatible values or scales, unsupported color channels, duplicate mark identities, invalid geometry, and charts with no usable rows.
Strict boundaries reject the invalid definition before a render, save, publication, update, or Figma insertion. Authoring surfaces keep the last successfully compiled chart visible while you repair the current Source or Data draft, so a temporary mistake does not replace the last valid result.
Warnings preserve usable work
A warning means Szum can still produce the chart. If one row is missing a required value while other rows remain usable, the compiler can omit that row, render the rest, and report exactly what was skipped. Warnings never disappear merely because the chart rendered successfully.
Review the warning before publication or automation. In an agent workflow, warnings require explicit user approval rather than being silently ignored.
Suggestions are explicit
Suggestions identify working but non-canonical definitions. For example, a separate text mark may duplicate labels already supported by a bar mark. The built-in label property participates in responsive placement and interaction, so Szum can recommend that first-class form.
The compiler never rewrites the submitted definition automatically. In the web editor or Figma plugin, Apply suggestion verifies the fix against the current chart and commits it as one undoable change. The validation API and MCP tools return a complete suggestedConfig so external clients do not need to interpret an internal patch.
Apply the complete replacement, then validate it again. Szum returns at most one safe replacement at a time.
Use Review in authoring tools
In the web editor and Figma plugin, Review is the complete finding surface for changes made through Data, chart controls, labels, themes, or Source.
- Errors keep the last valid chart visible but block publishing or insertion of the invalid draft.
- Warnings commit normally and remain visible for review.
- Suggestions can be inspected and applied explicitly.
Source may also show an immediate editing error, but Review remains the single place that collects the complete semantic result.
Validate from code or an agent
Use POST /validate for a public, free, read-only check that does not render, save, or consume a render allowance. The response separates blocking errors from the complete diagnostics list and may include suggestedConfig.
AI agents can use validate_chart for the same contract. Validate a generated or changed definition once before its next render, save, or update. A successful render already preflights that exact definition, so repeating validation while it remains unchanged is unnecessary.
What validation does not prove
Szum verifies the chart definition it receives. It does not verify that the source data is true, that a chosen statistic answers the right question, or that the resulting chart is an honest interpretation of the subject. Those decisions still require editorial judgment.