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; a deterministic error may offer an explicit fix. |
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 invalid definitions
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 identify canonical patterns
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.
Fixes are explicit and verified
Fixability is independent from severity. An error still blocks output even when Szum knows a deterministic repair; a suggestion remains non-blocking even when it offers the same kind of explicit action. Findings without a safe transformation remain manual.
For example, a logarithmic scale on a bar value axis is invalid because that axis requires a linear baseline. Review can offer Reset scale to Auto, remove the incompatible override, and verify that the replacement reduces the blocking errors without introducing a new one. Field errors can similarly offer a complete x/y remapping when exactly one compatible category/value assignment exists; ambiguous assignments remain manual. Szum never rewrites data or applies a repair automatically.
The compiler never rewrites the submitted definition automatically. In the web editor and Figma plugin, each fix has a specific action label and commits through the active chart, Source draft, or Data draft as one explicit change. If unrelated errors remain, the repaired draft stays blocked and Review presents the next result.
The validation API and MCP tools return a complete suggestedConfig for fixable errors or suggestions so external clients do not need to interpret an internal patch.
Apply the complete replacement, then validate it again. Szum returns at most one verified repair at a time, and valid remains false while any blocking error remains.
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 and block publishing or insertion; fixable errors expose an explicit repair.
- Warnings commit normally and remain visible for review.
- Suggestions can be inspected and applied explicitly when a fix is available.
Source may also show an immediate editing error, but Review remains the single place that collects the complete semantic result.
Validation from code and agents
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.
Limits of validation
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.