Auf neues JSON-Datenformat umstellen

[frankgerhardt]

Bisher wurden die Daten in diesem Format hoch geladen: https://github.com/mitfahrverband/mitfahr-api/blob/main/beispieldaten/json/trips_export_schema.json Das ist das Format wie Stadtnavi Herrenberg Mitfahrangebote bekommen hat.

In Zufkuft möchte ich dieses Format verwenden: http://amarillo.mfdz.de:8001/docs, siehe Components / Carpool. Das ist das Format wie bbnavi und stadtnavi generell in Zukuft Angebote bekommen werden.

[MartinH-open]

Das wäre aber was für nach dem 8. Mai 2022.

[frankgerhardt]

Wenn ich die anderen Anbieter integriere, würde ich das lieber im neuen Format machen, weil dann keine Nacharbeit.

[MartinH-open]

Ok, auch für den Übergang aufs neue Format schlage ich vor, die Daten der neuen, weiteren Anbieter im neuen Datenformat zu übertragen. Der Consumer - das iframe UI - würde solange beide Formate parallel unterstützen. Bestehende Datenlieferanten können dann nach und nach aufs neue Format umsteigen.
Für das neue Format schlage ich eine gewisse Namenkonvention vor, um aktuell relevante Dateien leicht zu erkennen; sowohl per Software als auch durch sortierte Auflistung der Dateien im Verzeichnis.

Vorschlag in der Art:
trips_<direction>_<eventname>_<startdate>[_<enddate>]_<agency>_<version>.json
Beispiel: trips_to_Duesseldorf_2022-05-08_blablacar_0.1.3.json
<direction> : 'to', 'from' to indicate the direction of the trips to or from the event
<eventname> : name of the specific event. example = Duesseldorf
<startdate> : date string of first day of the specific event. example = 2022-05-08
<enddate> : optional date string of last day of the specific event. example = 2022-05-08
<agency> : 'bessermitfahren', 'blablacar', 'mifaz', 'ride2go' to name the agency for which the file is containing data. example = blablacar
<version>.json : version string of the JSON data file format using a semantic versioning format. example = 0.1.3.json

Hintergründe:

1. So lassen sich gezielt auch alte Daten anhand des Namens erkennen und gezielt archivieren oder löschen.
2. Datenprobleme, die durch den Datenimport einer agency verursacht werden, stören die Daten der anderen nicht und können isoliert behandelt (zunächst ignoriert werden).
3. Die verschiedenen agency aktualisieren die Daten eventuell in unterschiedlichen zeitlichen Abstände und können so getrennt (verschiedene Prozesse) geliefert werden.
4. Das [_<enddate>] ist optional; insbesondere, wenn es nur das Event nur eintägig ist (Früh hin und später zurück). Bei mehrtägigen Events ist der letzte Tag anzugeben. (An späteren Tagen sind die Daten nicht mehr relevant und können archiviert/gelöscht werden)
5. Die Versionsangabe erlaubt es kompatibel Datenformate am Dateinamen zu erkennen ohne die Datei einzulesen. Der Dateiin halt sollte zusätzlich eine Versionsangabe erlauben.
6. Durch den Namensprefix trips lassen sich alphabetisch leicht alle Dateien dieses Typs erkennen und sie erscheinen nicht gemischt mit anderen Dateinamen im gleichen Verzeichnis. Ein spezielles Verzeichnis ausschliesslich nur für solche trips Informationen ist trotzdem empfohlen.

Offene Fragen:

• Brauchen wir noch eine fortlaufende ID oder Aufzählung, wenn die Daten in mehreren Abschnitte zusammengestellt werden?
  Eventuell sind mehrere Prozesse für eine agency beteiligt oder während eine Version der Datei vorliegt, wir bereicht die nächste Version generiert.

[MartinH-open]

Hinweise zum Format der JSON Datei mit mehreren Angeboten:

1. Die Definition des Formats Components / Carpool aus http://amarillo.mfdz.de:8001/docs bezieht sich auf ein einzelnes Fahrtangebot als JSON object. Die JSON Datei zum Übermitteln von mehreren Angebote müsste also eine Menge von JSON objects in einem array liefern.
2. Laut Definition für ein Fahrtangebot ist dort nur eine vereinfachte Tagesangabe und Uhrzeitangabe vorgesehen - ohne eine Zeitzone dafür anzugeben. Wahrscheinlich ist davon auszugehen, dass alle Tages und Zeitangaben die gleiche Zeitzone nutzen.
3. Für jedes Angebot ist eine agency anzugeben und die agency muss eine Zeitzone spezifizieren, in der diese agiert. Wahrscheinlich ist davon auszugehen, dass alle Angebote einer agency diese eine Zeitzone nutzen.
4. Entweder sollten in der JSON Datei mit allen Fahrtangeboten einer agency einmalig diese agency Informationen enthalten sein, damit Zeitzone und andere wichtige Dinge (wie Langname, Logo, Sprache, ..) verfügbar sind für die korrekte Darstellung und Nutzung der Fahrtangebote.
5. Für die JSON Datei mit Fahrtangeboten wäre die Info über das abgedeckte Gebiet (oder bounding box) und der Zeitpunkt der Datenerhebung auch sinnvoll. Es ist dazu zu klären, was Abdeckung eines Gebietes hier meint: betrifft es Start-, Ziel- und/oder auch Zwischenziele? Wie geht man mit räumlicher Unschärfe um?
6. Eine Versionsangabe in der JSON Datei auf obersten Objekt-Level sollte helfen zu entscheiden, ob die enthaltenen Datenformat kompatibel sind mit der verarbeitenden Software.

Für die aktuelle "Demo" Version in DE sind diese Festlegungen weniger relevant, weil nur eine Zeitzone genutzt wird und auch die agencies im code schon fest hinterlegt sind. Obige Überlegungen sind für zukünftige transnationale Lösungen relavant.