christian-weiss
commented
3 years ago Das Build-Script (Python) im Freifunk API Directory github repo scheint besser als der API Generator zu validieren: https://app.travis-ci.com/github/freifunk/directory.api.freifunk.net/builds/235931640
Validation errors (summary): 1x Freifunk Aachen 2x Freifunk Bad Pyrmont 1x Freifunk Bad Oeynhausen 1x Freifunk Bamberg 19x Kreis Schleswig-Flensburg 4x Freifunk Nordlippe 1x Freifunk Dresden 1x Freifunk Brandenburg 1x Freifunk Erlangen 1x Freifunk Fürth 1x Freifunk Haßberge 1x Freifunk Göldenitz 1x Freifunk MK 2x Freifunk Halle 1x Freifunk Kavelstorf 1x Freifunk Ingolstadt 1x Freifunk Ludwigslust 1x Freifunk Karlsruhe 1x Freifunk Nürnberg 1x Freifunk Niex 1x Freifunk Parchim 1x Freifunk Potrems 1x Freifunk Reinshagen 1x Freifunk Schwerin 1x Freifunk Vogtland 2x Freifunk Würzburg 1x Freifunk Stuttgart 1x Freifunk Wokern 1x Freifunk Wismar 1x freifunk wiesenburg 1x Freifunk Holzwinkel
Wenn man z.B. die aktuelle API Datei von Bad Pymon:
{
"name": "Freifunk Bad Pyrmont",
"url": "http://www.freifunk-badpyrmont.de",
"metacommunity": "Freifunk Nordlippe",
"location": {
"city": "Bad Pyrmont",
"country": "DE",
"lat": 51.98394626197565,
"lon": 9.256153106689453
},
"contact": {
"email": "ar@freifunk-badpyrmont.de"
},
"state": {
"description": "Wir bauen für die Region Bad Pyrmont (NDS) Freifunk auf.",
"focus": [
"Public Free Wifi",
"Local services and content"
],
"lastchange": "2016-03-21T14:50:02.053Z"
},
"nodeMaps": [
{
"url": "map.freifunk-badpyrmont.de",
"interval": "5",
"technicalType": "ffmap",
"mapType": "geographical"
},
{
"url": "map.freifunk-nordlippe.de/nodes_badpyrmont.json",
"interval": "5",
"technicalType": "ffmap",
"mapType": "list/status"
}
],
"techDetails": {
"firmware": {
"name": "GLUON",
"url": "http://update.freifunk-badpyrmont.de",
"docs": "http://www.freifunk-badpyrmont.de"
},
"dns": [
{
"domainname": "ffnl",
"nameserver": [
"10.136.1.1"
]
}
],
"networks": {
"ipv6": [
{
"network": "fd42:ffee:ff42::/48"
}
],
"ipv4": [
{
"network": "10.136.0.0/16"
}
]
},
"routing": [
"batman-adv"
],
"updatemode": [
"autoupdate"
],
"legals": [
"vpninternational"
]
},
"api": "0.4.8"
}
im Freifunk API Generator validiert, dann findet dieser alles okay, was falsch ist.
Das Python script hat jedoch recht, diese Datei ist nicht ok.
Es sieht so aus als ob der Freifunk API Generator hier gegen ein "empty schema" validiert - vermutlich also das Feld "schema" nicht extrahiert (ich habe diese Vermutung nicht im Quellcode des API Generators überprüft).
@andibraeu kannst Du mal schauen?
andibraeu
Unabhängig wie lange die draft-3 Freifunk JSON Schema noch im Einsatz sein werden, sollte diese nicht nur schematisch valide JSON Schema sein, sondern auch noch unproblematisch in der Handhabung werden.
Egal ob eine Soft-Migration zu draft-7 stattfinden wird (siehe auch https://github.com/freifunk/api.freifunk.net/issues/151) oder wie lange diese dauert, sollten wir die aktuellen draft-3 Freifunk JSON Schema Datei von Usability Problemen befreien.
Freifunk draft-3 JSON Schema sind aktuell problematisch Unsere Freifunk JSON Schema sind zwar gemäß http://json-schema.org/draft-03/schema# valide JSON Schema Dateien, jedoch sind diese gleichzeitig "empty schema". Was ist das? Ein "empty schema" ist ein JSON Schema das auf root-ebene keine der folgenden Schema Keywords enthält: https://tools.ietf.org/html/draft-zyp-json-schema-03#section-5 Nicht in der Spezifikation aufgeführte "Schema Keywords" werden ignoriert. Das steht in der Spec vom draft-3 zwar nicht explizit ist aber üblich unter den gängigen Validatoren - oft sogar ohne ein Hinweis auf das etwas ignoriert wurde. In der aktuellen draft-7 Spezifikation ist das Ignorieren aber explizit erwähnt: https://tools.ietf.org/html/draft-handrews-json-schema-01#section-4.3.1, was wirklich gut ist.
Da die Freifunk JSON Schema Dateien auf der Root-Ebene nur das Keyword "schema" (nicht verwechseln mit "$schema") verwenden und dieses nicht zur Spezifikation gehört wird es oft ignoriert und damit auch das eigentliche Freifunk JSON Schema welches sich eine Ebene tiefer befindet. Das führt dazu dass eine Validierung mit diesem JSON Schema zwangsläufig immer erfolgreich verlaufen ("empty schema"; da keine Regeln ausgewertet werden). Oder zumindest in einigen Validatoren anderes.
Einige Freifunk-Scripte (API Generator und o.g. Travis-CI Script) extrahieren daher den Teil unterhalb des "schema"-Feldes und bringen das damit auf Root-Ebene. Beispiel: https://github.com/freifunk/directory.api.freifunk.net/blob/master/tests/test.py#L28
Ein unerfahrener Entwickler oder Anwender aus einer lokalen Gruppe könnte gar nicht bemerkt haben das unser Freifunk JSON Schema einen "wrapper" in sich hat, der es zu einem "empty schema" macht, und alle seine Dateien damit immer als valide ausgibt, obwohl sie es nicht wären, wenn man den "Extract" als JSON Schema verwendet.
Alle Scripte die nicht kurzfristig auf draft-7 umgestellt werden können (z.B. fehlende unterstützung für draft-7) sollten von uns zumindest semantisch-saubere draft-3 Dateien bekommen. Auch hier würde ich diese gerne zunächst Zusätzlich im Repo ablegen um eine Soft-Migration bis z.B. 31.12.2019 zu ermöglichen.
(dieses Ticket wird dann für die Commit-Message und den PR verwendet)
Was haltet Ihr davon?