JSON-LD-Viewer und Checker für strukturierte Daten

Was JSON-LD ist, und warum es ein Graph ist

JSON-LD sind strukturierte Daten als JSON in einem <script type="application/ld+json">-Tag. Das Format beschreibt die Seite im Vokabular von schema.org (das ist ein Product namens Blue Mug, es kostet 24 USD, diese Organization verkauft es), damit Suchmaschinen und KI-Assistenten nicht aus dem Layout raten müssen. Google liest JSON-LD, Microdata und RDFa und empfiehlt JSON-LD.

Jedes Objekt hat ein @type. Es kann auch ein @id haben, einen Bezeichner, meist die Seiten-URL plus ein Fragment, zum Beispiel https://example.com/#organization. Jedes andere Objekt kann dann per @id darauf zeigen, statt es zu wiederholen. So sagt eine Seite: diese WebPage gehört zu dieser WebSite, diese Organization veröffentlicht die WebSite, und das Product auf der Seite stammt von derselben Organization.

Wenn die Referenzen zusammenpassen, beschreibt die Seite einen verbundenen Satz von Fakten. Wenn eine nicht passt, wegen eines Tippfehlers in einer @id oder eines Zeigers auf eine Organization, die nur die Startseite ausgibt, parst jeder Block weiter und die Verbindung geht still verloren. Eine Eigenschaftenliste zeigt dir das nicht. Ein Graph schon: Die Entität, die verbunden sein sollte, steht allein, oder ein Pfeil endet an einer gestrichelten Karte.

So liest du den Graphen

• Jede Karte ist eine Entität. Die farbigen Labels sind ihr @type. Darunter steht der Name (oder headline, title oder URL) und bis zu vier Klartext-Eigenschaften.
• Ein Pfeil läuft von der Entität mit der Eigenschaft zu der Entität, auf die sie zeigt, beschriftet mit dem Eigenschaftsnamen: offers, brand, publisher, author, isPartOf.
• Entitäten, auf die nichts zeigt, stehen in der linken Spalte. Jede Spalte weiter rechts ist einen Schritt tiefer.
• Eine gestrichelte Karte mit „Referenziert, nie definiert“ ist eine @id, auf die etwas zeigt, die aber nichts auf der Seite beschreibt.
• Objekte mit derselben @id werden zu einer Karte zusammengeführt, auch in getrennten script-Blöcken. Wenn du zwei Karten erwartest und eine siehst, teilen sie sich eine @id.
• Gelesen wird nur JSON-LD, nicht Microdata oder RDFa. Sehr große Graphen zeigen die ersten 150 Entitäten. PNG herunterladen speichert den Graphen auf weißem Grund, fertig für ein Ticket oder einen Kundenbericht.

Was der Wert und die Probleme bedeuten

Der Wert läuft von 0 bis 100 und gewichtet sechs Dinge: ob das JSON-LD wohlgeformt ist (20 %), ob die Eigenschaften da sind, die Google für ein Rich-Suchergebnis verlangt (30 %), ob Werte das richtige Format haben (20 %), empfohlene Eigenschaften (15 %), ob @id-Referenzen aufgehen (10 %) und kleine Best Practices (5 %). Eine Seite ohne JSON-LD hat 0.

Probleme stehen mit den Fehlern zuerst. Jedes beginnt mit einem Pfad wie Product.offers.price, den du in deiner Vorlage suchen kannst. Das sind die Meldungen, die du siehst, und was du bei jeder tun kannst:

Block ist kein gültiges JSON

Ein Syntaxfehler, also wird der ganze Block ignoriert. Übliche Ursachen: ein nachgestelltes Komma, ein nicht escaptes doppeltes Anführungszeichen in einem String, oder eine Template-Variable, die nichts ausgegeben hat. Schick den Block durch einen JSON-Parser und korrigiere die Zeile, die er nennt.

@context fehlt

Ohne @context bedeuten die Eigenschaftsnamen nichts. Füge "@context": "https://schema.org" zu jedem Top-Level-Objekt hinzu. Wenn deins http://schema.org sagt, funktioniert das auch. https ist die bevorzugte Form, deshalb erscheint es nur als Hinweis.

Knoten hat kein @type

Ein Objekt mit Eigenschaften, aber ohne Typ, lässt sich nicht deuten. Füge das @type hinzu, das sagt, was es ist, zum Beispiel Offer, Person oder PostalAddress.

… verlangt …; ohne das ist das Rich-Suchergebnis nicht zulässig

Google führt diese Eigenschaft als Pflicht für das Rich-Suchergebnis des Typs. Ein Event braucht name, startDate und location. Eine BreadcrumbList braucht itemListElement. Füge sie mit dem echten Wert von der Seite hinzu.

