JSON-LD in Drupal: so erzeugen Sie strukturierte Daten aus Feldern mit Schema.org Metatag

Der sicherste Weg, JSON-LD in Drupal hinzuzufügen, ist das Mapping von Schema.org-Properties auf bestehende Content-Felder. Konfigurieren Sie das Mapping einmal pro Content Type mit Metatag und Schema.org Metatag. Redakteure pflegen Produkt, Artikel oder Service wie gewohnt, während Drupal das JSON-LD aus denselben Werten erzeugt, die auf der Seite sichtbar sind.

JSON-LD in Drupal funktioniert am besten, wenn strukturierte Daten aus demselben Feldmodell kommen, das auch die sichtbare Seite speist. So vermeiden Sie eine zweite, versteckte Kopie von Preisen, Namen und Verfügbarkeit. Gleichzeitig erhält das Entwicklungsteam Konfiguration zum Exportieren, Prüfen und Testen. Lesen Sie auch: Schema.org und Metadaten in Drupal - das breitere Bild, bevor Sie einzelne Bundles mit Schema.org Metatag mappen.

Das ist besser, als Redakteure eine zweite, versteckte Faktensammlung pflegen zu lassen. Das Setup ist unkompliziert. Der schwierige Teil ist die Entscheidung, welche Felder maßgeblich sind, wie leere Werte behandelt werden und wie verhindert wird, dass ein neuer Content Type ohne Mapping in Produktion geht. Auch technisches SEO hängt davon ab, dass Markup und sichtbarer Inhalt übereinstimmen - nicht nur daran, dass die Syntax einen Validator besteht.

In diesem Artikel:

• Warum driftet handgeschriebenes JSON-LD vom Seiteninhalt ab?
• Welche Schema.org-Metatag-Submodule sollten Sie aktivieren?
• Wie konfigurieren Sie Metatag-Defaults vor dem Property-Mapping?
• Wie mappen Sie Drupal-Felder auf Product-JSON-LD?
• Wie exportieren Sie Schema.org-Metatag-Mapping als Drupal-Config?
• Was passiert, wenn Preisfelder in JSON-LD leer sind?
• Wie halten Sie mehrsprachiges JSON-LD an übersetzten Seiten ausgerichtet?
• Wie validieren Sie JSON-LD auf gerenderten Drupal-Seiten?
• Wie testen Sie Schema.org-Abdeckung in CI?
• Wie bauen Sie eine redaktionelle Queue für Structured-Data-Review?
• Wie integrieren Sie JSON-LD-Mapping in den Content-Type-Workflow?

Warum driftet handgeschriebenes JSON-LD vom Seiteninhalt ab?

Nehmen Sie an, eine Produktseite zeigt einen Preis von EUR 249. Das Seiten-Template liest den Wert aus field_price, aber jemand hat dieselbe Zahl manuell in einen JSON-LD-Block eingetragen.

Das Commercial-Team ändert den Preis auf EUR 269. Die sichtbare Seite aktualisiert sich. Das versteckte Markup nicht.

Jetzt macht die Seite zwei Aussagen über dasselbe Produkt. Die Syntax-Validierung kann weiterhin bestehen, weil beide Werte gültige Zahlen sind. Das Problem ist die Genauigkeit.

Googles Structured-Data-Richtlinien sagen, dass Markup sichtbaren Inhalt beschreiben soll. Produktname, Preis oder Verfügbarkeit in JSON-LD sollten daher aus derselben Quelle kommen wie der sichtbare Wert. Dasselbe gilt, wenn Text in Bildern Fakten vor Suche und KI-Fetchern verbirgt - wenn der Fakt nicht im HTML steht, kann strukturierte Daten ihn nicht zuverlässig ersetzen.

Drupal hat diese Quelle bereits: Felder.

Schema.org Metatag erweitert das Metatag-Modul. Es definiert Gruppen für Typen wie Article, Product, Service, Organization und WebSite und rendert die konfigurierten Properties als application/ld+json-Skript im Page Head. Tokens verbinden diese Properties mit Entity-Feldern.

Eine Bearbeitung kann beide Ausgaben aktualisieren.

Welche Schema.org-Metatag-Submodule sollten Sie aktivieren?

Schema.org Metatag 3.0.4 unterstützt Drupal 9, 10 und 11. Das Basismodul benötigt Metatag und PHP 8 oder neuer. Installieren Sie das Paket mit Composer:

composer require 'drupal/schema_metatag:^3.0'

Aktivieren Sie das Basismodul und die Submodule, die zu den Seiten passen, die Sie markieren wollen. Für einen Produktkatalog:

