The space export format

This is the developer reference for Wodo's space export format. If you just want to export or import a space, read Import and export instead — this page is for people writing tools against the format: converters from other trackers, auditing scripts, or their own backup tooling.

The format identifier is wodo-space-export-v2. The format evolves additively: new fields may appear, existing fields keep their meaning, and anything optional here may be absent in older files. An importer should ignore fields it doesn't recognize.

The two artifacts

A space exports two ways, and the import wizard accepts either:

• Data only — a single data.json file: the complete SpaceExport object described below.
• Full archive — a ZIP containing data.json plus every attachment as attachments/{uuid}/{filename}. The directory name is the attachment's UUID — the join key to the attachments array in the JSON; the file inside keeps its original (sanitized-at-upload) filename.

The two artifacts are self-describing and may be produced at different moments. Tools must tolerate asymmetry: JSON attachment entries missing from the ZIP (report and skip), and ZIP entries not referenced by the JSON (ignore).

Conventions

• IDs are UUID strings.
• Timestamps are ISO 8601 strings (RFC 3339 where a time is present); day-precision fields like due dates are ISO 8601 dates.
• Rich text comes in dual form: a *_text field with a plain-text extraction for humans and tooling, and a *_yjs field with the authoritative content as a base64-encoded Yjs update. For items, comments, and the space overview, the update contains a ProseMirror -compatible XML fragment under the key "content"; for documents, content_yjs encodes the document's entire Yjs doc. The *_text form is lossy; the *_yjs form is exact.
• Optional fields are omitted, not written as null (exception: labels.primary_label_id, which is written as null when unset).
• Array order is meaningful where the object has no explicit order array: items and documents appear in their display order, and each item's comments appear in thread order.

Top level

{
  "format": "wodo-space-export-v2",
  "exported_at": "2026-06-11T09:00:00Z",
  "space": { … },
  "labels": { … },
  "milestones": { … },
  "cycle_config": { … },
  "cycles": [ … ],
  "archive_config": { … },
  "views": { … },
  "items": [ … ],
  "documents": [ … ],
  "attachments": [ … ],
  "users": [ … ],
  "teams": [ … ],
  "overview_text": "…",
  "overview_yjs": "…"
}

space

labels

{
  "order": ["<label_id>", …],
  "primary_label_id": "<label_id>" | null,
  "definitions": {
    "<label_id>": {
      "id": "…", "name": "Status", "description": "", "icon": "",
      "values_order": ["<value_id>", …],
      "values": {
        "<value_id>": {
          "id": "…", "name": "Done", "color": "#22c55e",
          "is_completion_state": true,
          "completion_prompt": "What shipped?"
        }
      }
    }
  }
}

Items hold one value per label (items[].labels maps label id → value id). A value with is_completion_state: true counts as "done" for that label; its optional completion_prompt is the question shown when an item reaches that state.

Deprecated labels and label values are included — items may still reference them — carrying three optional fields on the definition: deprecated (bool), deprecated_at (timestamp), and deprecated_by (user UUID, resolved against users).

milestones

order (array of ids) plus definitions keyed by id:

cycles and cycle_config

Each entry in cycles is a concrete instance: { "id", "name", "start_date", "end_date", "archived" }.

cycle_config, when present: { "enabled", "pattern", "start_day", "prefix", "generate_ahead", "retain_past" }.

archive_config

{ "migration_days": <int> } — days after which archived items migrate to the deep archive.

views

order plus definitions keyed by view id:

Filter encoding. filters is a comma-separated token list. UUID-bearing tokens use the raw 16 UUID bytes encoded base64url without padding:

items

comments

Per item, in thread order:

documents

attachments

Metadata for every attachment row, whether or not the ZIP was downloaded:

Rich-text content references attachments by URL paths containing the attachment UUID; the import rewrites these inside the Yjs blobs.

users and teams

Snapshots of every user and team referenced anywhere in the export:

"users": [
  { "id": "…", "display_name": "Alice Anders", "email": "alice@example.com" }
],
"teams": [ { "id": "…", "name": "Platform" } ]

email is the cross-instance join key for import mapping; tombstoned accounts export as "Former user" without an email, and hard-deleted users are absent (importers fall back to the per-comment author_name snapshot).

How import treats the format

• Only "wodo-space-export-v2" is accepted.
• People are mapped on a ladder: a user UUID that exists in the target organization maps directly; otherwise a matching email maps to that member; otherwise the person is unmatched — their comments keep the exported name without an account, and their assignments and document ownerships are dropped. Teams map by UUID only. Everything is shown for review before the import runs.
• Provenance is preserved: when created_at/created_by are present, imported items and documents keep them (creators resolve through the people mapping; an unmatched creator falls back to the importing admin). Exports without these fields — older ones — import as before: importer + import time. Which of the two happened is recorded in the audit log.
• Item and comment UUIDs carry over; document and attachment UUIDs are regenerated, with references inside rich-text blobs (and forked_from lineage) rewritten.
• Saved-view filters survive: label, milestone, cycle, and keyword tokens carry over verbatim; u:/t: tokens are re-encoded for the mapped person or team, and unmatched ones are removed with a warning.
• short_id values are preserved and the space's counter is seeded past the maximum.
• Attachments over 50 MiB per file are skipped with a warning.

Current fidelity limitations

Known gaps in the format today — tracked, and the list shrinks as the format evolves:

• Saved views don't carry column/row collapse state or their own creation metadata.
• View filters partially encode UUIDs (base64url of the raw 16 bytes, unpadded) rather than plain UUID strings — tooling that rewrites identities must handle the token encoding.