… sollte … enthalten

Eine empfohlene Eigenschaft fehlt. Das Markup bleibt ohne sie zulässig, das Ergebnis kann aber weniger zeigen. Füge sie nur hinzu, wenn sie stimmt. Erfinde keine Bewertung und keine Rezensionszahl, um einen Hinweis zu löschen.

erwartet wurde eine Zahl / eine absolute http(s)-URL / ein ISO-8601-Datum / ein verschachteltes Objekt mit einem @type

Der Wert hat die falsche Form. Ein Preis von "$24.00" sollte 24.00 sein, die Währung steht in priceCurrency. Ein Datum wie "Sept 3, 2026" sollte "2026-09-03" sein. Ein Bildpfad wie /img/mug.jpg sollte die volle URL sein. Ein Autor als Klartext sollte ein Person- oder Organization-Objekt mit einem name sein. Werte aus einer festen Liste, wie availability, müssen einer der genannten sein, zum Beispiel https://schema.org/InStock.

… enthält …, erwartet wurde …

Das verschachtelte Objekt hat den falschen Typ, zum Beispiel eine Adresse, die ein Person enthält. Ändere sein @type auf den Typ, den die Meldung nennt.

Positionen … müssen 1..n ohne Lücken laufen / jeder Krümel außer dem letzten braucht ein item

In einer BreadcrumbList muss position 1, 2, 3 ohne Lücken zählen. Jeder Krümel außer dem letzten (die aktuelle Seite) braucht ein item mit der URL dieses Krümels.

@id "…" wird referenziert, aber auf dieser Seite nie definiert

Das ist die gestrichelte Karte im Graphen: Etwas zeigt auf eine @id, die nichts auf dieser Seite beschreibt. Meist ein Tippfehler (#org statt #organization, http statt https, ein fehlender Slash am Ende) oder die Entität wird nur auf einer anderen Seite ausgegeben, oft die Organization der Startseite. Eine Referenz ist kein Link, und nichts holt sie ab. Korrigiere die Schreibweise oder gib die Entität auch auf dieser Seite aus.

… getrennte Entitäten ohne @id-Querverweise zwischen ihnen

Mehrere Top-Level-Entitäten, die nie aufeinander zeigen. Das ist gültig, sie lesen sich aber als unverbundene Fakten. Gib jeder eine @id und verbinde sie: isPartOf der WebPage zur WebSite, publisher eines Article zur Organization.

… hat kein Rich-Suchergebnis, das wir prüfen können

Für diesen Typ haben wir keine Regeln. Das ist kein Fehler: Die Entität erscheint weiter im Graphen, und alles darin Verschachtelte wird weiter geprüft.

Ein durchgerechnetes Beispiel

Eine Produktseite gibt eine Organization, eine WebPage und ein Product in einem @graph aus. Jeder Teil parst, und auf den ersten Blick sieht es gut aus:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Coffee Co.",
      "url": "https://example.com/",
      "logo": "https://example.com/logo.png"
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/products/blue-mug#webpage",
      "name": "Blue Mug",
      "url": "https://example.com/products/blue-mug"
    },
    {
      "@type": "Product",
      "@id": "https://example.com/products/blue-mug#product",
      "name": "Blue Mug",
      "image": "https://example.com/img/blue-mug.jpg",
      "mainEntityOfPage": { "@id": "https://example.com/products/blue-mug#webpage" },
      "brand": { "@id": "https://example.com/#org" },
      "offers": {
        "@type": "Offer",
        "price": "$24.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock"
      }
    }
  ]
}

Der Graph zeigt, was der Code verbirgt. Die Organization steht allein in der linken Spalte, nichts zeigt auf sie, und der brand-Pfeil des Product endet an einer gestrichelten Karte für https://example.com/#org. Die Problemliste sagt dasselbe, mit Pfaden:

error  Product.offers.price
       price on Offer: expected a number, got the bare text "$24.00"
error  Product.brand
       @id "https://example.com/#org" is referenced but never defined on this page

Die Korrektur sind zwei Zeilen: Zeige mit brand auf die @id, die die Organization wirklich nutzt, und nimm das Währungssymbol aus dem Preis.

"brand": { "@id": "https://example.com/#organization" },
…
  "price": 24.00,

Der Wert geht von 79 auf 94, und die Organization ist jetzt mit dem Product verbunden. Die vier übrigen Hinweise verlangen sameAs, sku, aggregateRating und die url des Angebots. Füge die hinzu, die für den Shop stimmen. Ein Produkt ohne Rezensionen sollte keine Bewertung tragen.

Fragen