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 identify a meaningful concern while leaving the chart renderable. Authoring tools keep the chart visible. MCP render and write actions require explicit acknowledgement for the exact submitted value before continuing. Raw HTTP callers should validate first and decide how their product handles non-blocking findings.

Changing the chart invalidates that acknowledgement; validate the changed value again.

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",
      "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, and render_adjustment. Paths are RFC 6901 JSON Pointers: "" is the root; ~ and / within a field name become ~0 and ~1. Each code has a closed details object; reason carries the more specific finding.

Validation checks structure and semantics without laying out an image. Label-collision warnings 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

Conversion of an older config is classified as:

• exact when authored meaning carries over without normalization or loss;
• normalized when the current document is equivalent but canonicalized;
• lossy when supported meaning can render but named presentation details cannot be preserved;
• unsupported when choosing a current result would require guessing or dropping chart meaning.

The optional compatibility object contains classification and lossCodes. Unsupported input also contains unsupportedCode. Current input does not need this object.

Lossy input can be previewed with stable diagnostics. Durable writes require explicit acceptance of every returned loss code. Unsupported stored input remains byte-preserved and is not rewritten.

See older config compatibility for the supported chart mapping and complete loss and rejection codes.

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.

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 does not reserve render quota, create a chart, publish storage, or test a downstream consumer. It is deliberately side-effect free.