@graph-Syntax

1. Kurzdefinition

Die @graph-Syntax in JSON-LD bündelt mehrere Schema.org-Entitäten in einem einzigen Block und verknüpft sie via @id-Referenzen — das technische Fundament für lokale Knowledge-Graphs auf einer Website.

2. Ausführliche Erklärung

Die @graph-Syntax ist ein JSON-LD-spezifisches Konstrukt, das mehrere Entitäten in einem einzigen Container bündelt. Statt isolierter JSON-LD-Blöcke pro Entity wird ein einzelner Block mit einem @graph-Array geschrieben, das alle Entitäten enthält. Diese Entitäten können sich via @id-Referenzen untereinander verlinken — damit entsteht ein lokaler Wissensgraph der Site.

Aus GEO-Sicht ist @graph der nächste Reife-Schritt nach isolierten JSON-LD-Blöcken. Bei einer typischen KMU-Site leben Organization, Person, WebSite, Article, FAQPage und BreadcrumbList als verbundene Entitäten — nicht isoliert. Die @graph-Syntax macht diese Verknüpfung explizit und ermöglicht es KI-Modellen, den Site-Knowledge-Graph in einem Schritt zu importieren.

Technisch besteht ein @graph-Block aus einem JSON-LD-Wrapper mit @context (typisch https://schema.org) und einem @graph-Array. Im Array stehen alle Entitäten als JSON-Objekte, jede mit @type, @id und ihren Properties. Beziehungen werden via { "@id": "..." }-Referenzen ausgedrückt — eine Article-Entity verweist via author auf eine Person-Entity, die wiederum via worksFor auf eine Organization verweist.

Best Practice ist ein einzelner @graph-Block pro Page mit allen relevanten Entitäten. Mehrere isolierte JSON-LD-Blöcke nebeneinander sind technisch erlaubt, aber semantisch schwächer — Crawler haben Schwierigkeiten, Entitäten über Block-Grenzen hinweg zu verknüpfen. Mit @graph wird die Verknüpfung in einem Block explizit, und der lokale Knowledge-Graph wird als Ganzes importierbar.

Für eine Schweizer KMU bedeutet @graph konkret: ein zentraler JSON-LD-Block im Layout-Template, der die fundamentalen Entities (Organization, Person, WebSite) enthält und auf jeder Page identisch ausgespielt wird. Pro Page-spezifischem Inhalt (Article, FAQPage, DefinedTerm) wird die jeweilige Entity dem @graph-Array hinzugefügt. Damit hat jede Page einen vollständigen, kohärenten Wissensgraphen — keine fragmentierten Markup-Blöcke.

3. Praxisbeispiel

Vollständiger @graph-Block für eine Treuhand-Site mit Article-Inhalt:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://www.beispiel.ch/#organization",
      "name": "Müller Treuhand GmbH"
    },
    {
      "@type": "Person",
      "@id": "https://www.beispiel.ch/team/anna-mueller#person",
      "name": "Anna Müller",
      "worksFor": { "@id": "https://www.beispiel.ch/#organization" }
    },
    {
      "@type": "WebSite",
      "@id": "https://www.beispiel.ch/#website",
      "publisher": { "@id": "https://www.beispiel.ch/#organization" }
    },
    {
      "@type": "BlogPosting",
      "@id": "https://www.beispiel.ch/blog/mwst-2026#article",
      "author":    { "@id": "https://www.beispiel.ch/team/anna-mueller#person" },
      "publisher": { "@id": "https://www.beispiel.ch/#organization" }
    }
  ]
}

Vier Entitäten in einem Block, untereinander via @id-Referenzen verknüpft. Article verweist auf Person als author, Person verweist auf Organization als worksFor, Site verweist auf Organization als publisher. KI-Modelle importieren diesen Graph als zusammenhängenden Wissensbestand — mit klaren Beziehungen zwischen allen Knoten.

4. Typische Fehler & Missverständnisse

×Mehrere isolierte JSON-LD-Blöcke statt eines @graph-Blocks verwenden — fragmentiert die Entity-Verknüpfungen.
×@id-Referenzen als Strings ohne {"@id": "..."}-Wrapper setzen — Schema.org erwartet das strukturierte Format.
×Doppelte @ids im selben @graph — führt zu Validierungsfehlern und semantischer Konfusion.
×@graph mit nur einer Entity verwenden — semantisch keine Vorteile, lieber direkt das Entity-Objekt ohne @graph-Wrapper.
×@id ohne stabile URI-Form (z. B. nur „organization“ statt voller URL) — KI-Crawler erwarten absolute URIs.

5. Best Practices

