CSV

The OCEL 2.1 CSV format is a compact, human-readable serialization that stores events, relationships, objects, and object attribute changes in a single table.

Columns #

Every file starts with these columns:

• id: an event ID, or the source object ID of an object-to-object relationship
• activity: an event type, or the special value o2o
• timestamp: an event timestamp or the time of an object attribute assignment
• ot:<X>: one column for every object type <X>

All other columns are event attributes. Empty cells represent missing values.

Files use UTF-8 and the RFC 4180 CSV dialect: fields are comma-separated, quoted with double quotes when necessary, and double quotes inside quoted fields are doubled.

Object References #

An ot:<X> cell contains zero or more object references:

object-id#qualifier{"attribute":"value"}/another-id#qualifier

The object ID is required. A qualifier and JSON object attributes are optional. Multiple references are separated by /; a qualifier starts with #; and JSON attributes start with {.

Because the format has no escape mechanism for these separators, object IDs and qualifiers cannot contain /, #, or {.

Row Types #

The values of id, activity, and timestamp determine the row type.

Event Rows #

An event row defines an event. Non-empty extra columns are its event attributes. Each reference in an ot:<X> cell creates an event-to-object relationship, with <X> as the referenced object’s type. JSON attributes on a reference are timed object attribute assignments at the event timestamp.

id,activity,timestamp,ot:orders,ot:items,total
e1,place order,2024-01-01T10:00:00Z,"o1#order{""price"":10.5}",i1#item,10.5

Object-to-Object Rows #

When activity is o2o (case-insensitive), id is the source object and every object reference is a target. The relationship itself is atemporal. A timestamp is only used for JSON attributes attached to target references.

id,activity,timestamp,ot:items
o1,o2o,,i1#contains/i2#contains

The source object’s type must have been established by an earlier object reference.

Object Declaration Rows #

A row with empty id, activity, and timestamp declares objects without creating relationships. JSON values define base object attributes. Qualifiers are not allowed.

id,activity,timestamp,ot:orders
,,,"ord1{""priority"":""high""}"

Object Attribute Rows #

A row with only a timestamp records timed object attribute assignments. Its object references contain the attributes to change.

id,activity,timestamp,ot:products
,,2024-02-01T12:00:00Z,"Echo{""price"":109.76}"

Object and Attribute Reconstruction #

An importer creates an object for each ID appearing in an ot:<X> cell and obtains its type from <X>. The same object ID cannot appear under different object type columns. For each object attribute, assignments are ordered by timestamp and then input row order. The first assignment is the base value; later assignments are changes.

The format has no explicit attribute schema. For each attribute name and scope, an importer chooses the first type that accepts all non-empty values:

1. integer
2. floating-point number
3. boolean (true or false, case-insensitive)
4. ISO 8601 timestamp with timezone information
5. string

JSON numbers, booleans, and null retain their primitive meaning before type unification. JSON arrays and objects are not valid attribute values.

File Extension #

The canonical file extension is .ocel.csv. The plain .csv extension identifies a generic CSV file.

Further Resources #

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