drush en schema_metatag schema_product schema_organization schema_web_site -y
drush cr

Aktivieren Sie nicht automatisch jedes Submodule. Jedes fügt eine weitere Einstellungsgruppe und einen weiteren Typ hinzu, den das Team sich verpflichtet fühlen könnte zu konfigurieren. Starten Sie mit Seiten, die nützliche, gepflegte Daten enthalten.

Ein sinnvoller erster Schritt:

• schema_web_site und schema_organization für site-weite Identität,
• schema_article für Artikel und News,
• schema_product für echte Produktseiten,
• schema_service für Service-Seiten, wenn die Properties sichtbaren Content beschreiben,
• die Breadcrumb-Unterstützung des Moduls, wo die Site bereits Breadcrumbs rendert.

Schema.org enthält weit mehr Typen, als das Modul bereitstellt. Google unterstützt Rich Results für eine kleinere Menge als Schema.org definiert. Wählen Sie einen Typ, weil er die Seite beschreibt und einen Consumer hat - nicht, weil er in einer Liste steht.

Wie konfigurieren Sie Metatag-Defaults vor dem Property-Mapping?

Gehen Sie zu:

Configuration → Search and metadata → Metatag

Der Pfad lautet:

/admin/config/search/metatag

Metatag kombiniert Werte über eine Hierarchie:

1. Global defaults gelten site-weit.
2. Entity defaults gelten für einen Entity-Typ wie Content.
3. Bundle defaults überschreiben sie für einen Content Type wie Product.
4. Entity-level values können Defaults überschreiben, wenn ein Metatag-Feld an einem einzelnen Datensatz hängt.

Die Bundle-Ebene sollte den Großteil der Arbeit leisten. Ein Product-Content-Type braucht ein geprüftes Mapping, das alle Produkt-Nodes erben.

Vermeiden Sie Schema-Bearbeitung auf Entity-Ebene, außer die Seite ist eine echte Ausnahme. Sie verlangt von Redakteuren, technische Metadaten zu pflegen, die sie im normalen Seitendesign nicht sehen. Außerdem verhalten sich zwei Produkte desselben Content Types unterschiedlich.

Global defaults passen zu Identität, die sich pro Seite nicht ändert, etwa der Publisher-Organisation. Bundle defaults passen zu Properties, die an Felder gebunden sind, etwa Produktname, SKU und Beschreibung. Dasselbe Prinzip gilt, wenn Sie Redakteure lehren, in Komponenten statt einem langen Body-Feld zu arbeiten - eine maßgebliche Quelle, viele Ausgaben.

Wie mappen Sie Drupal-Felder auf Product-JSON-LD?

Nehmen Sie an, der Drupal-Content-Type enthält diese Felder:

Das Schema.org-Mapping sollte dieselben Werte lesen:

Token-Pfade für referenzierte Entities und Media hängen von der Feldstruktur und aktivierten Token-Providern ab. Nutzen Sie Browse available tokens im Metatag-Formular und prüfen Sie das Ergebnis auf einer echten Seite. Kopieren Sie kein Media-Token aus einem anderen Projekt und nehmen Sie an, die Relationship-Kette sei identisch.

Das Kern-Mapping-Prinzip ist stabil:

• Namen kommen aus Namensfeldern,
• Identifikatoren aus Identifikatorfeldern,
• Zahlen aus numerischen Feldern,
• kontrollierte Status aus gespeicherten Maschinenwerten,
• URLs müssen zu absoluten öffentlichen URLs auflösen,
• verschachtelte Objekte wie Offer und Brand behalten ihr eigenes @type.

Feldbasiertes JSON-LD unterstützt auch redaktionelle Muster wie Answer-first Writing für AI-Suche, bei denen sichtbarer Text und Metadaten dieselben Fakten beschreiben müssen.

Product-Defaults konfigurieren

Unter /admin/config/search/metatag fügen Sie die Defaults für den Product-Content-Type hinzu oder bearbeiten sie. Öffnen Sie den Abschnitt Schema.org: Product und setzen Sie:

• @type auf Product,
• name auf das Node-Titel-Token,
• description auf das Summary-Token,
• url auf die absolute Node-URL,
• sku auf das SKU-Feld,
• image auf die öffentliche Bild-URL,
• brand als Brand-Objekt,
• offers als Offer-Objekt, befüllt aus den Preisfeldern.

Das Formular des Moduls stellt komplexe Properties als verschachtelte Inputs dar. Nutzen Sie diese Steuerungen, statt einen JSON-String in ein Textfeld zu bauen.

