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.

Contents