Strukturierte Daten in CI automatisiert testen statt manuell im Rich-Results-Test zu prüfen

1. Warum manuelles Prüfen im Rich-Results-Test nicht skaliert

Der Rich-Results-Test von Google ist ein hervorragendes Werkzeug, um eine einzelne URL punktuell zu prüfen, aber er ist als manuelles Werkzeug konzipiert und lässt sich nicht ohne Weiteres in einen automatisierten Entwicklungsprozess einbinden. Bei einer Website mit hunderten Produktseiten, Kategorieseiten und Blogartikeln, die alle unterschiedliche Schema-Typen wie Product, BreadcrumbList oder Article ausliefern, ist es schlicht nicht praktikabel, nach jedem Deployment jede betroffene Seite einzeln von Hand zu kontrollieren.

Das eigentliche Risiko liegt darin, dass fehlerhaftes Schema-Markup oft unbemerkt bleibt, weil es die sichtbare Darstellung der Seite für normale Nutzer nicht beeinträchtigt. Ein Theme-Update, ein CSS-Refactoring oder eine Änderung an einem Template kann ein JSON-LD-Snippet versehentlich entfernen oder beschädigen, ohne dass im Frontend irgendetwas sichtbar kaputtgeht, sodass der Fehler erst auffällt, wenn Rich Snippets in der Suche verschwinden und der Traffic bereits gesunken ist.

2. Schema-Validierungs-Tools für die Kommandozeile

Für die automatisierte Validierung eignen sich Kommandozeilen-Tools, die JSON-LD- oder Microdata-Markup gegen die Schema.org-Spezifikation sowie gegen die von Google dokumentierten Anforderungen für Rich Results prüfen. Das Node-Paket 'structured-data-testing-tool' etwa lädt eine URL oder eine lokale HTML-Datei, extrahiert das enthaltene Markup und prüft es gegen konfigurierbare Presets für Google-, Twitter- oder Facebook-spezifische Anforderungen, inklusive Pflichtfeldern je Schema-Typ.

Alternativ lassen sich JSON-LD-Snippets auch direkt gegen offizielle Schema.org-Definitionen validieren, etwa mit Bibliotheken, die ein JSON-Schema aus der Schema.org-Vokabular ableiten und Markup dagegen prüfen. Für Magento-Projekte bietet es sich an, ein kleines Skript zu schreiben, das die generierten Kategorie- und Produktseiten per Headless-Browser rendert, das JSON-LD extrahiert und anschließend gegen die erwarteten Pflichtfelder wie Preis, Verfügbarkeit und Bewertung prüft.

3. CI-Pipeline-Integration: Den Build bei fehlerhaftem Schema blockieren

Damit fehlerhaftes Schema-Markup gar nicht erst live geht, sollte die Validierung als eigener Job in der CI-Pipeline laufen, der eine repräsentative Auswahl an Seitentypen rendert und deren strukturierte Daten prüft. Schlägt die Validierung fehl, etwa weil ein Pflichtfeld fehlt oder ein falscher Datentyp verwendet wird, sollte der Job mit einem Fehlercode abbrechen und dadurch den gesamten Build blockieren, genauso wie es bei fehlschlagenden Unit-Tests der Fall wäre.

Wichtig ist, den Job so zu gestalten, dass er nicht bei jeder minimalen Abweichung blockiert, sondern nur bei tatsächlich kritischen Fehlern wie fehlenden Pflichtfeldern oder ungültigem JSON, während Warnungen zu optionalen, aber empfohlenen Feldern lediglich als Kommentar im Merge-Request erscheinen. Diese Abstufung verhindert, dass Entwickler die Prüfung als ständige Blockade wahrnehmen und im schlimmsten Fall dazu neigen, sie zu umgehen.

# .gitlab-ci.yml
structured-data-check:
  stage: test
  image: node:20-alpine
  script:
    - npm ci
    - node scripts/validate-schema.js --urls=config/schema-check-urls.txt --fail-on=error
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'
  allow_failure: false

4. Welche Schema-Fehler in der Praxis am häufigsten auftreten

Der häufigste Fehlertyp ist ein fehlendes Pflichtfeld, etwa ein Product-Schema ohne Preisangabe oder ein Review-Schema ohne Bewertungsskala, weil Google für viele Rich-Result-Typen strikte Mindestanforderungen definiert, die über die reine Schema.org-Spezifikation hinausgehen. Ein zweiter häufiger Fehler ist ein falscher Datentyp, etwa ein Preis als Text mit Währungssymbol statt als reine Zahl, was technisch gültiges JSON-LD erzeugt, aber von Google nicht als korrekt anerkannt wird.

Ebenfalls häufig sind widersprüchliche Angaben zwischen dem sichtbaren Seiteninhalt und dem strukturierten Markup, etwa wenn der angezeigte Preis im Frontend von dem im JSON-LD hinterlegten Preis abweicht, weil eine Preisänderung nur an einer der beiden Stellen im Code nachgezogen wurde. Solche Inkonsistenzen werden von Google als Verstoß gegen die Richtlinien gewertet und können zum vollständigen Entzug der Rich-Snippet-Berechtigung für die betroffene Domain führen.

5. Monitoring bestehender Live-Seiten nach Deployments

