Bundled CSV/Parquet

The OCEL 2.1 bundled format stores an OCEL 2.0 log as a ZIP archive of typed tables. It is intended for efficient import into databases and dataframe engines. The same layout can also be used as an uncompressed directory.

Archive Layout

Every bundle contains ocel-meta.json. The remaining files use either CSV or Parquet, never a mixture of both:

ocel-meta.json
events/event_<encoded-event-type>.<ext>
objects/object_<encoded-object-type>.<ext>
object_changes/object_changes_<encoded-object-type>.<ext>
relations/e2o.<ext>
relations/o2o.<ext>

Here, <ext> is csv or parquet. Each event type has one event table, and each object type has both an object table and an object-change table. An object-change table without changes contains only its header in CSV or zero rows in Parquet.

Type names in filenames are UTF-8 percent-encoded. ASCII letters, digits, ., _, and - remain unescaped; every other byte is written as %HH with uppercase hexadecimal digits.

place order  -> events/event_place%20order.csv
pay/order    -> events/event_pay%2Forder.csv
sales person -> objects/object_sales%20person.csv

The metadata mapping is authoritative: importers do not infer type names from filenames.

Metadata

ocel-meta.json declares the OCEL and bundle versions, storage format, event and object types, attribute names and primitive types, and all table locations.

{
  "ocelVersion": "2.0",
  "bundleFormatVersion": "1.0",
  "storageFormat": "csv",
  "eventTypes": {
    "place order": {
      "file": "events/event_place%20order.csv"
    }
  },
  "objectTypes": {
    "orders": {
      "file": "objects/object_orders.csv",
      "changesFile": "object_changes/object_changes_orders.csv"
    }
  },
  "relations": {
    "e2o": "relations/e2o.csv",
    "o2o": "relations/o2o.csv"
  }
}

Tables

The bundle contains these logical tables:

TableRequired columns
Event tableocel_id, ocel_time, followed by the event type’s attributes
Object tableocel_id, followed by the object type’s attributes
Object-change tableocel_id, ocel_time, ocel_changed_field, followed by the object type’s attributes
Event-to-object relationsocel_event_id, ocel_object_id, ocel_qualifier
Object-to-object relationsocel_source_id, ocel_target_id, ocel_qualifier

Object attribute values in an object table are initial values, effective from the Unix epoch (1970-01-01T00:00:00Z). Each row in an object-change table assigns one new value: ocel_changed_field names the changed attribute, and that attribute’s column contains the value.

For example:

ocel_id,ocel_time,ocel_changed_field,price
o1,2024-02-01T12:00:00Z,price,109.76

File Extension

The canonical archive extension is .ocel.zip. The uncompressed form is a directory with the same internal layout.

Further Resources

See the OCEL 2.1 specification for the complete definition and bundled running example.

← CSV
Specification →