Older config compatibility

New integrations should use 2026-09-26 documents. Validation, rendering, save, and update operations continue to accept the documented subset of 2026-03-20 configs.

When accepted, an older config is converted to the current ChartDocument before it is validated, rendered, or saved. The compatibility result tells you whether that conversion is exact, normalized, lossy, or unsupported.

Chart mapping

An older config needs one unambiguous primary chart. Layer order does not decide which layer wins.

What conversion preserves

For supported input, conversion carries forward:

• primary data and its row order;
• semantic channels, series, grouping, and aggregation where representable;
• supported scale types, domains, tick formats, locale, theme, and text;
• native labels, line points, area strokes, annotations, and compatible reference rules;
• categorical color domains and ranges where their meaning is unambiguous;
• canvas or plot sizing and render output policy.

Conversion never silently truncates primary data, selects one of several competing datasets, or turns an incompatible layer into decoration by guesswork.

Conversion classifications

The write column applies when an API or MCP client submits the older config itself. For lossy input, acceptLosses must name every returned code for that exact value. If the config changes, validate it again.

In the web editor and Figma Source, Migrate chart replaces a convertible older definition with a current document when you choose the action, including when conversion reports reductions. There is no per-code acceptance step. If conversion is unavailable, those controls explain why and leave the original definition untouched. Supported older saved charts continue to open without changing their stored definition.

Loss codes

• attribution_preference_dropped – attribution is now delivery and plan policy rather than authored chart semantics.
• annotation_style_reduced – annotation meaning survives but an older style option has no current equivalent.
• area_orientation_reduced – a horizontal legacy area is normalized to the current vertical area family.
• bar_label_style_reduced – native bar-label meaning survives but some layer-local styling does not.
• category_label_format_reduced – an axis-only category format cannot also preserve a distinct label presentation.
• layer_data_consolidated – compatible layer-local datasets are consolidated into the one current data table.
• mark_paint_reduced – an independent paint channel has no equivalent on the current family.
• mark_presentation_reduced – compatible marks differ in another independent presentation option.
• path_style_reduced – absorbed line or area path styling differs from the retained path.
• point_style_reduced – line point coverage or styling cannot be represented uniformly.
• value_format_reduced – one current value formatter replaces differing legacy formatter routes.
• wide_values_normalized – multiple legacy value fields become current wide-value semantics.

These are the complete loss codes when converting 2026-03-20 to 2026-09-26.

Unsupported codes

• invalid_source_semantics – the retained config does not hold together on its own terms, before any conversion is attempted; the accompanying diagnostic codes name the underlying problem. A common case is a mark naming a field that its own rows do not contain.
• no_primary_chart – the config has no primary chart mark. Rules, text and other decorations cannot stand on their own.
• mixed_primary_families – the marks resolve to more than one chart family that cannot become one chart. Bars or areas combined with a line convert when both name the same field through their color channel (fill and stroke), share the same x and y, and cover disjoint series values: that becomes one seriesed chart whose named series are drawn as a line. Outside that shape, split the marks into separate charts, or, where the second family is a flat threshold, express it as a reference line.
• incompatible_primary_composition – the marks share a family but cannot be composed into one chart, because their mark types or their category fields differ.
• incompatible_axis_semantics – the source axis scale types are not among those the target chart family accepts.
• incompatible_color_semantics – the color channel cannot become one series or category encoding: it is keyed on a field that is neither, it repeats the value field, it colors a non-bar family by category, or it accompanies wide values.
• incompatible_decoration – a rule or text layer has no equivalent current reference or annotation.
• unsupported_presentation – a theme, typography or format option has no current equivalent, or the converted document does not compile against the current family.

Unsupported input returns a stable code. If it came from storage, the original bytes remain unchanged for recovery.

New integrations

Do not generate 2026-03-20 configs for new work. Use list_chart_types, the current ChartConfig JSON Schema, or the chart type reference, then place that config and its data in a current ChartDocument with matching document and config versions.

If an older integration cannot update immediately, it may continue sending the supported config subset for validation, rendering, save, and update. Direct API/MCP writes return any required loss codes before writing.