Graph

The primary function of @graph is to house an array of multiple top-level entities—such as an Organization, a WebSite, and a Person—within a single <script> block. Without @graph, each entity would require its own separate JSON-LD block, leading to code duplication and fragmented data. This consolidation allows a single document to fully describe a complex entity ecosystem, such as a corporation with multiple brands and their respective CEOs, all linked through shared identifiers.

@graph facilitates explicit linking between nodes using the @id keyword. By assigning a unique Internationalized Resource Identifier (IRI) to each node, other nodes can reference it directly via properties like founder, publisher, or subjectOf. This transforms a flat list of entities into a connected, machine-readable knowledge graph. For example, a NewsArticle node can explicitly point to its author, which is a Person node defined in the same @graph array, using the author's @id.

The @graph construct works in tandem with the @context keyword to define shared vocabularies. A single @context at the top of the block applies to all nodes within the @graph array, ensuring consistent term mapping and reducing verbosity. This scoping allows for the reuse of common properties and type definitions across multiple entities without re-declaring them, making the structured data block more compact and efficient for parsers to process.

Beyond a simple array, @graph can be combined with an @id at the top level to create a named graph. This practice assigns a unique IRI to the entire set of statements, effectively making a statement about the graph itself. This is crucial for provenance tracking, allowing a publisher to assert metadata—such as dateCreated, creator, or license—about the entire structured data payload, not just the individual entities within it.

When multiple entities are present, search engines need to identify the primary subject of the page. The @graph construct is often used with the mainEntity property on a parent WebPage node. By placing the WebPage node inside the @graph and using its mainEntity property to point to the @id of the primary Article or Product node, the data block explicitly disambiguates the page's central topic from secondary entities like the site's Organization or navigation elements.

A canonical use case for @graph is implementing the Sitelinks Search Box rich result. This requires defining a WebSite node with a potentialAction of type SearchAction and a urlTemplate. By placing this WebSite node inside an @graph alongside the Organization node that owns it, a single JSON-LD block can simultaneously establish the brand entity and enable the powerful site-search feature directly in search engine results pages.