Speichern Sie die Defaults, leeren Sie Caches und öffnen Sie eine veröffentlichte Produktseite. Im Head sollte ein JSON-LD-Skript mit einem Product-Objekt im @graph stehen.

Das Ergebnis sollte dieser Form folgen:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Product",
      "@id": "https://www.example.com/products/aqua-4500#product",
      "name": "Aqua 4500",
      "description": "A submersible pump for continuous industrial use.",
      "url": "https://www.example.com/products/aqua-4500",
      "sku": "AQ-4500",
      "brand": {
        "@type": "Brand",
        "name": "AquaWorks"
      },
      "offers": {
        "@type": "Offer",
        "price": "269.00",
        "priceCurrency": "EUR",
        "availability": "https://schema.org/InStock"
      }
    }
  ]
}

Diese Ausgabe ist ein Beispiel, kein Block zum Einfügen in Drupal. Ihr Mapping sollte sie aus der Product-Entity erzeugen.

Wie exportieren Sie Schema.org-Metatag-Mapping als Drupal-Config?

Sobald die Seitenausgabe stimmt, exportieren Sie die Drupal-Konfiguration:

drush cex -y
git diff -- config/sync

Bundle-Defaults werden als Metatag-Default-Konfigurations-Entities gespeichert. Ein Product-Mapping erscheint normalerweise in einer Datei namens:

metatag.metatag_defaults.node__product.yml

Der einfache Teil einer exportierten Datei hat diese Form:

id: node__product
label: 'Content: Product'
tags:
  schema_product_type: Product
  schema_product_name: '[node:title]'
  schema_product_description: '[node:field_summary]'
  schema_product_id: '[node:url:absolute]#product'
  schema_product_url: '[node:url:absolute]'
  schema_product_sku: '[node:field_sku]'

Komplexe Werte wie Offer serialisiert das Modul und sie sind im rohen YAML schwerer zu prüfen. Konfigurieren Sie sie in der UI, exportieren Sie sie und committen Sie das Ergebnis. Bearbeiten Sie serialisierte Werte nicht von Hand, ohne die gerenderte Seite zu testen.

Config-Export zählt, weil ein Mapping Anwendungsverhalten ist. Es sollte mit Code Review und Deployment zusammen mit dem Content Type und den Feldern laufen, von denen es abhängt.

Was passiert, wenn Preisfelder in JSON-LD leer sind?

Preis-Mappings decken Content-Model-Probleme schnell auf.

Der Preis sollte aus einem Dezimalfeld kommen, nicht aus einem formatierten Satz wie „Ab €269“. Währung braucht einen eigenen kontrollierten Wert. Verfügbarkeit speichert einen Maschinenwert, der auf einen gültigen Schema.org-Status mappt.

Entscheiden Sie, was passiert, wenn kein öffentlicher Preis existiert. Geben Sie nicht aus:

{
  "@type": "Offer",
  "price": "",
  "priceCurrency": "EUR"
}

Ein unvollständiges Offer kann ungültig oder irreführend sein. Entweder machen Sie die Felder für Produkte mit Offer verpflichtend, oder lassen Sie das Offer weg, wenn das Business keinen Preis veröffentlicht.

Hier kann ein einfaches Token-Mapping ein kleines Custom-Modul brauchen. Eine hook_metatags_alter()-Implementierung kann ein verschachteltes Objekt entfernen, wenn seine Pflicht-Quellfelder leer sind. Halten Sie die Regel nah am Content Model und decken Sie sie mit einem Test ab.

Dieselbe Regel gilt für Bewertungen, Datumsangaben und Identifikatoren. Ein leeres Token ist kein nützliches Structured Data. Ein Fallback sollte geschäftliche Bedeutung haben, nicht nur einen Validator zum Schweigen bringen.

Wie halten Sie mehrsprachiges JSON-LD an übersetzten Seiten ausgerichtet?

Tokens lösen sich im Kontext der gerenderten Entity auf. Auf einer übersetzten URL sollten übersetzter Titel und Beschreibung das Markup für diese Sprache speisen.

Prüfen Sie das auf produktionsnahen Seiten. Referenzierte Entities, Media-Metadaten und Custom Tokens folgen Übersetzungen nicht immer so wie die Haupt-Node-Felder.

Klassifizieren Sie Properties, bevor Sie sie konfigurieren:

• Übersetzbar: Name, Beschreibung und publikumsorientierte Labels.
• Meist geteilt: SKU, GTIN und technische Identifikatoren.
• Marktspezifisch: Preis, Währung, Verfügbarkeit und bedientes Gebiet.
• Site-weit: Publisher-Identität und offizielle Profile.

