Dokumentformate und Migration

Document Serialization & Migration

Use this skill when designing saved document JSON/AST formats, validating persisted editor payloads, migrating legacy document versions, or generating HTML/Markdown/PDF/email exports.

Separate Editable Source Document from Derived Exports

1. Persist the Structured Source Model, Not Rendered Output:
   • Always save the canonical structured document (schemaVersion, root blocks, attributes, marks) as the authoritative source of truth.
   • Treat rendered HTML, email MJML/table HTML, Markdown, PDF, or plain-text search indexes as derived outputs generated from the structured document. Never try to reconstruct complex editor state by reverse-parsing exported presentation HTML when a structured format exists.
2. Explicit schemaVersion & Server/Client Validation:
   • Include an explicit integer schemaVersion at the root of every persisted document and local draft.
   • Validate document payloads on load and on server save: verify required node fields, valid block types, allowed nesting, and attribute types.

Safe Schema Evolution & Unknown-Block Preservation

• Never Silently Drop Unsupported or Newer Block Types:
  • When an older client or partial editor loads a document containing a block type or attribute it does not yet recognize (or a plugin that is disabled), preserve the unknown block's raw data intact in an inert UnsupportedBlock / passthrough wrapper node rather than stripping it on load and deleting the user's content on the next autosave.
• Deterministic Version Migrations (v1 -> v2 -> v3):
  • Implement pure, idempotent migration functions per version step (migrateV1ToV2(doc)), tested with representative real-world documents.
  • Separate read-time migration from silent write-back: do not mark a newly opened document as dirty or overwrite the server record with a migrated format without explicit version tracking or user edit.

Export Fidelity & Round-Trip Safety

• When importing/exporting Markdown, HTML, or email templates, document accurately which rich blocks degrade gracefully in target formats (e.g., interactive callouts or multi-column layouts in email clients) and test round-trip serialization (parse(serialize(doc))) for all supported blocks.

Checklist

• Does every persisted document carry an explicit schemaVersion separate from derived HTML/Markdown/email exports?
• Are unrecognized or newer block types preserved in a safe passthrough node rather than silently deleted on load/save?
• Are format migrations pure, step-by-step, and tested against legacy document fixtures?
• Does loading and migrating a document avoid falsely marking the editor as modified before the user edits?