What is @graph in JSON-LD?

If you open the JSON-LD block of a product page and right after @context you see "@graph": [, what follows is not a node but a list of them: the store, the site, the breadcrumbs and the product, one after another. @graph is not a Schema.org type like Product or Offer, and it has nothing to do with Google's Knowledge Graph: it is a keyword of the format itself, in the family of @context, @type and @id. It matters because it decides how your page's structured data is arranged, and because it is easy to believe it arranges more than it does.

How it works

The W3C's JSON-LD 1.1 specification gives it two uses. The one you will see in a store is the first: when a document's top level is an object that carries no keys other than @graph and, at most, @context, @graph expresses the default graph, the one that would otherwise stay implicit. The specification explains what it is for: when there are several nodes at the top level that share the same context, @graph gathers them in a list and lets you declare that context only once.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}

The alternative is a list of loose nodes, each with its own @context. The specification puts the two examples side by side and treats them as equivalent: without @graph, the context is repeated on every node.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} So the first advantage of @graph is one of order and weight, not of meaning.

The second use is rare in ecommerce. If the same object that carries @graph also carries an @id, that identifier is the name of a named graph, and you can make statements about the graph itself, such as the date it was generated.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} A product page does not need it.

What joins the nodes is something else. The specification distinguishes two ways of relating them: embedding a node inside a property of another, which creates a parent-child relationship, or referencing it by its identifier.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} A reference is an object that carries only @id and points to a node described elsewhere in the document.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Inside a @graph the nodes are siblings, so they connect the second way: the product's offer says it is sold by {"@id": ".../#organization"}, and that @id is the one on the store's node a few lines above. If it does not say so, the specification is clear: a top-level object with @graph is used to define nodes that may not form a connected graph.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}

Nor does it matter much whether everything goes in one block or several. When the JSON-LD content of an HTML page is extracted as RDF, all the <script type="application/ld+json"> elements are processed and merged into a single dataset.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} A @graph with four nodes and four blocks with one node each say the same thing if the identifiers match.

Google does not ask for @graph. Its general guidelines say that the more elements you mark up, the more complete a picture it has of the page and the more Search features it can show it in, including rich results. And they say Search understands multiple elements on a page whether you nest them, with a main element and the others grouped under it, or specify them separately. In the second case it asks you to link them: if two elements are better understood together, use @id on both; if you do not link them, Google may not know they go together.⁠^{[2]Google Search Central. General structured data guidelines}

In a store

Fictional example. A shirt's product page in an invented store, with the four nodes in a single @graph, cut down to the essentials:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://www.example.com/#organization",
      "name": "Calella",
      "url": "https://www.example.com/"
    },
    {
      "@type": "WebSite",
      "@id": "https://www.example.com/#website",
      "url": "https://www.example.com/",
      "publisher": { "@id": "https://www.example.com/#organization" }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Shirts",
          "item": "https://www.example.com/shirts"
        },
        { "@type": "ListItem", "position": 2, "name": "Calella linen shirt, blue" }
      ]
    },
    {
      "@type": "Product",
      "@id": "https://www.example.com/calella-linen-shirt#product",
      "name": "Calella linen shirt, blue",
      "offers": {
        "@type": "Offer",
        "price": "39.90",
        "priceCurrency": "USD",
        "seller": { "@id": "https://www.example.com/#organization" }
      }
    }
  ]
}

It reads like this. The @context goes once, at the top, and applies to all four nodes. The organization has an @id, and two nodes cite it by it without describing it again: the website as publisher and the offer as seller. The offer, by contrast, is nested inside the product, because it only makes sense inside it. The two techniques coexist in the same block. Clione does the same: a page published with Clione carries a single @graph with Organization, WebSite, BreadcrumbList and Product, plus FAQPage when it has questions, and its Product node has a stable @id that coexists with the theme's own instead of duplicating it.

How to check it

1. Open a product page's source code and search for application/ld+json. Count the blocks and see whether any starts with @graph. Several blocks are not an error: the specification treats them as a single dataset.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
2. Note each node's @id. A node without @id is valid, but it is anonymous: the specification calls it a blank node, and from outside the document it cannot be cited.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
3. Follow every reference. Every property that carries only @id, like the offer's seller, has to point to a node that exists on the page with that same identifier, letter for letter.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
4. Check that what is better understood together is linked, like the product and the store that sells it. If it is not, Google may not relate them.⁠^{[2]Google Search Central. General structured data guidelines}
5. Run the URL through the Rich Results Test and compare the elements it detects with the nodes you counted.

Related concept: the @id identifier

@graph and @id almost always go together and do different jobs. @graph is the list: it says which nodes exist. @id is the name: it says who each one is and lets another cite it. A block can have @graph without a single @id, and then it is a list of unrelated nodes; and it can have @id without @graph, with the nodes nested inside one another. The @id identifier has its own entry, which explains how to choose it so it does not change.

To go further, the structured data reading path orders the rest of the terms, and the product graph draws which nodes surround a product and how they cite each other.