Eine französische Produktseite sollte keine englische Beschreibung ausgeben, weil die französische Übersetzung leer ist. Entscheiden Sie, ob Veröffentlichung blockiert wird, die Property weggelassen wird oder eine dokumentierte Fallback-Sprache auch sichtbar auf der Seite erscheint.

Testen Sie jede Sprach-URL separat. Bestehen in Englisch sagt nichts über den deutschen Preis oder französische Bild-Metadaten aus.

Wie validieren Sie JSON-LD auf gerenderten Drupal-Seiten?

Ein Token in Drupal zu speichern, beweist nicht, dass das resultierende JSON-LD korrekt ist. Validatoren helfen nur, wenn das Markup auf der Live-Seite zu den Feldern passt, die Redakteure pflegen.

Nutzen Sie drei Validierungsebenen.

1. Ausgabe parsen

Öffnen Sie den Seitenquelltext und finden Sie:

<script type="application/ld+json">

Bestätigen Sie, dass der Block gültiges JSON ist, der erwartete Typ existiert und nur ein Modul jede Entity besitzt. Doppelte Product-Objekte aus Schema.org Metatag und einem Theme-Template können widersprechen, ohne Syntaxfehler zu erzeugen.

2. Vokabular prüfen

Nutzen Sie den Schema.org-Validator, um Schema.org-Typen und Properties zu prüfen.

Das fängt fehlerhafte Verschachtelung, Tippfehler in Properties und ungültige Werte ab. Es beweist nicht, dass Google den Typ als Rich Result nutzt. Für CMS-weite SEO-Checks jenseits von Markup siehe 10 SEO-Funktionen, die ein modernes CMS haben sollte und Top-Verbesserungen nach einem Drupal-SEO-Audit.

3. Das beabsichtigte Google-Feature prüfen

Nutzen Sie Googles Rich Results Test für von Google Search unterstützte Typen. Prüfen Sie danach die feature-spezifische Dokumentation für Pflicht-Properties.

Gültiges Schema.org-Markup und Rich-Result-Eignung sind verschiedene Tests. Ein gültiges Service-Objekt kann die Seite gut beschreiben, auch wenn Google kein Service-Rich-Result liefert.

Vergleichen Sie nach den technischen Checks das Ergebnis mit sichtbarem Content. Validatoren entscheiden nicht, ob EUR 269 im Markup mit EUR 249 im Angebotsblock kollidiert. Kann KI Ihre Website tatsächlich lesen? zeigt, warum abrufbares HTML und abgestimmte Fakten über klassische Rich Results hinaus zählen.

Wie testen Sie Schema.org-Abdeckung in CI?

Ein Team kann jeden bestehenden Content Type korrekt konfigurieren und trotzdem sechs Monate später Abdeckung verlieren. Jemand fügt eine neue Product-Variante oder ein Resource-Bundle hinzu und setzt keine Metatag-Defaults.

Der einfachste CI-Check prüft, dass ausgewählte öffentliche Bundles die erwartete Schema-Gruppe in exportierter Konfiguration haben.

<?php

declare(strict_types=1);

namespace Drupal\Tests\site_schema\Unit;

use PHPUnit\Framework\TestCase;
use Symfony\Component\Yaml\Yaml;

final class SchemaDefaultsConfigTest extends TestCase {

  public function testPublicBundlesHaveSchemaDefaults(): void {
    $required = [
      'article' => ['schema_article_type', 'Article'],
      'product' => ['schema_product_type', 'Product'],
      'service' => ['schema_service_type', 'Service'],
    ];

    $configDirectory = dirname(DRUPAL_ROOT) . '/config/sync';

    foreach ($required as $bundle => [$tag, $expectedType]) {
      $path = sprintf(
        '%s/metatag.metatag_defaults.node__%s.yml',
        $configDirectory,
        $bundle,
      );

      self::assertFileExists(
        $path,
        sprintf('The %s bundle has no Metatag defaults.', $bundle),
      );

      $config = Yaml::parseFile($path);

      self::assertSame(
        $expectedType,
        $config['tags'][$tag] ?? null,
        sprintf('The %s bundle has no %s mapping.', $bundle, $tag),
      );
    }
  }

}

Passen Sie Config-Verzeichnis und Bundle-Liste an das Projekt an. Führen Sie den Test im selben PHPUnit-Job aus, der custom Drupal-Code prüft.

Dieser Test fängt Abwesenheit ab. Er fängt kein falsches Preis-Token ab.

