Workspace file format
The canonical data format is one JSON document per user, defined by schema/workspace.schema.json (JSON Schema draft 2020-12). In standalone mode it holds everything; with a server it holds exactly what that user may see.
Top level
| Field | Meaning |
|---|---|
schemaVersion | Integer. Bumped on every schema change (see docs/migrations/) |
app | { name: "pecklist", version } (punchlist before the rename) of the app that last wrote the file |
owner | User id (ULID) the file belongs to |
node | Device id used in this copy's HLC timestamps |
entities | One array per entity type |
sync | { server, cursor }; both null in standalone mode |
Every entity
| Field | Meaning |
|---|---|
id | ULID |
createdAt, createdBy | UTC timestamp, user id |
deletedAt | Tombstone timestamp or null (soft delete, 30-day trash) |
origin | Home server of the record; local in standalone mode |
_hlc | Field name to hybrid logical clock timestamp of its last write |
Merge rules
- Scalar fields: the value with the later
_hlctimestamp wins. HLC format<ISO time>-<4-digit counter>-<node>sorts as a plain string. - Element sets (
tasks.tags,tasks.assignees,tasks.blockedBy): each element is{ in, hlc }and merges on its own. - Entities present on only one side are kept.
- Manual order uses fractional index keys (
order), compared as plain strings.
The rules are pinned by schema/fixtures/merge; every implementation must pass them.
Dates
- UTC timestamps:
2026-10-20T16:15:02.113Z - Schedules and due dates: a local date (
2026-11-03) or local date-time without offset (2026-11-03T09:00) plus atimeZone.