Rolling back Plotly after a figure schema upgrade: what breaks when figure['version'] no longer matches

1. What breaks when fig['version'] no longer matches the installed Plotly release?

Plotly stores a fig['version'] key that records the figure schema version used when the figure was serialized. When plotly.io.from_json loads a figure whose version is newer than the running library, the loader performs a compatibility check:

• It issues a UserWarning about the version mismatch.
• Any trace or layout attributes that the older library does not recognize are silently dropped.
• New trace types (e.g., scattergl, sunburst) are converted to the closest known type or removed entirely.
• References to layout templates that only exist in the newer schema fall back to Plotly’s default template, potentially changing colors, fonts, and default trace settings.

These changes occur even if the fig['version'] value is numerically equal to the installed Plotly version. The version field only guarantees that the figure was written by a *release* of Plotly, not that the *schema* is identical across releases. Minor releases often introduce new properties that do not increment the major version number but still break older clients.

2. Is a simple version check sufficient to guarantee a figure survives a downgrade?

No. Checking fig['version'] against the installed Plotly version only tells you that the figure was written by a *compatible* release. It does not account for schema changes that add new keys or trace types. The safest approach is to load the figure with the older library and then compare the keys before and after to detect any silent drops. If you need the data to survive, you must either keep the newer library or explicitly strip unsupported keys before serialization.

3. Does Plotly provide a supported downgrade path?

Plotly does not ship a dedicated downgrade helper. The recommended workflow when you must revert to an older library is:

1. Install the target older Plotly release (e.g., pip install plotly==5.13.0).
2. Load the newer figure with plotly.io.from_json and let the library discard unknown keys.
3. Re‑serialize the cleaned figure with plotly.io.to_json (or write_json) so that the file now matches the older schema.

Alternatively, manually prune unsupported keys before serialization if you need to preserve as much information as possible.

4. When is exporting a static snapshot a safe fallback?

If interactivity is not required after rollback, fig.to_image(static_plot=True) (or to_image(..., static_plot=True)) produces a PNG/SVG that reflects the visual state of the figure as rendered by the newer library. This approach:

• Preserves the visual appearance regardless of schema differences.
• Ignores template fallbacks because the image is rendered in the newer environment.
• Discards all interactivity (hover, zoom, click callbacks).

Use this method when you only need a static representation for documentation or archival purposes.

5. Practical verification steps

# 1. Create a figure with a trace type only available in Plotly 6.x
import plotly.graph_objects as go
fig = go.Figure(go.Scattergl(x=[1,2,3], y=[4,5,6]))
fig.write_json('new_figure.json')

# 2. Downgrade to Plotly 5.x
# pip install plotly==5.13.0

# 3. Load and inspect
import plotly.io as pio
fig_old = pio.from_json('new_figure.json')
print(fig_old.data)  # Trace type may be missing or converted
print(fig_old.layout)  # Template fallback may occur

After the round‑trip, compare fig_old.to_dict().keys() with the original to confirm which keys were dropped.

6. Summary of recommendations

• Never rely solely on fig['version'] for safe downgrade.
• Use re‑serialization with the older Plotly library to drop unsupported keys explicitly.
• Manually strip or transform unsupported attributes if you need to preserve data.
• Export a static image when interactivity can be sacrificed.
• Keep a copy of the original figure in the newer format if you may need to upgrade again later.