LOGUMENT: "WHEN, What, and How has it happened in Vehicles?"

Sunghwan Park (Chung-Ang Univ.), Hyun-Gul Roh (42dot Corp.), Sunwoo Na (Chung-Ang Univ.), Sangho Park (Chung-Ang Univ.), Yeseul Chang (Chung-Ang Univ.), and Jaewoo Lee (Chung-Ang Univ.)

Contents

• LOGUMENT: "WHEN, What, and How has it happened in Vehicles?"
  • Contents
  • Implementation of LOGUMENT
    • Structure
    • Primitive operations
    • Supporting operations
    • Additional supporting operation
  • About TSON
    • BNF of TSON
    • VSCode Extension
  • Usage
    • Working environment
    • LOGUMENT Demo
    • TSON & TSON Patch Generation with VSS dataset
  • Contributions
  • LICENSE

---

Implementation of LOGUMENT

Structure

• Version []uint64: An array of versions that LOGUMENT manages; should be continuos
• Snapshot map[uint64]tson.Tson: A map which contains an initial Snapshot (by Create) and Snapshots from Snapshot Function {version: Snapshot}
• Patches map[uint64]tsonpatch.Patch: A map of Patches managed internally in LOGUMENT {version: Patches}
• PatchPool tsonpatch.Patch: Patches to be managed in LOGUMENT

Primitive operations

• Create(snapshot tson.Tson, patches tsonpatch.Patch): Make a new LOGUMENT using an initial snapshot (Note: The function name in the implementation is NewLogument)

• Store(patches tsonpatch.Patch): Store new patches in the PatchPool temporarily; These patches are queued and will be later integrated into the LOGUMENT state via the Append operation

• Append(): Incorporate all pending patches from the PatchPool into the Patches, update(increase) the version, and clear the PatchPool

  💡 Implementation detail

  Append, as defined in the LOGUMENT paper, is implemented by sequentially executing Store and Append.

• Track(vi, vj uint64): Extract patches that have changed Values between the vi and the vj, preparing them for transmission

• Snapshot(vk uint64): Generate a snapshot representing the LOGUMENT state at the specified version by applying the corresponding patches to the nearest previous snapshot

• Slice(vi, vj uint64): Extract a subset of the LOGUMENT that includes all snapshots and patches between the version vi and vj (inclusive)

Supporting operations

• Set(vk uint64, op tsonpatch.OpType, path string, value any): Update the state with a JSON-supported value, and create the patch of which op is either add or replace

• Unset(vk uint64, op tsonpatch.OpType, path string): Remove the specific path, and create the patch that op is remove

• TestSet(vk uint64, op tsonpatch.OpType, path string, value any): Set only if value has changed

• TestUnset(vk uint64, op tsonpatch.OpType, path string): Unset only if path has removed

• TemporalTrack(tsi, tsj int64): Extract patches between the tsi and the tsj, enabling to query the evolution and history of data over time

• TemporalSnapshot(tsk int64): Create a snapshot based on a target timestamp

• TemporalSlice(tsi, tsj int64): Extract a subset of the LOGUMENT document based on the specified start and end timestamps

Additional supporting operation

• Compact(path string): For the specified targetPath, remove patches where only the timestamp has changed (i.e., retain only those patches where the Value has actually been modified)

• History(path string): Retrieve the history of changes at the specified target path; This includes all patches that have modified the value at the target path

---

About TSON

TSON, which stands for Time-Stamped JSON, is used to store timestamps as well as data values.

BNF of TSON

<tson> ::= <object> | <array> | <value>

<object> ::= "{" <members>? "}"
<members> ::= <pair> ("," <pair>)*
<pair> ::= <string> <timestamp>? ":" <value>

<array> ::= "[" <elements>? "]"
<elements> ::= <value> ("," <value>)*

<value> ::= <primitive> <timestamp>? | <object> | <array> | "null"
<primitive> ::= <string> | <number> | <boolean>

<timestamp> ::= "<" <timestamp_value> ">"

VSCode Extension

There is a Visual Studio Code extension, which enables TSON syntax highlighting.
Please refer to VSCode-TSON-Extension repository, and TSON extension on VSCode Marketplace

For more detailed explanation about TSON and TSON Patch, please refer to its README.md file.

---

Usage

Working environment

• go 1.23.5
• jsonpatch@appscode v1.0.1

LOGUMENT Demo

go get -u && go run main.go

Then navigate to localhost:8080 to interact.

TSON & TSON Patch Generation with VSS dataset

go run main.go [ARGUMENTS...]

Parameters:

• cars <int>: [required] the number of cars
• files <int>: [required] the number of files per each car
• change_rate <float64>: Change rate for each file
• size <float64>: Dataset size ratio (0.5: Use 50% attributes of VSS)
• dataset <string>: Path to VSS JSON dataset

---

Contributions

• Supervising: Hyun-Gul Roh and Jaewoo Lee

• LOGUMENT interface: Sunghwan Park

• TSON & TSON Patch implementation: Sunwoo Na (Karu)

• Data Synchronize Framework: Sunwoo Na (Karu)

• vss.json from Vehicle Signal Specification

LICENSE

LOGUMENT and all related projects are APACHE-2.0 licensed.