JSON-LD: qué es y cómo funciona

JSON-LD —JavaScript Object Notation for Linked Data— es una forma de escribir datos estructurados como JSON plano. Es una Recomendación del W3C y el formato que Google recomienda para el marcado Schema, porque vive en su propio bloque en lugar de estar entretejido con tu HTML.

Dónde se coloca

JSON-LD va dentro de un elemento script con un tipo especial. Los navegadores no lo ejecutan; lo leen los rastreadores. Puede ir en el <head> o en cualquier parte del <body>.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "Green Sill",
      "url": "https://example.com/",
      "sameAs": ["https://www.linkedin.com/company/green-sill"]
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "name": "Green Sill",
      "publisher": { "@id": "https://example.com/#org" }
    }
  ]
}
</script>

Las palabras clave que importan

• @context declara el vocabulario; para SEO, https://schema.org.
• @type nombra el tipo de cosa: Organization, Product, Event, etc.
• @id da a un nodo un identificador estable, normalmente una URL más un fragmento, para que otros nodos puedan referenciarlo en lugar de repetirlo.
• @graph agrupa varios nodos conectados en un solo bloque, como arriba, donde el WebSite apunta a su publisher mediante el ID.

Por qué importa

JSON-LD hace que una página sea apta para resultados enriquecidos y ofrece a los buscadores y a los sistemas de IA un resumen inequívoco de las entidades y los hechos que contiene. Al estar separado del diseño, un cambio de plantilla no lo rompe, y es sencillo de generar desde un CMS o una base de datos de productos. La introducción a los datos estructurados de Google enumera los formatos admitidos y las políticas que se aplican.

Errores frecuentes

• JSON no válido. Una coma sobrante, unas comillas que faltan o comillas tipográficas pegadas desde un procesador de textos invalidan todo el bloque, y cada elemento que contiene.
• Caracteres sin escapar. Unas comillas dobles dentro del nombre de un producto necesitan una barra invertida, y una etiqueta de cierre de script literal dentro de un valor de texto termina el bloque antes de tiempo.
• Entidades duplicadas en varios bloques con valores distintos, a menudo por varios plugins.
• Inyección solo con JavaScript. Google puede leer el JSON-LD añadido por scripts después del renderizado, pero los rastreadores que no ejecutan JavaScript, incluidos muchos bots de IA, nunca lo ven. Genéralo en el HTML del servidor.
• HTML dentro de los valores, como etiquetas de párrafo en un campo de descripción.

Valídalo

Pasa la página por el validador de Schema: extrae cada bloque JSON-LD junto con cualquier Microdata o RDFa, informa de los errores de sintaxis JSON y comprueba las propiedades obligatorias y recomendadas por Google para los tipos habituales. Para los conceptos que hay detrás, consulta datos estructurados.

Preguntas frecuentes