Older config compatibility

New integrations should send 2026-09-26 documents. Validation, rendering, save, and update still accept the documented subset of 2026-03-20 configs.

An accepted older config is converted to a current ChartDocument before it is validated, rendered, or saved. The compatibility result says whether that conversion was 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 output format.

Conversion never drops primary rows, picks one of several competing datasets, or turns a layer it cannot map into a decoration.

Conversion classifications

The write column applies when an API or MCP client sends the older config itself. For lossy input, acceptLosses must list every loss code the conversion returned; a request missing one fails with loss_approval_required, and a code that is not a loss code fails with unknown_loss_code. If you change the config, validate it again, because its loss codes can change too.

In the web editor and the Figma Source drawer, Migrate chart replaces a convertible older definition with a current document, including when conversion reports losses. There is no per-code acceptance step. When conversion is unavailable, the panel says why and leaves the original definition untouched. Supported older saved charts keep opening without their stored definition being rewritten.

Loss codes

• attribution_preference_dropped – attribution now follows your plan and delivery surface, so an authored preference is dropped.
• annotation_style_reduced – the annotation survives, but an older style option has no current equivalent.
• area_orientation_reduced – a horizontal area becomes a vertical area.
• bar_label_style_reduced – bar labels survive, but some layer-specific styling does not.
• category_label_format_reduced – a category axis format cannot also keep a separate label format.
• font_weight_dropped – a font weight that does not resolve to a number falls back to the theme default.
• font_weight_rounded – a font weight between the supported steps is rounded to the nearest of 100–900.
• layer_data_consolidated – compatible per-layer datasets are merged into the single data table; every row is kept.
• mark_paint_reduced – an independent paint setting has no equivalent on the current chart type.
• mark_presentation_reduced – compatible marks differ in another presentation option that cannot be kept per mark.
• path_style_reduced – styling on an absorbed line or area path differs from the path that is kept.
• point_style_reduced – line point coverage or styling cannot be represented uniformly.
• tick_density_dropped – tick density has no current setting, so axes use their automatic ticks.
• value_format_reduced – one value format replaces several differing older formats.
• wide_values_normalized – several older value fields become current wide values.

These are all the loss codes for converting 2026-03-20 to 2026-09-26.

Unsupported codes

• invalid_source_semantics – the older config is invalid under its own 2026-03-20 rules, so there is nothing to convert. The accompanying diagnostic codes name the problem; most often, a mark references a field its rows do not contain.
• no_primary_chart – the config has no primary chart mark. Rules, text, and other decorations cannot stand alone.
• mixed_primary_families – the marks resolve to more than one chart type. Bars or areas combined with a line do convert when both name the same field through their color channel (fill and stroke), share the same x and y, and cover different series values: the result is one chart that draws the line’s series as a promoted line. Otherwise, split the marks into separate charts, or express a flat threshold as a reference line.
• incompatible_primary_composition – the marks belong to one chart type but cannot form one chart: for example, their mark types or category fields differ, a pie or scatter chart has more than one primary mark, or wide values repeat a field.
• incompatible_axis_semantics – an axis scale type is not one the target chart type accepts, such as linear or log positioning for bars.
• incompatible_color_semantics – the color channel cannot become one series or category encoding: it uses a field that is neither, repeats the value field, colors a non-bar chart by its category, or accompanies wide values.
• incompatible_decoration – a rule or text layer has no current reference or annotation equivalent.
• unsupported_presentation – a theme, typography, sizing, or format option has no current equivalent, or the converted document does not compile.

Unsupported input returns its stable code. If it came from storage, the original bytes stay unchanged, so nothing is lost.

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 the config and its data in a current ChartDocument whose version matches the config’s.

An integration that cannot update right away can keep sending the supported config subset for validation, rendering, save, and update. Direct API and MCP writes report any required loss codes before anything is written.