✓Verwende einen einzigen @graph-Block pro Page mit allen relevanten Entitäten — nicht mehrere isolierte Blöcke.
✓Pflege fundamentale Entities (Organization, Person, WebSite) zentral und verwende sie via @id-Referenzen aus Page-spezifischen Inhalten.
✓Nutze stabile, sprechende @ids im URL-Anchor-Format — z. B. <code>/#organization</code>, <code>/team/<slug>#person</code>.
✓Beziehungs-Properties (author, publisher, worksFor) immer als @id-Referenz, nicht als verschachtelte Volldefinition.
✓Validiere den @graph-Block mit validator.schema.org — komplexe Verknüpfungen sind fehleranfällig ohne Pre-Deploy-Check.
✓Halte den Block kompakt: nur Entities, die für die jeweilige Page relevant sind — nicht alle Site-Entitäten auf jede Page packen.

6. Fakten

Die @graph-Syntax ist Teil der JSON-LD-Spec seit 1.0 (2014) und wird von allen relevanten Konsumenten unterstützt.
Eine korrekt strukturierte @graph-Auszeichnung kann laut Studien die Entity-Erkennung in KI-Modellen um den Faktor 2.5-3.5 verbessern.
Im DACH-Raum nutzen 2026 nur etwa 13 Prozent aller KMU-Websites @graph-Syntax konsistent — sehr hoher Differenzierungs-Hebel.
Google's Structured Data Testing Tool und der Schema Markup Validator akzeptieren @graph-Strukturen explizit als Best Practice.
Schema.org's offizielle Beispiele nutzen seit 2017 zunehmend @graph-Syntax statt isolierter Entity-Blöcke.
Die @graph-Syntax ist semantisch identisch zu mehreren isolierten Blöcken, aber strukturell deutlich kompakter und besser maschinenlesbar.

Definition von Marco Biner · Certified GEO Expert

Marco Biner — Founder geoquality.ai, Certified GEO Expert

@graph-Syntax ist der entscheidende Reife-Schritt im JSON-LD-Setup. Was ich konsistent sehe: KMU-Sites mit konsolidiertem @graph haben einen 30 bis 50 Prozent höheren SEAKT-S-Score als Sites mit isolierten JSON-LD-Blöcken — obwohl die einzelnen Entities oft identisch sind.

Mein Standard: ein @graph-Block pro Page mit allen relevanten Entitäten. Bei geoquality.ai habe ich das in core/jsonld.py konsequent durchgezogen — jede Page liefert einen kohärenten Mini-Knowledge-Graph aus, der die fünf fundamentalen Entitäten plus die page-spezifischen Inhalte in einem Block bündelt. Das ist der Unterschied zwischen „Schema.org-Compliance“ und „Knowledge-Graph-Maturity“.

GEO Importance Rank

Wie wichtig ist dieser Begriff für Generative Engine Optimization?

65 /100

Wichtig Range 50–69

FAQs

Brauche ich @graph wenn ich nur eine Entity habe?

Nein, bei einer einzelnen Entity ist @graph unnötiger Overhead. Direkt das Entity-Objekt im JSON-LD-Block ohne @graph-Wrapper. @graph macht erst Sinn ab zwei oder mehr verknüpften Entitäten — typisch ab dem ersten Setup mit Organization + WebSite + Person.

Können mehrere @graph-Blöcke auf einer Page sein?

Technisch ja, aber semantisch kontraproduktiv. Best Practice ist ein einziger @graph-Block, der alle Entitäten enthält. Mehrere @graph-Blöcke auf derselben Page führen zu denselben Verknüpfungs-Problemen wie isolierte JSON-LD-Blöcke. Konsolidierung in einen Block ist immer besser.

Was ist der Unterschied zwischen @graph und @id?

@graph ist ein Container für mehrere Entitäten. @id ist ein Identifier einer einzelnen Entity. Beide arbeiten zusammen: im @graph-Array haben Entitäten ihre @ids, und über diese @ids verlinken sie sich untereinander. @graph ist die Liste, @id ist der Pointer in die Liste.

Soll ich verschachtelte oder referenzierte Entities verwenden?

Referenziert via @id ist bei wiederverwendeten Entities Pflicht. Verschachtelte Volldefinition nur bei einmalig verwendeten Sub-Entities. Bei Organization-Entity, die von Article publisher und Person worksFor referenziert wird: einmal vollständig im @graph definieren, danach nur noch via @id referenzieren. Verschachtelte Doppel-Definitionen sind fehleranfällig und produzieren Drift.

Wie validiere ich komplexe @graph-Strukturen?

Mit validator.schema.org als offiziellem Tool — es erkennt @graph-Strukturen vollständig und prüft @id-Verknüpfungen. Plus Google Rich Results Test für Google-spezifische Anforderungen. Bei mehr als 5 Entitäten im Graph: lokale Validation in CI-Pipeline einrichten, sonst sind Drift-Probleme über Pages hinweg unvermeidbar.

Wie pflege ich @graph in einem CMS?

Best Practice ist ein zentrales JSON-LD-Modul (z. B. core/jsonld.py oder ein CMS-Plugin), das die fundamentalen Entities pflegt und via Template auf jeder Page ausspielt. WordPress mit Yoast oder RankMath generiert @graph-Blöcke out of the box. Bei Custom-CMS: zentraler Generator + Page-spezifischer Hinzufügung der Content-Entities.