JSON-LD

Warum das zählt

Strukturierte Daten sind die Grundlage dafür, dass Suchmaschinen die Angaben einer Seite eindeutig zuordnen können. Aus ihnen entstehen erweiterte Suchergebnisse, also Rich Snippets mit Bewertungen, Preisen oder Öffnungszeiten. Welche Schreibweise ein Unternehmen dafür wählt, klingt nach einer Detailfrage. Sie entscheidet aber darüber, ob die Auszeichnung in zwei Jahren noch stimmt.

Bei den älteren Formaten Microdata und RDFa stehen die Angaben als zusätzliche Attribute mitten im HTML, direkt an den Elementen, die den Text anzeigen. Wer das Layout ändert, zerstört dabei leicht die Auszeichnung, ohne es zu merken. Ein Relaunch des Designs kostet dann nebenbei alle erweiterten Suchergebnisse.

JSON-LD liegt in einem eigenen Block. Layout und Auszeichnung lassen sich unabhängig voneinander ändern. Der Block ist an einer Stelle les- und prüfbar, statt über die ganze Seite verteilt zu sein. Genau diesen Punkt nennt Google als Grund für seine Empfehlung: JSON-LD sei die einfachste Lösung, um strukturierte Daten auch bei vielen Seiten umzusetzen und zu pflegen.

Wie es funktioniert

Browser zeigen den Inhalt eines Blocks vom Typ application/ld+json nicht an. Innen steht gültiges JSON, also verschachtelte Paare aus Schlüssel und Wert. Schlüssel, die mit dem Zeichen @ beginnen, sind reservierte Steuerwörter des Formats. Die Spezifikation definiert über zwanzig davon. In der Praxis begegnen einem vor allem diese vier:

Der Schlüssel, der am meisten unterschätzt wird, ist @id. Damit lassen sich Beziehungen ausdrücken, ohne Angaben zu wiederholen. Ein Beitrag verweist für seinen Autor auf die Kennung der Person, die Person verweist für ihren Arbeitgeber auf die Kennung der Firma. So entsteht ein Netz aus Entitäten statt einer Sammlung isolierter Angaben. Ein Beispiel mit zwei verknüpften Objekten in einem einzigen Block:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#firma",
      "name": "Beispiel GmbH",
      "url": "https://example.com/",
      "sameAs": ["https://www.linkedin.com/company/beispiel"]
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/kontakt#seite",
      "name": "Kontakt",
      "publisher": { "@id": "https://example.com/#firma" }
    }
  ]
}
</script>

Die Kennungen sind hier absolute Adressen mit einem Rautenzeichen und einem kurzen Namen dahinter. Sie müssen keine aufrufbare Seite bezeichnen. Sie müssen nur auf der gesamten Website eindeutig sein und über die Zeit stabil bleiben. Die Eigenschaft sameAs nimmt Adressen weiterer Profile derselben Organisation auf, etwa in Verzeichnissen oder Netzwerken. Wie das Zusammenspiel wirkt, steht ausführlicher unter sameAs.

In der Praxis

Der Block darf im Kopfbereich der Seite stehen oder im Rumpf. Google wertet beide Positionen aus und liest JSON-LD laut eigener Dokumentation auch dann, wenn es erst durch JavaScript oder ein eingebundenes Widget in die Seite eingefügt wird. Der Kopfbereich hat trotzdem einen praktischen Vorteil: Dort findet ihn jeder sofort, der den Quelltext prüft.

Bei einer selbst gepflegten Website erzeugt man den Block am besten automatisch aus denselben Daten, aus denen auch die sichtbare Seite entsteht. Handgepflegte Blöcke laufen sonst auseinander, sobald sich ein Preis oder eine Öffnungszeit ändert. Bei Content-Management-Systemen übernehmen das meist Erweiterungen. Deren Ausgabe sollte man einmal ansehen, weil viele mehr ausgeben als nötig und dabei Angaben ergänzen, die auf der Seite gar nicht stehen.

Zum Prüfen hat sich diese Reihenfolge bewährt:

1. Quelltext ansehen. Im Browser den Seitenquelltext öffnen und nach application/ld+json suchen. Erscheint nichts, wird der Block entweder gar nicht ausgegeben oder erst durch JavaScript ergänzt. Dann hilft die Elementansicht der Entwicklerwerkzeuge, die das fertig zusammengebaute HTML zeigt.
2. Auf Gültigkeit prüfen. Die Adresse in Googles Test für Rich-Suchergebnisse geben. Er meldet, welche Typen er gefunden hat, und listet Fehler und Warnungen einzeln auf.
3. Ergebnis einordnen. Der Test deckt nur die Typen ab, für die Google erweiterte Suchergebnisse ausliefert. Welche das sind, führt die Hilfe zum Testwerkzeug einzeln auf. Taucht eine gültige Auszeichnung dort nicht auf, ist sie nicht zwingend falsch. Für solche Typen prüft der Schema Markup Validator von Schema.org gegen das Vokabular.
4. Nach jeder Änderung wiederholen. Ein Update des Systems, ein neues Template oder eine zusätzliche Erweiterung können den Block verändern, ohne dass an der sichtbaren Seite etwas auffällt.

Fehlerfrei bedeutet: Die Auszeichnung ist lesbar und der erwartete Typ wird erkannt. Ob daraus tatsächlich ein erweitertes Suchergebnis entsteht, entscheidet Google im Einzelfall und sagt es niemandem zu.

Häufige Fehler

Ungültige Syntax. Ein fehlendes Komma oder eine überzählige schließende Klammer macht den ganzen Block unbrauchbar. JSON wird als Ganzes verarbeitet, deshalb fällt nicht nur die betroffene Zeile aus, sondern alles, was in diesem Block steht. Weitere gültige Blöcke auf derselben Seite bleiben davon unberührt, weil jeder Block für sich gelesen wird.

HTML-Zeichenfolgen im Block. Innerhalb eines script-Elements werden HTML-Entities nicht aufgelöst. Wer ü statt „ü“ schreibt, bekommt genau diese Zeichenfolge als Wert. Ein doppeltes Anführungszeichen im Text muss mit einem umgekehrten Schrägstrich maskiert werden. Die Zeichenfolge </script> darf in keinem Wert unmaskiert vorkommen, weil der Browser dort das Element beendet.

Mehrere Blöcke mit widersprüchlichen Angaben. Wenn eine Erweiterung und eine eigene Auszeichnung dieselbe Sache unterschiedlich beschreiben, entsteht ein Widerspruch. Zwei verschiedene Firmennamen für dieselbe Kennung sind schlechter als gar keine Auszeichnung.

Kennungen vergeben, aber nicht verwenden. Ein @id, auf das nirgends verwiesen wird, verbindet nichts. Der Nutzen entsteht erst, wenn andere Objekte darauf zeigen.

Angaben, die nicht auf der Seite stehen. Auch wenn der Block unsichtbar ist, gelten die Richtlinien für strukturierte Daten. Google verlangt dort ausdrücklich, keine Inhalte auszuzeichnen, die für Leser der Seite nicht sichtbar sind, und untersagt irreführende Auszeichnungen wie erfundene Bewertungen.

Abgrenzung

JSON-LD ist die Schreibweise, Schema.org das Vokabular. Das eine legt fest, wie geschrieben wird, das andere, was geschrieben werden kann. Beide sind unabhängig voneinander: Schema.org lässt sich auch als Microdata notieren, und JSON-LD kann andere Vokabulare aufnehmen.

Von gewöhnlichem JSON unterscheidet sich JSON-LD durch @context. Erst diese Angabe gibt Schlüsseln wie name oder address eine feste, maschinenlesbare Bedeutung. Ohne Kontext ist ein Schlüssel nur eine Zeichenfolge, deren Sinn jedes System selbst raten müsste.

Von Microdata und RDFa unterscheidet sich JSON-LD durch die Trennung von Auszeichnung und Layout. Google verarbeitet alle drei Formate gleichwertig, solange die Auszeichnung gültig und korrekt umgesetzt ist. Ausdrücklich empfohlen wird jedoch nur JSON-LD, und nur bei JSON-LD liegt die Auszeichnung so weit vom Layout getrennt, dass ein Umbau des Designs sie nicht zwangsläufig mitreißt.