From 08cc5e18572edea4b78245815ab644f913377154 Mon Sep 17 00:00:00 2001
From: Daniel <d.hornung@indiscale.com>
Date: Tue, 9 Apr 2024 18:21:06 +0200
Subject: [PATCH] DOC: json table conversion `specs.md`
---
src/doc/table-json-conversion/specs.md | 144 ++++++++++++++-----------
1 file changed, 84 insertions(+), 60 deletions(-)
diff --git a/src/doc/table-json-conversion/specs.md b/src/doc/table-json-conversion/specs.md
index 3a5fcef5..73e48044 100644
--- a/src/doc/table-json-conversion/specs.md
+++ b/src/doc/table-json-conversion/specs.md
@@ -1,20 +1,19 @@
-# Konversion zwischen LinkAhead-Datenmodellen, JSON-Schema und XLSX (und zurück) #
+# Conversion between LinkAhead data models, JSON schema, and XLSX (and vice versa) #
-Top level of json must be a dict. keys of the dict are RT names.
+This file describes the conversion between JSON schema files and XLSX templates, and between JSON
+data files following a given schema and XLSX files with data. This conversion is handled by the
+Python modules in the `table_json_conversion` library.
+Requirements: When converting from a json schema, the top level of the json schema must be a
+dict. The keys of the dict are RecordType names.
-Frage: is the first RT never an array?
+## Data models in JSON Schema and JSON data ##
+The data model in LinkAhead defines the types of records present in a LinkAhead instance and their
+structure. This data model can also be represented in a JSON Schema, which defines the structure of
+JSON files containing records pertaining to the data model.
-Do not use sheet name, but only content of hidden rows
-
-## Datenmodelle in JSON-Schema und JSON-Daten ##
-
-Das Datenmodell in LinkAhead legt fest, welche Arten von Records es in einer LinkAhead-Instanz gibt
-und wie diese aussehen. Dieses Datenmodell kann auch in einem JSON Schema repräsentiert werden, dass
-die Struktur von JSON Dateien festlegt, die zu dem Datenmodell gehörige Records enthält.
-
-Zum Beispiel kann das folgende JSON den Record einer Person beschreiben:
+For example, the following JSON can describe a "Person" Record:
```JSON
{
@@ -25,46 +24,61 @@ Zum Beispiel kann das folgende JSON den Record einer Person beschreiben:
}
```
-Ein *JSON Schema* schreibt eine konkrete Struktur vor, und die zugehörige JSON Dateien können
-genutzt werden, um Daten zu bestimmten Record-Strukturen zu repräsentieren. Beispielsweise könnte
-man ein JSON Schema erstellen, dass es erlaubt "Training" Records mit Informationen zu abgehaltenen
-Trainings zu speichern. Dies ist insbesondere wertvoll beim Datenim- und export. Man
-könnte Webformulare aus dem Json Schema generieren oder es nutzen, um in LinkAhead gespeicherte
-Objekte als JSON zu exportieren.
+A *JSON Schema* specifies a concrete structure, and the associated JSON files can be used to
+represent data for specific record structures. For instance, one could create a JSON Schema allowing
+the storage of "Training" Records containing information about conducted trainings. This is
+particularly valuable for data import and export. One could generate web forms from the JSON Schema
+or use it to export objects stored in LinkAhead as JSON.
-## Von JSON zu XLSX: Datenrepräsentation ##
+## From JSON to XLSX: Data Representation ##
-Im Folgenden wird beschrieben, wie JSON Dateien, die LinkAhead-Records reprästentieren in XLSX
-Dateien umgewandelt werden, bzw. wie aus XLSX-Dateien JSON Dateien mit Records erstellt werden.
+The following describes how JSON files representing LinkAhead records are converted into XLSX files,
+or how JSON files with records are created from XLSX files.
-Der Attributname (oben "Person") legt den RecordType fest und der Wert diese Attributs kann entweder
-ein Objekt oder eine Liste sein. Ist es ein Objekt (wie im obigen Beispiel), so wird ein einzelner
-Record repräsentiert. Bei einer Liste mehrere Records, die den gleichen RecordType als Parent
-haben.
+The attribute name (e.g., "Person" above) determines the RecordType, and the value of this attribute
+can either be an object or a list. If it is an object (as in the example above), a single record is
+represented. In the case of a list, multiple records sharing the same RecordType as the parent are
+represented.
-Die *Properties* des Records (oben `family_name` und `given_name`) werden zu *Spalten* im XLSX. Die
-Properties haben wiederum einen Attributnamen und einen Wert. Der Wert kann
+The *Properties* of the record (e.g., `family_name` and `given_name` above) become *columns* in the
+XLSX file. These properties have an attribute name and a value. The value can be:
-a. primitiv (Text, Zahl, Boolean, ...)
-b. ein Record
-c. eine Liste von primitiven Typen
-d. eine Liste von Records
+a. A primitive (text, number, boolean, ...)
+b. A record
+c. A list of primitive types
+d. A list of records
-sein.
+In cases *a.* and *c.*, a cell is created in the column corresponding to the property in the XLSX
+file. In case *b.*, columns are created for the Properties of the record, where for each of the
+Properties the cases *a.* - *d.* are considered recursively.
-In den Fällen *a.* und *c.* wird in XLSX eine Zelle in der zur Property gehörigen Spalte erstellt.
-Im Fall *b.* wird prinzipiell für die Properties des Records Spalten erstellt. Tatsächlich wird der
-referenzierte Record genauso behandelt wie der ursprüngliche. D.h. die Fälle a.-d. werden wieder
-für die einzelnen Properties betrachtet.
+For case *d.* however, the two-dimensional structure of an XLSX sheet is not sufficient. Therefore,
+for such cases, *new* XLSX sheets/tables are created.
-Für den Fall *d.* ist die zweidimensionale Struktur eines XLSX Blatts nicht ausreichend. Daher
-werden für solche Fälle *neue* XLSX-Blätter/-Tabellen erstellt.
+In these sheets/tables, the referenced records are treated as described above (new columns for the
+Properties). However, there are now additional columns that indicate from which "external" record
+these records are referenced.
-In diesen werden die referenzierten Records behandelt wie oben beschrieben. Es gibt jedoch
-zusätzliche Spalten die es erlauben zu erkennen, von welchem "externen" Record diese Records
-referenziert werden.
+Let's now consider these four cases in detail and with examples:
+
+### a. Properties with Primitive Data Types ###
+
+```JSON
+{
+ "Training": {
+ "date": "2023-01-01",
+ "url": "www.indiscale.com",
+ "duration": 1.0,
+ "participants": 1,
+ "remote": false
+ }
+}
+```
+
+This entry is represented in an XLSX sheet with the following content:
+date url duration participants remote
+2023-01-01 www.indiscale.com 1.0 1 false
-Wir betrachten diese vier Fälle nun im Detail:
### a. Properties mit primitiven Datentypen ###
@@ -79,13 +93,14 @@ Wir betrachten diese vier Fälle nun im Detail:
}
}
```
-Dieser Eintrag wird in einem XLSX-Blatt mit dem folgenden Inhalt abgebildet:
+
+This entry will be represented in an XLSX sheet with the following content:
| date | url | duration | participants | remote |
|------------|-------------------|----------|--------------|--------|
| 2023-01-01 | www.indiscale.com | 1.0 | 1 | false |
-### b. Property, die einen Record referenziert ###
+### b. Property referencing a record ###
```JSON
{
@@ -99,16 +114,16 @@ Dieser Eintrag wird in einem XLSX-Blatt mit dem folgenden Inhalt abgebildet:
}
```
-Dieser Eintrag wird in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
+This entry will be represented in an XLSX sheet with the following content:
| date | `supervisor.family_name` | `supervisor.given_name` |
|------------|--------------------------|-------------------------|
| 2023-01-01 | Stevenson | Stevie |
-Beachten Sie, dass die Spaltennamen umbenannt werden dürfen. Die Zuordnung der Spalte zu Properties
-von Records wird über den Inhalt von versteckten Zeilen gewährleistet.
+Note that column names may be renamed. The mapping of columns to properties of records is ensured
+through the content of hidden rows. (See below for the definition of hidden rows.)
-### c. Properties, die Listen mit Werten von primitiven Datentypen enthalten ###
+### c. Properties containing lists of primitive data types ###
```JSON
{
@@ -119,16 +134,16 @@ von Records wird über den Inhalt von versteckten Zeilen gewährleistet.
}
```
-Dieser Eintrag würde in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
+This entry would be represented in an XLSX sheet with the following content:
| url | subjects |
|-------------------|--------------|
| www.indiscale.com | Math;Physics |
-Die Listenelemente werden separiert von `;` in die Zelle geschrieben. Wenn die Elemente den
-Separator `;` enthalten, dann wird dieser mit einem `\\` escaped.
+The list elements are written into the cell separated by `;` (semicolon). If the elements contain
+the separator `;`, it is escaped with `\\`.
-### d. Properties, die Listen mit Referenzen enthalten ###
+### d. Properties containing lists with references ###
```JSON
{
@@ -148,22 +163,23 @@ Separator `;` enthalten, dann wird dieser mit einem `\\` escaped.
}
```
-Da die beiden Coaches nicht vernünftig in einer Zelle dargestellt werden können, bedarf es nun eines
-weiteren Tabellenblatts, das die Eigenschaften der Coaches enthält.
+Since the two coaches cannot be represented properly in a single cell, another worksheet is needed
+to contain the properties of the coaches.
-Das Blatt zu den *Trainings* enthält in diesem Beispiel nur die "date" Spalte:
+The sheet for the Trainings in this example only contains the "date" column
| date |
|------------|
| 2023-01-01 |
-Zusätzlich gibt es ein *weiteres* Blatt in dem die Coaches gespeichert werden. Hier ist nun
-entscheidend, dass definiert wird, wie von potentiell mehreren "Trainings" das richtige Element
-gewählt wird. In diesem Fall bedeutet dies, dass das "date" eindeutig sein muss.
+Additionally, there is *another* sheet where the coaches are stored. Here, it is crucial to define
+how the correct element is chosen from potentially multiple "Trainings". In this case, it means that
+the "date" must be unique.
-TODO: In welchem Scope gilt diese Eindeutigkeit? Können wir dies checken?
+Note: This uniqueness requirement is not strictly checked right now, it is your responsibility as a
+user that such "foreign properties" are truly unique.
-Das zweite Blatt sieht dann wie folgt aus
+The second sheet looks like this:
| date | `coach.family_name` | `coach.given_name` |
|------------|---------------------|--------------------|
@@ -227,3 +243,11 @@ For example, this table defines three coaches for the two trainings from the las
| | 2024-02-27 | example.com/mp | Ada |
| | 2024-02-27 | example.com/mp | Berta |
| | 2024-02-27 | example.com/m | Chris |
+
+## Current limitations ##
+
+The current implementation still lacks the following:
+
+- Lists of enum references are not yet implemented as columns where matching cell can simply be
+ ticked/crossed.
+- Files handling is not implemented yet.
--
GitLab