vyuhDiagram

Upgrade a saved document ​

Loading interactive example…Open in new tab ↗
Opening the live canvas…

Try Load without migration to see the legacy type rejected, then Import legacy cards to upgrade it. The upgrade preserves identities, text, ports and connections. Undo reverses the import; the invalid fixture leaves the drawing unchanged.

The host schema version is separate from the diagram JSON format version. Decode first, run the explicit migration chain, then publish the complete candidate through replaceDocument with a captured revision. No intermediate document is published. A host stores its schema version alongside the JSON; this example supplies that envelope in memory.

The fixture intentionally accepts only its known legacy card type. Production migrations must cover their actual supported schema and preserve or deliberately remap all references. Upgrade callbacks should perform no external side effects.

See Persistence and imports.

Source ​

dart
final exampleMigrations = DiagramDocumentMigrations(
  minimumSupportedVersion: 1,
  currentVersion: 2,
  steps: [
    DiagramDocumentMigration(
      fromVersion: 1,
      upgrade: (document) {
        return document.replaceElements([
          for (final element in document.elements)
            if (element is ShapeElement)
              switch (element.type) {
                'legacy.card' => element.copyWith(type: Shapes.card),
                _ => throw FormatException(
                  'Unknown legacy shape: ${element.type}',
                ),
              }
            else
              element,
        ]);
      },
    ),
  ],
);