¿Qué es @graph en JSON-LD?

Si abres el bloque JSON-LD de una ficha de producto y justo después de @context aparece "@graph": [, lo que sigue no es un nodo sino una lista de ellos: la tienda, la web, las migas de pan y el producto, uno detrás de otro. @graph no es un tipo de Schema.org como Product u Offer, ni tiene nada que ver con el Knowledge Graph de Google: es una palabra clave del propio formato, de la familia de @context, @type e @id. Te importa porque decide cómo están ordenados los datos estructurados de tu página, y porque es fácil creer que ordena más de lo que ordena.

Cómo funciona

La especificación JSON-LD 1.1 del W3C le da dos usos. El que verás en una tienda es el primero: cuando el nivel superior de un documento es un objeto que no lleva más claves que @graph y, si acaso, @context, @graph expresa el grafo por defecto, el que de otro modo quedaría implícito. La especificación explica para qué sirve: cuando hay varios nodos en el nivel superior que comparten el mismo contexto, @graph los reúne en una lista y permite declarar ese contexto una sola vez.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}

La alternativa es una lista de nodos sueltos, cada uno con su propio @context. La especificación pone los dos ejemplos uno al lado del otro y los da por equivalentes: sin @graph, el contexto se repite en cada nodo.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Así que la primera ventaja de @graph es de orden y de peso, no de significado.

El segundo uso es raro en comercio electrónico. Si el mismo objeto que lleva @graph lleva también un @id, ese identificador es el nombre de un grafo con nombre (named graph), y se pueden hacer afirmaciones sobre el grafo en sí, como la fecha en que se generó.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Una ficha de producto no lo necesita.

Lo que une los nodos es otra cosa. La especificación distingue dos maneras de relacionarlos: anidar un nodo dentro de una propiedad de otro, que crea una relación de padre e hijo, o referenciarlo por su identificador.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Una referencia es un objeto que solo lleva @id y apunta a un nodo descrito en otra parte del documento.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Dentro de un @graph los nodos son hermanos, así que se conectan del segundo modo: la oferta del producto dice que la vende {"@id": ".../#organization"}, y ese @id es el del nodo de la tienda que está unas líneas más arriba. Si no lo dice, la especificación es clara: un objeto de nivel superior con @graph sirve para definir nodos que pueden no formar un grafo conectado.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}

Tampoco importa tanto si todo va en un bloque o en varios. Cuando el contenido JSON-LD de una página HTML se extrae como RDF, todos los elementos <script type="application/ld+json"> se procesan y se fusionan en un único conjunto de datos.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Un @graph con cuatro nodos y cuatro bloques con un nodo cada uno dicen lo mismo si los identificadores coinciden.

Google no pide @graph. Sus directrices generales dicen que, cuantos más elementos marcas, más completa es la imagen que tiene de la página y en más funciones de la Búsqueda puede mostrarla, entre ellas los resultados enriquecidos. Y dicen que la Búsqueda entiende varios elementos en una página tanto si los anidas, con un elemento principal y los demás agrupados bajo él, como si los especificas por separado. Y en el segundo caso pide enlazarlos: si dos elementos se entienden mejor juntos, usa @id en los dos; si no los enlazas, Google puede no saber que van juntos.⁠^{[2]Google Search Central. General structured data guidelines}

En una tienda

Ejemplo ficticio. La ficha de una camisa de una tienda inventada, con los cuatro nodos en un solo @graph, recortados a lo esencial:

{
  "@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": "Camisas",
          "item": "https://www.example.com/camisas"
        },
        { "@type": "ListItem", "position": 2, "name": "Camisa de lino Calella, azul" }
      ]
    },
    {
      "@type": "Product",
      "@id": "https://www.example.com/camisa-lino-calella#product",
      "name": "Camisa de lino Calella, azul",
      "offers": {
        "@type": "Offer",
        "price": "39.90",
        "priceCurrency": "EUR",
        "seller": { "@id": "https://www.example.com/#organization" }
      }
    }
  ]
}

Se lee así. El @context va una vez, arriba, y vale para los cuatro nodos. La organización tiene un @id, y dos nodos la citan por él sin describirla otra vez: el sitio web como editor y la oferta como vendedor. La oferta, en cambio, va anidada dentro del producto, porque solo tiene sentido dentro de él. Las dos técnicas conviven en el mismo bloque. Así lo hace también Clione: una ficha publicada con Clione lleva un solo @graph con Organization, WebSite, BreadcrumbList y Product, más FAQPage cuando tiene preguntas, y su nodo Product tiene un @id estable que convive con el del tema en lugar de duplicarlo.

Cómo comprobarlo

1. Abre el código fuente de una ficha y busca application/ld+json. Cuenta los bloques y mira si alguno empieza por @graph. Varios bloques no son un error: la especificación los trata como un solo conjunto de datos.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
2. Apunta el @id de cada nodo. Un nodo sin @id es válido, pero es anónimo: la especificación lo llama nodo en blanco, y desde fuera del documento no se le puede citar.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
3. Sigue cada referencia. Toda propiedad que solo lleve @id, como el vendedor de la oferta, tiene que apuntar a un nodo que exista en la página con ese mismo identificador, letra por letra.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
4. Comprueba que lo que se entiende mejor junto está enlazado, como el producto y la tienda que lo vende. Si no lo está, Google puede no relacionarlos.⁠^{[2]Google Search Central. General structured data guidelines}
5. Pasa la URL por la Prueba de resultados enriquecidos y compara los elementos que detecta con los nodos que has contado.

Concepto cercano: identificador @id

@graph y @id van casi siempre juntos y hacen trabajos distintos. @graph es la lista: dice qué nodos hay. @id es el nombre: dice quién es cada uno y permite que otro lo cite. Un bloque puede tener @graph sin un solo @id, y entonces es una lista de nodos sin relación; y puede tener @id sin @graph, con los nodos anidados unos dentro de otros. El identificador @id tiene su propia entrada, que explica cómo elegirlo para que no cambie.

Para seguir, la ruta de lectura de datos estructurados ordena el resto de términos, y el grafo de producto dibuja qué nodos rodean a un producto y cómo se citan entre sí.