--- title: @graph-Syntax slug: graph-syntax canonical_url: https://www.geoquality.ai/glossar/graph-syntax md_url: https://www.geoquality.ai/glossar/graph-syntax.md language: de last_modified: 2026-05-03T00:00:00+00:00 related_terms: [at-id-property, entity, json-ld, knowledge-graph, schema-org, structured-data] content_hash: bd847fc08bcf7963 license: CC BY 4.0 author: Marco Biner (geoquality.ai) schema_type: DefinedTerm --- # @graph-Syntax 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. ## Erläuterung 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. ## 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. ## Häufige Fehler - 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. ## 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. /#organization, /team/<slug>#person. - 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. ## 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. ## FAQ ### 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. ## Experten-Definition @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“. ## Verwandte Begriffe - [@id (Schema.org)](https://www.geoquality.ai/glossar/at-id-property.md) — Die @id-Property in JSON-LD ist der stabile, eindeutige Identifier einer Schema.org-Entity in URI-Form — die unsichtbare Klebematerie, die Entitäten innerhalb und zwischen Sites zu einem kohärenten Wissensgraphen verknüpft. - [Entity](https://www.geoquality.ai/glossar/entity.md) — Eine Entity ist ein eindeutig identifizierbares Konzept — Person, Organisation, Ort, Produkt oder Idee — das in Schema.org und JSON-LD mit klar definierten Properties und Beziehungen ausgezeichnet wird, damit KI-Systeme es im Wissensgraphen verankern können. - [JSON-LD](https://www.geoquality.ai/glossar/json-ld.md) — JSON-LD ist ein W3C-standardisiertes Format zur Einbettung strukturierter Daten in Webseiten — typischerweise nach Schema.org-Vokabular — und der von Google sowie allen grossen KI-Crawlern bevorzugte Weg, Entitäten und Beziehungen maschinenlesbar zu beschreiben. - [Knowledge Graph](https://www.geoquality.ai/glossar/knowledge-graph.md) — Ein Knowledge Graph ist eine Datenstruktur, die Entitäten und ihre Beziehungen als verknüpftes Netzwerk repräsentiert und KI-Systemen die Faktenbasis liefert, aus der sie Antworten zusammensetzen. - [Schema.org](https://www.geoquality.ai/glossar/schema-org.md) — Schema.org ist das von Google, Microsoft, Yahoo und Yandex gemeinsam entwickelte Vokabular zur strukturierten Beschreibung von Web-Inhalten — der De-facto-Standard für maschinenlesbare Auszeichnung und das technische Fundament jeder GEO-Strategie. - [Strukturierte Daten](https://www.geoquality.ai/glossar/structured-data.md) — Strukturierte Daten sind maschinenlesbare Auszeichnungen von Web-Inhalten — typischerweise als JSON-LD im HTML-Head — die Entitäten, Beziehungen und Metadaten explizit benennen statt sie nur implizit im Fliesstext zu hinterlassen. ## Quelle und Zitation - HTML-Original: https://www.geoquality.ai/glossar/graph-syntax - Lizenz: CC BY 4.0 - Zitiervorschlag: "@graph-Syntax (geoquality.ai Glossar, Biner 2026)"