# @graph en JSON-LD: qué es y cómo ordena tu schema

> Qué es @graph en JSON-LD, qué dice la especificación del W3C, cómo enlaza el producto, la tienda y la web de una ficha y cómo revisar el de tu tienda.

URL: https://clione.ai/es/glosario/graph/
Lang: es

Si abres el bloque [JSON-LD](/es/glosario/json-ld/) de una [ficha de producto](/es/glosario/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](/es/glosario/migas-de-pan/) y el producto, uno detrás de otro. `@graph` no es un tipo de [Schema.org](/es/glosario/schema-org/) como [Product](/es/glosario/schema-product/) u [Offer](/es/glosario/schema-offer/), ni tiene nada que ver con el [Knowledge Graph](/es/glosario/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](/es/glosario/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.[^w3c-json-ld11]

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.[^w3c-json-ld11] 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ó.[^w3c-json-ld11] 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.[^w3c-json-ld11] Una referencia es un objeto que solo lleva `@id` y apunta a un nodo descrito en otra parte del documento.[^w3c-json-ld11] 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**.[^w3c-json-ld11]

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**.[^w3c-json-ld11] 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](/es/glosario/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**.[^google-sd-policies]

## 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:

```json
{
  "@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](/es/glosario/schema-organization/), [WebSite](/es/glosario/schema-website/), BreadcrumbList y [Product](/es/glosario/schema-product/), más [FAQPage](/es/glosario/faqpage/) cuando tiene preguntas, y su nodo Product tiene un `@id` estable que convive con el del tema en lugar de duplicarlo.


Creer que meter dos nodos en el mismo `@graph` ya dice que están relacionados. No lo dice: la especificación presenta el `@graph` de nivel superior precisamente como la manera de declarar nodos que pueden no estar conectados, y lo que los conecta es una propiedad que apunta al `@id` del otro.[^w3c-json-ld11] Un producto y una organización en el mismo bloque, sin `seller` ni otra referencia, son dos islas.


## 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.[^w3c-json-ld11]
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.[^w3c-json-ld11]
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.[^w3c-json-ld11]
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.[^google-sd-policies]
5. **Pasa la URL por la [Prueba de resultados enriquecidos](/es/glosario/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`](/es/glosario/id-json-ld/) tiene su propia entrada, que explica cómo elegirlo para que no cambie.

Para seguir, la [ruta de lectura de datos estructurados](/es/aprender/datos-estructurados/) ordena el resto de términos, y el [grafo de producto](/es/glosario/grafo-de-producto/) dibuja qué nodos rodean a un producto y cómo se citan entre sí.