Ein CI-Check vor dem Deployment deckt nur die getesteten Seitentypen ab, während im Live-Betrieb durch redaktionelle Änderungen, Produktimporte oder Drittanbieter-Plugins jederzeit neue Probleme entstehen können, die kein CI-Job vorab sieht. Deshalb sollte zusätzlich ein regelmäßiges Monitoring der Live-Seite laufen, das eine repräsentative Stichprobe wichtiger URLs, etwa die traffic-stärksten Produkt- und Kategorieseiten, täglich oder wöchentlich erneut crawlt und das aktuelle Schema-Markup mit dem letzten bekannten guten Zustand vergleicht.

Für dieses Monitoring eignen sich entweder dedizierte SEO-Monitoring-Plattformen mit Schema-Überwachungsfunktion oder ein selbst geschriebenes Skript, das per Cronjob läuft, die Ergebnisse in einer Datenbank ablegt und bei Abweichungen einen Diff zum vorherigen Lauf erzeugt. Wichtig ist, dass das Monitoring nicht nur prüft, ob überhaupt JSON-LD vorhanden ist, sondern auch, ob die enthaltenen Werte inhaltlich plausibel sind, etwa ob ein Preis von null Euro oder ein leeres Bewertungsfeld auf einen zugrunde liegenden Datenfehler hindeutet.

6. Regressionen nach Deployments früh erkennen

Eine Regression im Schema-Markup entsteht typischerweise dann, wenn ein Theme-Update ein Template verändert, das JSON-LD-Snippet ausgibt, ohne dass der Entwickler wusste, dass genau dieses Template für strukturierte Daten verantwortlich ist. Besonders anfällig sind Layout-Refactorings, bei denen ein Block im Seitenaufbau verschoben oder entfernt wird, weil in vielen Systemen das JSON-LD als eigener, leicht übersehbarer Block im Template-Baum eingebunden ist.

Ein automatisierter Vergleich zwischen dem Schema-Zustand vor und nach jedem Deployment, idealerweise als Teil des Monitorings, macht solche Regressionen innerhalb von Stunden statt Wochen sichtbar. Je früher ein Team erkennt, dass ein Deployment strukturierte Daten beschädigt hat, desto einfacher lässt sich die Ursache noch im Kontext der ursprünglichen Änderung finden, statt Wochen später in einem gewachsenen Commit-Verlauf danach suchen zu müssen.

7. Alerting bei erkannten Fehlern einrichten

Monitoring ohne Alerting bringt wenig, wenn niemand die Ergebnisse regelmäßig auswertet, weshalb sich eine Benachrichtigung über Slack, E-Mail oder ein Ticket-System anbietet, sobald das Monitoring eine kritische Abweichung feststellt. Die Benachrichtigung sollte konkret genug sein, um sofort handlungsfähig zu sein, also die betroffene URL, den fehlenden oder fehlerhaften Feldnamen und idealerweise einen Link zum letzten funktionierenden Zustand enthalten.

Um Alarmmüdigkeit zu vermeiden, sollten nur tatsächlich kritische Fehler eine sofortige Benachrichtigung auslösen, während kleinere Abweichungen in einem wöchentlichen Sammelbericht zusammengefasst werden. Ein Team, das bei jeder kleinsten Warnung eine Slack-Nachricht erhält, beginnt früher oder später, diese Nachrichten zu ignorieren, wodurch auch die wirklich wichtigen Meldungen untergehen.

8. Best Practices für den Team-Workflow

Damit die automatisierte Prüfung im Alltag akzeptiert wird, sollte sie frühzeitig im Entwicklungsprozess ansetzen, idealerweise bereits als lokaler Pre-Commit-Hook für Entwickler, die an Templates mit Schema-Markup arbeiten, und nicht erst als letzte Hürde vor dem Produktions-Deployment. Ergänzend hilft eine kurze, zentrale Dokumentation, welche Seitentypen welches Schema ausliefern müssen und welche Felder dabei zwingend erforderlich sind, damit neue Teammitglieder nicht bei jeder Änderung raten müssen.

Sinnvoll ist zudem, die Liste der zu prüfenden URLs regelmäßig zu aktualisieren, wenn neue Seitentypen oder Schema-Typen hinzukommen, etwa ein neues FAQ-Schema für Ratgeberseiten oder ein Event-Schema für eine neue Veranstaltungsseite. Eine veraltete Prüfliste erzeugt trügerische Sicherheit, weil sie zwar grün anzeigt, aber neue, ungeprüfte Seitentypen gar nicht erfasst.

9. Grenzen automatisierter Tests: Manuelle Stichproben bleiben nötig

Auch die beste automatisierte Prüfung ersetzt nicht vollständig den gelegentlichen Blick in den echten Rich-Results-Test oder in die Google Search Console, weil Google seine Anforderungen an strukturierte Daten von Zeit zu Zeit ändert und neue Rich-Result-Typen einführt, die ein selbst geschriebenes Validierungsskript zunächst nicht kennt. Eine quartalsweise manuelle Stichprobe wichtiger Seitentypen im offiziellen Test-Tool von Google fängt solche Änderungen ab, bevor sie zu unbemerkten Lücken in der automatisierten Prüfung werden.

Auch die Search-Console-Berichte zu strukturierten Daten sollten regelmäßig manuell gesichtet werden, weil sie teilweise Informationen liefern, etwa zur tatsächlichen Darstellung von Rich Snippets in den Suchergebnissen, die eine reine Code-Validierung nicht abbilden kann. Automatisierte Tests und manuelle Kontrolle ergänzen sich also, statt sich gegenseitig zu ersetzen, und genau diese Kombination liefert die zuverlässigste Absicherung für strukturierte Daten im laufenden Betrieb.

10. Zusammenfassung

11. FAQ: Strukturierte Daten in CI: Das Wichtigste auf einen Blick