Import and export

Contents

Import and export#

Quilombo can export a workspace as a versioned JSON or CSV document and import that document into an authorized workspace. PostgreSQL remains canonical storage; these formats are for backup, transfer, inspection, and deterministic interchange. OKF projection is not part of the current contract.

Export#

Use GET /api/workspaces/{slug}/export/?format=json or ?format=csv. The response is a UTF-8 attachment. Both formats include stable UUIDs for locations, items, labels, label aliases, label assertions, holdings, and location relations.

JSON uses this top-level shape:

{
  "format_version": "1.1",
  "workspace": {"id": "...", "name": "Workshop", "slug": "workshop"},
  "exported_at": "2026-08-22T12:00:00Z",
  "locations": [],
  "items": [],
  "labels": [],
  "label_aliases": [],
  "item_labels": [],
  "holdings": [],
  "location_relations": []
}

CSV uses one table with a record_type column. Label records use label, label_alias, and item_label; fields that are structured in the domain model, such as aliases, metadata, and attributes, contain compact JSON values.

Import#

POST to /api/workspaces/{slug}/import/ with format, a unique idempotency_key, optional provenance, and exactly one input source:

  • document: a parsed JSON object;

  • content: a JSON or CSV string;

  • file: a UTF-8 JSON or CSV upload.

Set dry_run: true to validate the entire document and return created/updated counts without writing records or an inventory event. A non-dry-run import commits all records and its provenance in one transaction. Repeating it with the same idempotency key and payload returns the original summary.

Version 1.1 adds the label vocabulary and assertions. Imports continue to accept version 1.0 JSON and CSV documents, treating their absent label collections as empty. An assertion’s authenticated created_by_id is preserved for backups in the same installation; a portable transfer must set it to null when that user does not exist in the target installation.

Imports preserve supplied UUIDs and merge the document into the target workspace; records omitted from a document are not deleted. References must resolve within the document. UUIDs from another workspace, conflicting stable keys, invalid hierarchies, cross-workspace relationships, negative quantities, and fractional quantities for discrete items are rejected before commit.

Web UI#

Signed-in members have an Import / export page for each workspace (/app/{slug}/transfer/):

  • Export downloads the whole workspace as a JSON or CSV file.

  • Import takes a JSON or CSV upload and always shows a dry-run preview with created/updated counts first. “Apply import” then commits it in one transaction and redirects to the history. Re-applying the same preview is idempotent.

Members with read-only access can export but not import.

Contents