Skip to content
Snippets Groups Projects
Verified Commit 08cc5e18 authored by Daniel Hornung's avatar Daniel Hornung
Browse files

DOC: json table conversion `specs.md`

parent 628af5af
No related branches found
No related tags found
1 merge request!100WIP: Filling XLSX: Seems to be working.
Hide whitespace changes
Inline Side-by-side
src/doc/table-json-conversion/specs.md
+ 84
− 60
View file @ 08cc5e18
# 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.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment