To main content
Featured image of Webtrees-Plugin: json-ld

Webtrees-Plugin: json-ld

Veröffentlicht von Benjamin Marwell am

Nun habe ich es endlich mal geschafft, etwas Software zu schreiben, die ein größerer Benutzerkreis nutzen könnte: JSON-LD für die Web-Genealogie-Software Webtrees, über die ich schon geschrieben habe. Maschinenlesbare Daten eröffnen den freien Zugriff auf Genealogie-Daten.

Webtrees jsonld data highlighted

Zweck von json-ld im Stammbaum

Für den Einsatz von json-ld im Stammbaum sprechen viele Gründe. Zum einen werden Daten, die sowieso bereits vorhanden sind, maschinenlesbar dargestellt. Zum anderen kann diese Darstellung helfen, Daten miteinander zu verknpüfen. Und genau dafür ist json-ld gedacht: Das Verknüpfen bestehnder Daten, sowie die Lesbarkeit für Maschinen zu erhöhen.

[caption id="attachment_5838" align="aligncenter" width="1035"]Open Graph mit Graham Bell / Google-SucheOpen Graph mit Graham Bell / Google-Suche[/caption]

Mögliche Einsatzzwecke sind etwa Genealogie-Netze oder auch die Google Graph Search. Bereits jetzt werden Personendaten aus Wikipedia (bzw. maschinenlesbar aus Wikisource) herausgelesen und in einer Seitenleiste angezeigt. Damit erhält der Suchende die gewünschten Informationen auf einen Blick. Solche Ergebnisse halte ich auch für einen Stammbaum für möglich.

Context: Schema.org

Innerhalb von json-ld können verschiedene Daten abgelegt werden. Die Art der Daten werden über die Felder @context  und @type  gekennzeichnet. Ich benutze in diesem Projekt den Kontext (bzw. das Vokabular) von Schema.org, der Typ ist in den meisten Fällen eine Person. Das hat den einfachen Hintergrund, dass Google dieses Vokabular versteht und dieses damit auch wohl die weiteste Verbreitung finden wird. Weitere implementierte Typen sind die Adressen, ImageObjects und ggf. später noch weitere Inhalte nach Bedarf.

Im Kontext könnten natürlich auch andere Angaben stehen, etwa die Beschreibung einer vCard nach w3c oder eigene Inhalte. Da das Vokabular von schema.org aber völlig ausreichend und in sich schlüssig ist, halte ich hier weitergehende oder gar eigene Definitionen für unnötig.

Entwicklung auf Github

Die Entwicklung findet auf Github statt. Zusätzlich gibt es eine Englische und Deutsche Beschreibung von webtrees-jsonld auf meiner Homepage.

Wer mir Pull-Requests schicken möchte, darf das gerne tun. Dabei sind - soweit wie möglich - die Issues zu beachten. Ich betreibe folgende Entwicklungszweige:

  • Master enthält die Releases für die aktuellste webtrees-Version. Releasefähige next-Zweige werden hier reingemergt, jedoch immer nur für die aktuellste Webtrees-Version.
  • next-16 enthält Entwicklungen für webtrees 1.6. Sobald 1.7 erscheint werden hier auch release-Tags gesetzt, und ggf. findet hier eine geringe Weiterentwicklung für Bugfixes statt.
  • next-17 Hauptentwicklungszweig für Webtrees 1.7. Dieser wird eröffnet, sobald ich mit der Funktionalität des Plugins zufrieden bin. Da die aktuelle Version von Webtrees noch 1.6 ist, existiert dieser Zweig noch nicht.
  • div. Branches ... werden für neue Features genutzt. Und danach wieder gelöscht.

Testen der Ergebnisse

Die Ergebnisse lassen sich durch den Aufruf der Website, oder auch durch das sog. Parsen (Auswerten) testen. In jedem Fall wird dabei wird der HTML-Quellcode ausgelesen und auf Gültigkeit geprüft. Einen Schritt weiter geht Google mit dem Structured Data Testing Tool: Es wird ebenfalls auf inhaltliche Korrektheit geprüft, in dem bekannte Elemente von schema.org mit den gefundenen verglichen werden.

Test per Befehlszeile

Man kann wie folgt prüfen, ob die Daten korrekt hinterlegt sind:
curl -so - "http://pfad.zu/webtrees/individual.php?pid=I1&ged=AllGED" | \
    xmllint --html --xpath "//script[@id='json-ld-data']/text()" - 2>/dev/null | \
    jq -C '.'

Was hier passiert: Zunächst wird die URL zu einer Person (I1 ) aufgerufen und die Ausgabe auf den Bildschirm ausgegeben (per -o - ). Das Ergebnis wird von xmllint interpretiert. Es wird über xpath das Script-Element mit der ID json-ld-data  extrahiert und nur dessen Inhaltstext ausgegeben. Dieses json-Objekt wird von jq -C  noch gefärbt. Das Ergebnis sieht in etwa wie folgt aus.

[caption id="attachment_5840" align="aligncenter" width="807"]Curl mit XMLLint und JQ für JSON-Farbausgabe.Curl mit XMLLint und JQ für JSON-Farbausgabe.[/caption]

Test über den Aufruf der Webseite

Das Plugin schreibt das Skript-Element in einen Webtrees-Tab. Damit man als Benutzer davon etwas sieht, habe ich die Ausgabe zusätzlich mit HTML-Kodierten HTML-Elementen in einen <pre> -Tag gestellt. Der Aufruf der Seite zeigt also den Inhalt ebenfalls an.

[caption id="attachment_5839" align="aligncenter" width="1249"]Webtrees: Json-LD-TabWebtrees: Json-LD-Tab[/caption]

Die Ausgabe sollte in etwa der gezeigten entpsrechen, nur mit den Daten der aufgerufenen Person.

Test über Googles Structured Data Testing Tool

Letztendlich ist aber wichtig, dass die Daten auch inhaltlich lesbar sind. Ein falsches Datum, das nicht im ISO-Format ist, kann etwa schon ein Problem darstellen. Auch eine leere oder ungültig befüllte Liste ist möglicherweise problematisch. Daher ist es wichtig, die Daten auch in möglichen Zielsystemen zu testen. Google stellt hierfür das Structured Data Testing Tool bereit.

structured-data-testing-tool_henrytudorGut zu sehen ist hier, dass beim Klick auf ein Zielelement auch die entsprechende Stelle im Quellcode merkiert wird. Das ist für die Fehlerbehebung sehr praktisch. Sollten hier Fehler auftreten, bitte ich um Rückmeldung von Issues auf Github.

Download und Installation

Downloads wird es unter Github-Releases geben. Die Installation ist in der Readme.md beschrieben. Pro Webtrees-Version wird es getrennte Releases geben.

Weblinks