Skip to content
Snippets Groups Projects

ENH: add framework for converting json schema into table templates

Merged ENH: add framework for converting json schema into table templates
f-more-jsonschema-export into dev
Merged Henrik tom Wörden requested to merge f-more-jsonschema-export into dev
Viewing commit 96e5eb76
Prev Next
Show latest version
2 files
+ 139
− 81
Compare changes
  • Side-by-side
  • Inline
Files
2
src/doc/table-json-conversion/specs.md
+ 139
− 81
# Konversion zwischen LinkAhead-Datenmodellen, JSON-Schema und XLSX (und zurück) #
Top level of json must be a dict. keys of the dict are RT names.
@@ -6,12 +8,14 @@ Frage: is the first RT never an array?
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.
Das Datenmodell in LinkAhead legt fest, welche Arten von Records es in einer LinkAhead-Instanz
gibt und wie diese aussehen. Diese 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:
```JSON
{
"Person": {
@@ -21,36 +25,48 @@ Zum Beispiel kann das folgende JSON den Record einer Person beschreiben:
}
```
Das JSON Schema schreibt eine konkrete Struktur vor und kann 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 speichern. Dies ist insbesondere wertvoll
beim Datenim- und export. Man könnte basierend auf dem im Folgenden beschriebenen Webformulare basieren
oder es nutzen um in LinkAhead gespeicherte Objekte als JSON zu exportieren.
Im Folgenden wird beschrieben, wie JSON Dateien mit solchen Records in XLSX Dateien umgewandelt
werden, bzw. wie aus XLSX-Dateien JSON Dateien mit Records erstellt werden.
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.
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
a. primitiv (Text, Zahl, Boolean, ...)
b. ein Record
c. eine Liste von primitiven Typen
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.
## Von JSON zu XLSX: Datenrepräsentation ##
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.
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.
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
a. primitiv (Text, Zahl, Boolean, ...)
b. ein Record
c. eine Liste von primitiven Typen
d. eine Liste von Records
sein.
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.
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 erstellt.
In diesen werden die referenzierten Records behandelt wie oben beschrieben. Es gibt jedoch zusätzliche Spalten die es erlauben zu erkennen von
welchem Record die Records referenziert werden.
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.
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 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.
Wir betrachten diese vier Fälle nun im Detail:
a. Properties mit primitiven Datentypen
### a. Properties mit primitiven Datentypen ###
```JSON
{
@@ -63,38 +79,36 @@ a. Properties mit primitiven Datentypen
}
}
```
Dies würde in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
| date | url | duration | participants | remote |
|------|-----|-------------------|-----|---|----|
| 2023-01-01 | www.indiscale.com | 1.0 | 1 | false |
Dieser Eintrag wird in einem XLSX-Blatt mit dem folgenden Inhalt abgebildet:
b. Property, die einen Record referenziert
| date | url | duration | participants | remote |
|------------|-------------------|----------|--------------|--------|
| 2023-01-01 | www.indiscale.com | 1.0 | 1 | false |
### b. Property, die einen Record referenziert ###
```JSON
{
"Training": {
"date": "2023-01-01",
"supervisor": {
"family_name": "Steve",
"family_name": "Stevenson",
"given_name": "Stevie",
}
}
}
```
Dies würde in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
Dieser Eintrag wird in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
| date | supervisor.family_name | supervisor.given_name |
|------|-----|-------------------|
| 2023-01-01 | Steve | Stevie |
| 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.
c. Properties, die Listen mit Werten von primitiven Datentypen enthalten
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.
### c. Properties, die Listen mit Werten von primitiven Datentypen enthalten ###
```JSON
{
@@ -105,19 +119,16 @@ c. Properties, die Listen mit Werten von primitiven Datentypen enthalten
}
```
Dies würde in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
| url | subjects |
|------|-----|-------------------|-----|---|----|
| www.indiscale.com | Math;Physics |
Dieser Eintrag würde in einem XLSX Blatt mit dem folgenden Inhalt abgebildet:
Die Listenelemente werden separiert von ``;`` in die Zelle geschrieben.
Wenn die Elemente den Separator ``;`` enthalten, dann wird dieser mit einem ``\`` escaped.
| 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.
d. Properities, die Listen mit Referenzen enthalten
### d. Properties, die Listen mit Referenzen enthalten ###
```JSON
{
@@ -127,45 +138,92 @@ d. Properities, die Listen mit Referenzen enthalten
{
"family_name": "Sky",
"given_name": "Max",
},{
},
{
"family_name": "Sky",
"given_name": "Min",
}],
}
]
}
}
```
Da die beiden Coaches nicht vernünftig in einer Zelle dargestellt werden können, bedarf es nun eines
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.
Das Blatt zu den Trainings enthält in diesem Beispiel nur die "date" Spalte:
Das Blatt zu den *Trainings* enthält in diesem Beispiel nur die "date" Spalte:
| date |
|------|
| 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
TODO: In welchem Scope gilt diese Eindeutigkeit? Können wir dies checken?
Das zweite Blatt sieht dann wie folgt aus
| date | coach.family_name | coach.given_name |
|------|-|-|
| 2023-01-01 | Sky | Max|
| 2023-01-01 | Sky | Min|
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.
TODO: In welchem Scope gilt diese Eindeutigkeit? Können wir dies checken?
# Hidden automation logic
The first column in each sheet will be hidden and it will contain an entry in each row that needs special
treatment. The following values are used:
``COL_TYPE``: typically the first row. It indicates the row that defines the type of columns (``FOREIGN`` or ``VALUE``).
``PATH``: indicates that the row is used to define the path within the JSON
``IGNROE``: row is ignored; It can be used for explanatory texts or layout
Das zweite Blatt sieht dann wie folgt aus
If we want to put the value of a given cell into the JSON, we traverse all path elements given in rows with the ``PATH`` value from row with lowest index to the one with the highest index. The final element of the path is the name of the Property of which the value
needs to be set. The elements of the path are sufficient to identify the object within the JSON if the value of the corresponding key is
an object. If the value is an array, the appropriate object within the array needs to be selected.
For this selection additional ``FOREIGN`` columns are used. The path given in those columns is the path to the level where the object needs to be chosen plus the name of the attribute that is used to select the correct object.
| date | `coach.family_name` | `coach.given_name` |
|------------|---------------------|--------------------|
| 2023-01-01 | Sky | Max |
| 2023-01-01 | Sky | Min |
## Data in XLSX: Hidden automation logic ##
### First column: Marker for row types ###
The first column in each sheet will be hidden and it will contain an entry in each row that needs
special treatment. The following values are used:
- ``IGNORE``: This row is ignored. It can be used for explanatory texts or layout.
- ``COL_TYPE``: Typically the first row that is not `IGNORE`. It indicates the row that defines the
type of columns (`FOREIGN`, `SCALAR`, `LIST`, `IGNORE`). This row may occur only once.
- ``PATH``: Indicates that the row is used to define the path within the JSON. These rows are
typically hidden for users.
An example table could look like this:
| `IGNORE` | | Welcome | to this | file! | |
| `IGNORE` | | Please | enter your | data here: | |
| `COL_TYPE` | `IGNORE` | `SCALAR` | `SCALAR` | `LIST` | `SCALAR` |
| `PATH` | | `Training` | `Training` | `Training` | `Training` |
| `PATH` | | `url` | `date` | `subjects` | `supervisor` |
| `PATH` | | | | | `email` |
| `IGNORE` | Please enter one training per line. | Training URL | Training date | Subjects | Supervisor's email |
|------------|-------------------------------------|----------------|---------------|--------------|--------------------|
| | | example.com/mp | 2024-02-27 | Math;Physics | steve@example.com |
| | | example.com/m | 2024-02-27 | Math | stella@example.com |
### Parsing XLSX data ###
To extract the value of a given cell, we traverse all path elements (in ``PATH`` rows) from top to
bottom. The final element of the path is the name of the Property to which the value belongs. In
the example above, `steve@example.com` is the value of the `email` Property in the path
`["Training", "supervisor", "email"]`.
The path elements are sufficient to identify the object within a JSON, at least if the corresponding
JSON element is a single object. If the JSON element is an array, the appropriate object within the
array needs to be selected.
For this selection additional ``FOREIGN`` columns are used. The paths in these columns must all have
the same *base* and one additional *unique key* component. For example, two `FOREIGN` columns could
be `["Training", "date"]` and `["Training", "url"]`, where `["Training"]` is the *base path* and
`"date"` and `"url"` are the *unique keys*.
The base path defines the table (or recordtype) to which the entries belong, and the values of the
unique keys define the actual rows to which data belongs.
For example, this table defines three coaches for the two trainings from the last table:
| `COL_TYPE` | `FOREIGN` | `FOREIGN` | `SCALAR` |
| `PATH` | `Training` | `Training` | `Training` |
| `PATH` | `date` | `url` | `coach` |
| `PATH` | | | `given_name` |
| `IGNORE` | Date of training | URL of training | The coach's given name |
| `IGNORE` | from sheet 'Training' | from sheet 'Training' | |
|------------|-----------------------|-----------------------|------------------------|
| | 2024-02-27 | example.com/mp | Ada |
| | 2024-02-27 | example.com/mp | Berta |
| | 2024-02-27 | example.com/m | Chris |