¿Qué es JSON-LD (JSON for Linking Data)?
JSON-LD es un formato estándar del W3C para escribir datos enlazados en JSON. En una web, JSON-LD es el bloque de código que describe la página con un vocabulario como Schema.org, dentro de una etiqueta script aparte del texto visible, de modo que un buscador lee qué producto, precio o marca hay sin depender de cómo está maquetada la página.
Lo esencial
- JSON-LD es un formato, no un vocabulario: es la sintaxis en la que se escriben las palabras de Schema.org.
- Va en un bloque script propio, separado del HTML visible, y por eso se mantiene sin tocar la maqueta.
- Google admite tres formatos y recomienda este, por ser el más fácil de mantener a escala.
- Que esté separado no significa que pueda decir otra cosa: tiene que describir lo mismo que ve el lector.
- La versión vigente es la 1.1, de 2020; la 1.2 está en marcha y lo escrito en 1.1 seguirá siendo válido.
Si abres el código fuente de una ficha de producto y buscas application/ld+json, lo que encuentras es JSON-LD: un bloque de texto que describe la página para las máquinas, separado de lo que ve el cliente. JSON-LD es el formato, la manera de escribir; las palabras que lleva dentro (producto, precio, marca) son de Schema.org, y juntos forman los datos estructurados de la página. Te importa porque es el formato que recomienda Google, también para las fichas que aspiran a resultados enriquecidos, y porque, al ir aparte, es fácil que diga una cosa mientras la ficha dice otra.
Cómo funciona
JSON-LD es una especificación del W3C. Su versión vigente, JSON-LD 1.1, la define como un formato basado en JSON para serializar datos enlazados (Linked Data), pensado para encajar en sistemas que ya usan JSON, y es recomendación del W3C desde el 16 de julio de 2020. Es un superconjunto de la versión 1.0, de enero de 2014: todo lo que esta permitía sigue ahí.[1]W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data El sitio de la comunidad lo presenta con su nombre largo: JSON for Linking Data.[2]json-ld.org. JSON-LD: JSON for Linking Data
Un documento JSON-LD es JSON normal con unas pocas palabras clave que empiezan por arroba. Las cuatro que verás en una tienda:[1]W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data
@context: las reglas para interpretar el documento. En la práctica,"@context": "https://schema.org"dice que las palabras que siguen son las de Schema.org.@type: el tipo de lo que se describe, por ejemploProduct.@id: un identificador único del nodo, normalmente una dirección web (un IRI). Es lo que permite que otro bloque se refiera a ese mismo producto sin repetirlo; tiene su página propia, el identificador@id.@graph: sirve para expresar un grafo, varios nodos en un mismo bloque. Lo explica la entrada de@graph.
En una página web, el bloque va dentro de un elemento <script type="application/ld+json">.[1]W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data Google acepta ese elemento tanto en el <head> como en el <body>, y de los tres formatos que admite (JSON-LD, microdatos y RDFa) recomienda JSON-LD siempre que el sitio lo permita, porque es el más fácil de implantar y mantener a escala y el que menos errores provoca.[3]Google Search Central. Introduction to structured data markup in Google Search
El bloque puede llegar escrito en el HTML que sirve el servidor o añadirse después con JavaScript. Google puede procesar los datos estructurados que hay en el DOM cuando renderiza la página, pero avisa de que el marcado generado dinámicamente puede hacer que los rastreos de Shopping sean menos frecuentes y menos fiables, un problema para lo que cambia rápido, como el precio y la disponibilidad.[4]Google Search Central. Generate structured data with JavaScript Si tu tema o una aplicación inyectan el bloque con JavaScript, la entrada de renderizado de JavaScript explica qué implica.
El formato sigue vivo. El grupo de trabajo de JSON-LD del W3C tiene un mandato del 6 de enero de 2026 al 31 de enero de 2028 para publicar JSON-LD 1.2, con la recomendación prevista para el cuarto trimestre de 2027, y se compromete a que cualquier documento válido en JSON-LD 1.1 siga siéndolo en 1.2.[5]W3C. JSON-LD Working Group Charter Lo que publiques hoy en 1.1 no habrá que reescribirlo por el cambio de versión.
En una tienda
El bloque de una ficha, reducido a lo esencial. Ejemplo ficticio: la tienda, el producto, la dirección y el precio son inventados, y el bloque solo dice lo que esa ficha imaginaria muestra en pantalla.
<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",
"image": "https://www.example.com/img/calella-azul.jpg",
"sku": "CAL-AZ-M",
"brand": { "@type": "Brand", "name": "Calella" },
"offers": {
"@type": "Offer",
"price": "39.90",
"priceCurrency": "EUR",
"availability": "https://schema.org/InStock",
"url": "https://www.example.com/camisa-lino-calella"
}
}
</script>
Se lee de arriba abajo. @context fija el vocabulario. @type dice que es un producto, el tipo Product. @id le da un nombre estable con el que otros bloques de la página pueden apuntar a él. Las propiedades siguientes son las del vocabulario, y offers abre un segundo nodo anidado, de tipo Offer, con el precio, la moneda y la disponibilidad. Fíjate en el precio, con punto decimal, sin símbolo y con la moneda en su propia propiedad: la entrada de Offer explica por qué se escribe así.
Una ficha real suele llevar más de un nodo: la organización, el sitio web, las migas de pan y el producto. Una ficha publicada con Clione, por ejemplo, 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.
Lo que se suele confundir
Pensar que, como el bloque no se ve, puede decir cualquier cosa. Google pide lo contrario con un ejemplo de JSON-LD: si el marcado describe a un artista, el cuerpo de la página tiene que describir a ese mismo artista. Lo que no ve el lector no se marca.[6]Google Search Central. General structured data guidelines
Cómo comprobarlo
- Abre el código fuente de la ficha (no el inspector del navegador) y busca
application/ld+json. Cuenta cuántos bloques hay y qué@typedeclara cada uno: eso es lo que sirve tu servidor. - Pasa la misma URL por la Prueba de resultados enriquecidos. Admite JSON-LD, microdatos y RDFa, te dice qué tipos encuentra con sus errores y sugerencias, y también acepta un fragmento de código pegado.[7]Ayuda de Search Console. Rich Results Test
- Compara las dos lecturas. Si la prueba encuentra un bloque que el código fuente no tenía, lo está añadiendo JavaScript, y para el precio y la disponibilidad eso tiene el coste que describe Google.[4]Google Search Central. Generate structured data with JavaScript
- Si hay dos nodos de producto, compara sus datos. Si no dicen lo mismo, al menos uno no representa la página.[6]Google Search Central. General structured data guidelines
Concepto cercano: microdatos
Los microdatos son la otra forma habitual de escribir el mismo vocabulario. Forman parte del estándar HTML y añaden grupos de pares nombre-valor en paralelo al contenido que ya existe, con atributos como itemscope, itemtype e itemprop sobre las etiquetas visibles.[8]WHATWG. HTML Standard: Microdata JSON-LD hace lo contrario: describe la página en un bloque aparte. Google admite los dos y recomienda JSON-LD.[3]Google Search Central. Introduction to structured data markup in Google Search La diferencia práctica es dónde vive el dato: en microdatos va pegado al texto que lee el cliente, y en JSON-LD se puede cambiar sin tocar la maqueta, con el riesgo de que deje de coincidir con ella.
Para seguir, la ruta de lectura de datos estructurados ordena el resto de términos, y la guía para auditar los datos estructurados de una ficha aplica estos pasos a una ficha entera.
Sinónimos
- English
- JSON-LD, JSON for Linking Data
- Español
- JSON-LD, marcado JSON-LD
Fuentes
- [1] W3C. JSON-LD 1.1: A JSON-based Serialization for Linked Data. Consultado el . ↑ ↑ ↑
- [2] json-ld.org. JSON-LD: JSON for Linking Data. Consultado el . ↑
- [3] Google Search Central. Introduction to structured data markup in Google Search. Consultado el . ↑ ↑
- [4] Google Search Central. Generate structured data with JavaScript. Consultado el . ↑ ↑
- [5] W3C. JSON-LD Working Group Charter. Consultado el . ↑
- [6] Google Search Central. General structured data guidelines. Consultado el . ↑ ↑
- [7] Ayuda de Search Console. Rich Results Test. Consultado el . ↑
- [8] WHATWG. HTML Standard: Microdata. Consultado el . ↑
Historial de cambios
- Primera versión.
Esta definición se publica bajo licencia CC BY 4.0. Puedes reutilizar esta definición citando a Clione con un enlace a esta página.
Términos relacionados
Schema.org
Qué es Schema.org, quién lo mantiene, cómo se organizan sus tipos y propiedades y por qué no es lo mismo que el formato ni que lo que exige Google.
Datos estructurados
Qué son los datos estructurados, qué piezas los forman, qué consigue una tienda con ellos según Google y cómo comprobar que dicen lo mismo que la ficha.
Product
Qué es el tipo Product de Schema.org, qué propiedades lleva, qué pide Google para fragmentos de producto y fichas de comerciante, y cómo contrastarlo.
Offer
Qué es el tipo Offer de Schema.org, cómo se escriben el precio, la moneda y la disponibilidad, qué pide Google y en qué se diferencia de AggregateOffer.
@graph
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.
Identificador @id
Qué es el identificador @id en JSON-LD, cómo une los nodos de tu schema, por qué conviene que no cambie y cómo evitar dos productos donde hay uno.
Haz que los bots entiendan tu catálogo
Clione completa cada ficha de producto con lo que los bots leen mejor: el grafo JSON-LD con sus datos estructurados, la meta description y las preguntas frecuentes. Tú revisas y pulsas Push; después comprobamos tu tienda en vivo para que todo siga publicado.