Orqestria Download
← Back to Internal system builders

Skill · Version 1.0.0

Document formats and migration

Preserves editable document meaning across serialization, format changes and exports, including content the current editor does not understand.

document-serialization-migration

Team members using this skill

See how it helps

When is it useful?

Use it when saved documents outlive editor releases or must move between rich and simpler formats.

What does it help you do?

  • Separates editable source documents from derived exports.
  • Preserves unknown blocks and validates versioned schemas.
  • Tests deterministic migrations and import-export fidelity.

Try asking this

Upgrade document format while preserving blocks from a newer editor. Open a document containing an unknown chart block, edit a paragraph and save. The chart's original data should survive the round trip unchanged.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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?

Included files 1

  • SKILL.md