Draft-3 Freifunk JSON Schema, zwar valide, aber problematisch

[christian-weiss]

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 #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?

[christian-weiss]

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": "[email protected]"
  },
  "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?

[christian-weiss]

Ich dachte das "empty schema" issue wäre durch diesen Commit bereits behoben:
45f41f6

Vermutlich nutzt der API Generator noch den alten Stand der Spec-Dateien (also älter als 23 Tage).

[christian-weiss]

BTW: Ich nutze zur Validierung von Freifunk API Dateien gegen das Freifunk Schema gerne:
jsonschema -i instanceData.json 0.4.16.json

Mit diesem Docker Container:
https://hub.docker.com/repository/docker/freifunkhamm/jsonschema

[andibraeu]

der generator wird auch bald umgestellt, hier entsteht die neue Version: https://freifunk.github.io/generator.api.freifunk.net/

[andibraeu]

alles bis auf den Generator sollte auch schon funktionieren, z.b. auch der api viewer unter http://api-viewer.freifunk.net/

[andibraeu]

Mit der Umstellung auf draft-7 im Rahmen des GSoC-Projekts sind die Regeln auch ein wenig strenger geworden und wir haben Fehler entdeckt, die uns vorher einfach nicht aufgefallen sind, z.b. https://api-viewer.freifunk.net/bamberg.html#validation

Dort ist das networks-feld einfach in einer falschen ebene gelandet