¿Qué es el identificador @id en JSON-LD?

En el bloque JSON-LD de muchas fichas aparece una línea como "@id": "https://www.example.com/camisa-lino-calella#product". Parece un enlace y casi nunca se abre: es un nombre. No es el código del producto ni su SKU, tampoco la propiedad identifier de Schema.org ni la lista de perfiles de sameAs. Es la palabra clave con la que el propio formato distingue un nodo de otro dentro de los datos estructurados de la página. Te importa porque es lo que une la oferta con la tienda que la vende, y lo que decide si el bloque de tu tema y el de una aplicación describen un producto o dos.

Cómo funciona

La especificación JSON-LD 1.1 del W3C define @id como la palabra clave que identifica de forma única los nodos descritos en el documento, con un IRI o con un identificador de nodo anónimo.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Explica también para qué: para poder referirse a un nodo desde fuera es importante que tenga un identificador, y en los datos enlazados lo ideal es que, al abrir ese identificador, se obtenga una descripción del nodo.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}

Un IRI se parece a una URL, pero no es lo mismo. La especificación lo aclara: una URL localiza un recurso en la web y un IRI lo identifica. Es buena práctica que se pueda abrir, aunque no siempre es práctico, y pone como ejemplo un identificador urn:uuid: que no lleva a ninguna parte.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} En una tienda, el IRI suele ser la URL de la página con un fragmento detrás (#product, #organization, #website), que nombra cada cosa sin inventar direcciones nuevas.

Un @id puede escribirse relativo, por ejemplo "../", y entonces se resuelve contra la dirección base del documento. La especificación avisa del coste: si el documento cambia de sitio, el identificador cambia con él.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Por eso en una tienda se escriben completos.

Con un nombre, un nodo ya se puede citar. La especificación llama referencia de nodo a un objeto que solo lleva @id: no describe nada, apunta a un nodo descrito en otra parte del documento.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Es lo que hace "seller": {"@id": "https://www.example.com/#organization"} dentro de una oferta: dice quién vende sin repetir los datos de la empresa.

Sin @id, el nodo es válido, pero anónimo. JSON-LD no obliga a identificar todos los nodos; los que no tienen IRI son nodos en blanco, y si llevan un identificador local (empieza por _:), solo vale dentro de su documento: desde otro documento no se les puede citar.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}

Y lo que más afecta a una ficha: cuando se extrae el JSON-LD de una página HTML como datos enlazados, todos sus bloques <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} Al aplanar ese conjunto, se reúnen en un solo mapa todas las propiedades de cada nodo.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} Dos bloques que describen un nodo con el mismo @id acaban siendo un nodo con las propiedades de los dos; dos bloques sin @id, dos nodos distintos.

Google lo pide en sus directrices generales. Cuando varios elementos de una página van por separado y se entienden mejor juntos, como una receta y su vídeo, hay que usar @id en los dos; si no los enlazas, la Búsqueda puede no saber que van juntos, y en su ejemplo eso le impide mostrar el vídeo como parte del resultado enriquecido de la receta.⁠^{[2]Google Search Central. General structured data guidelines} El ejemplo es de recetas, pero la regla está en las directrices generales, las que se aplican a todos los resultados enriquecidos.⁠^{[2]Google Search Central. General structured data guidelines} El @graph reúne los nodos en un bloque; el @id es lo que los conecta.

En una tienda

Ejemplo ficticio. La ficha de una camisa de Calella, una tienda inventada, con dos bloques: el que trae el tema y el que añade una aplicación. Recortados a lo esencial:

<!-- Bloque del tema -->
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": "Camisa de lino Calella, azul",
    "offers": { "@type": "Offer", "price": "39.90", "priceCurrency": "EUR" }
  }
</script>

<!-- Bloque de la aplicación -->
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Product",
    "@id": "https://www.example.com/camisa-lino-calella#product",
    "name": "Camisa de lino Calella, azul",
    "brand": { "@id": "https://www.example.com/#organization" }
  }
</script>

Leídos juntos, son dos productos: uno anónimo con precio y otro con nombre propio y marca, pero sin precio. Si el tema también escribiera "@id": "https://www.example.com/camisa-lino-calella#product", serían uno solo con las dos cosas.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} El caso no es raro: el bloque de Product que trae Cornerstone, el tema por defecto de BigCommerce, en su versión 6.22.0, no lleva @id.⁠^{[3]BigCommerce en GitHub. Cornerstone, the default Stencil theme (release 6.22.0)} En una ficha publicada con Clione, su nodo Product lleva un @id estable y convive con el del tema en lugar de duplicarlo.

El otro uso diario es el de la entidad que se repite en todo el sitio. La tienda es la misma en la portada, en cada categoría y en cada ficha, así que su nodo Organization debería llamarse igual en todas: https://www.example.com/#organization. Cada oferta la cita como vendedora y el nodo WebSite como editora, sin describirla de nuevo.

Cómo comprobarlo

1. Abre el código fuente de una ficha y busca @id. Apunta el de cada nodo: producto, oferta, organización, sitio. El que no tenga, es anónimo.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
2. Sigue cada referencia. Todo objeto que solo lleve @id tiene que apuntar a un nodo que exista en la página con ese mismo valor, letra por letra.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
3. Cuenta los nodos de producto. Si hay dos, mira si comparten @id. Si no, son dos productos para cualquiera que lea la página.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data}
4. Compara el @id de la organización en tres páginas: la portada, una categoría y una ficha. Debería ser el mismo.
5. Pasa la URL por la Prueba de resultados enriquecidos y compara los elementos que detecta con los nodos que has contado; si dos que deberían ir juntos salen por separado, falta un @id que los una.⁠^{[2]Google Search Central. General structured data guidelines}

Concepto cercano: sameAs

Los dos sirven para identificar, y miran en direcciones opuestas. @id es el nombre que le das tú a un nodo dentro de tu marcado, y lo define el formato JSON-LD.⁠^{[1]W3C. JSON-LD 1.1, A JSON-based Serialization for Linked Data} sameAs es una propiedad de Schema.org que apunta hacia fuera, a páginas de otros sitios que dicen quién es esa entidad: la entrada de sameAs explica cuáles poner. Un nodo de organización bien hecho suele llevar los dos: su @id para que tus propios nodos lo citen, y su sameAs para que el resto del mundo lo reconozca.

Para seguir, la ruta de lectura de datos estructurados ordena el resto de términos, y la entrada de @graph muestra cómo se combinan varios nodos con sus @id en un solo bloque.