Fügen Sie pro wertvollem Template einen Functional Test hinzu. Erstellen oder laden Sie ein repräsentatives Produkt, rufen Sie die öffentliche URL ab, dekodieren Sie das application/ld+json-Skript und prüfen Sie geschäftskritische Werte:

• @type gleich Product,
• name gleich Node-Titel,
• sku gleich field_sku,
• offers.price gleich Roh-Preisfeld,
• offers.priceCurrency gleich gespeicherter Währung,
• sichtbarer Preis gleich generiertem Preis.

Schema.org Metatag nutzt denselben Ansatz in eigenen Functional Tests: gerenderte Seite laden, JSON-LD-Skript finden, dekodieren und Ausgabe vergleichen. Warum Drupal für strukturierte Content-Operations im großen Maßstab funktioniert zeigt, wie Konfiguration, Felder und Governance diese Checks nützlich halten, wenn die Site wächst.

Wie bauen Sie eine redaktionelle Queue für Structured-Data-Review?

Bundle-Defaults sollten normale Seiten abdecken. Menschliche Prüfung sollte fehlende oder außergewöhnliche Quelldaten fokussieren.

Erstellen Sie eine administrative View für Product-Content mit Spalten für:

• Titel,
• Veröffentlichungsstatus,
• SKU,
• Preis,
• Währung,
• Verfügbarkeit,
• Bild,
• Übersetzungsstatus,
• Datum der letzten Änderung,
• Flag „Schema review required“.

Fügen Sie exposed Filter für leere Pflichtfelder und das Review-Flag hinzu. Geben Sie der View einen klaren Namen wie Structured data review queue.

Das Boolean-Flag ist nützlich, wenn ein Datensatz dem Bundle-Mapping nicht folgen kann, etwa ein Produkt mit mehreren unabhängigen Offers oder eine Seite für eine Produktfamilie statt einer SKU. Dieser Datensatz braucht eine Modellierungsentscheidung, kein manuelles JSON-LD-Textfeld.

Wenn Redakteure Metatag-Overrides auf Entity-Ebene setzen können, nehmen Sie diese Datensätze in ein separates Audit auf. Overrides sind Ausnahmen und sollten selten bleiben. Wenn Specs auch KI-gestützte Buyer Research unterstützen müssen, erklärt KI-Empfehlung für Lieferanten: Shortlist-Fakten, warum veröffentlichte Feldwerte über Such-Snippets hinaus zählen.

Wie integrieren Sie JSON-LD-Mapping in den Content-Type-Workflow?

Ein öffentlicher Content Type ändert mehr als das Bearbeitungsformular. Nutzen Sie eine kurze Definition-of-Done-Checkliste:

1. Wählen Sie den primären Schema.org-Typ der Seite.
2. Identifizieren Sie Felder, die seine nützlichen Properties liefern.
3. Konfigurieren Sie Bundle-Defaults mit Tokens.
4. Exportieren und prüfen Sie die Konfiguration.
5. Testen Sie einen vollständigen Datensatz und einen mit fehlenden optionalen Feldern.
6. Testen Sie jede veröffentlichte Sprache.
7. Fügen Sie das Bundle zum Config-Coverage-Test hinzu.
8. Fügen Sie Pflicht-Quellfelder zur redaktionellen Review-View hinzu.
9. Bestätigen Sie, dass Theme oder anderes Modul keine doppelte Entity erzeugt.

Wiederholen Sie die Prüfung, wenn ein Feld Name, Typ oder Ownership ändert. Ein Mapping kann vorhanden bleiben und auf ein Token zeigen, das jetzt nichts mehr auflöst.

Brauchen Sie JSON-LD-Mappings, die mit Ihrem Drupal-Content im Einklang bleiben?

Wir implementieren Schema.org-Metatag-Konfiguration, Feld-zu-Token-Mappings und automatisierte Checks auf Drupal-Plattformen, auf denen Produktseiten, Artikel und mehrsprachiger Content zwischen sichtbarem Text und Structured-Data-Markup abgestimmt bleiben müssen. Dasselbe Muster unterstützt B2B-Sites, die strukturierte Specs für Buyer Research und KI-gestützte Shortlists veröffentlichen.

Wenn Ihre Drupal-Website gepflegtes JSON-LD aus Content-Feldern statt handgeschriebener Blöcke braucht, kann unser Team Bundle-Defaults konfigurieren, sie als Code exportieren und Validierung an Ihren redaktionellen Workflow anbinden. Besuchen Sie unsere Seite Drupal-Agentur, um zu sehen, wie wir Drupal-Plattformen für content-lastige Organisationen bauen und betreuen.