JSON-LD

Un bloque aparte, no etiquetas por en medio

JSON-LD significa JavaScript Object Notation for Linked Data: notación JSON para datos enlazados. Es un formato, no un concepto. Los datos estructurados son qué le cuentas a la máquina; JSON-LD es cómo lo tecleas.

Su rasgo definitorio es que va en un bloque independiente, dentro de una etiqueta <script type="application/ld+json"> del HTML, completamente separado del contenido visible. No se mezcla con el diseño ni con las clases de estilo. Se puede leer entero de un vistazo, moverlo, generarlo desde una plantilla o borrarlo, y el aspecto de la página no cambia ni un píxel.

Eso lo distingue de las alternativas anteriores. Microdatos y RDFa hacen el mismo trabajo repartiendo atributos por el HTML, enganchados a las mismas etiquetas que además maquetan la página, aunque cada uno con su vocabulario propio: microdatos marca con itemscope, itemtype e itemprop; RDFa usa vocab, typeof, property y resource. El problema no es teórico: en cuanto alguien rediseña, el marcado se rompe. He visto webs con microdatos donde el rediseño se llevó por delante la mitad del marcado sin que nadie se enterara durante dos años, porque no se ve.

Google recomienda explícitamente JSON-LD en su documentación. Los otros formatos los sigue leyendo, así que si heredas una web con microdatos que funcionan no hay urgencia por migrar. Pero para todo lo nuevo, JSON-LD y punto.

Las tres piezas que lo sostienen

Un bloque de JSON-LD gira alrededor de tres claves con arroba. Entenderlas es la mitad del asunto.

@context dice qué diccionario se está usando. Casi siempre vale https://schema.org. Es lo que hace que name signifique «nombre» y no cualquier otra cosa.

@type dice qué es esto: Person, Organization, Article, BreadcrumbList. Determina qué propiedades tienen sentido a continuación.

@id es el identificador único de esa cosa. Es la clave que casi todo el mundo se salta y la más importante de las tres, porque es la que permite enlazar: si en la página de contacto y en cada artículo del blog te refieres a la misma persona con el mismo @id, todos esos bloques hablan de un mismo individuo. Sin @id, son personas distintas que casualmente se llaman igual.

Así se ve un bloque mínimo de autor, del tipo que llevan las páginas de este sitio:

{
  "@context": "https://schema.org",
  "@type": "Person",
  "@id": "https://yapci.com/#person",
  "name": "Yapci Bello",
  "jobTitle": "Consultor de marketing online",
  "url": "https://yapci.com/sobre-mi/",
  "sameAs": ["https://smedialab.es/equipo/yapci-bello/"]
}

Ocho líneas. A partir de ahí, cualquier otro bloque del sitio que necesite declarar el autor no repite todo esto: apunta al identificador con "author": { "@id": "https://yapci.com/#person" } y ya está. Una persona, una definición, referenciada desde donde haga falta.

Cómo lo monto en un proyecto real

Mi regla es sencilla: el JSON-LD no se escribe a mano en ninguna página. Se genera desde los mismos datos que ya usa el sitio.

En la práctica eso significa un módulo único que construye los bloques a partir del contenido: el título sale del título, la fecha de publicación sale de la fecha del artículo, el autor sale de la ficha de autor. Un único sitio donde está la verdad. Si mañana cambia el teléfono o el nombre comercial, se cambia una vez y se propaga a todas las páginas.

La razón no es elegancia técnica, es que lo he visto fallar de la otra forma demasiadas veces. El marcado copiado y pegado envejece en silencio: nadie lo mira porque no se ve, y a los seis meses la mitad de las páginas declara un horario que ya no existe. Un dato estructurado desactualizado es peor que no tenerlo, porque estás afirmando algo falso de forma explícita y legible por máquina.

El otro hábito que mantengo: emitir todos los bloques de una página agrupados en un único @graph en lugar de sembrar seis scripts sueltos. Es más fácil de depurar, evita duplicados y hace evidentes las referencias cruzadas entre las piezas.

Por qué le importa a un negocio

Porque es la diferencia entre que las máquinas te entiendan bien o te interpreten a ojo. El contenido lo escribes para personas; el JSON-LD es el resumen técnico que acompaña a ese contenido y que leen el buscador y los sistemas que redactan respuestas.

Es también de lo poco en marketing digital que se hace una vez y sigue rindiendo años sin mantenimiento. Bien montado, sale gratis en cada página nueva que publiques. Mal montado, no molesta pero tampoco existe.

Y hay un matiz que conviene decir claro para no vender humo: JSON-LD no sube posiciones. No es un factor de posicionamiento. Lo que hace es permitir resultados enriquecidos en algunos casos y, sobre todo, dejar tu identidad declarada sin ambigüedad. Ese segundo efecto es el que cuenta a medio plazo.

Errores frecuentes

Que no coincida con la página. El marcado tiene que describir lo que hay visible. Declarar valoraciones que no existen, precios que no aparecen o preguntas frecuentes ocultas está expresamente prohibido en las directrices de Google y puede acarrear una acción manual. Suena obvio y sigue siendo el fallo número uno.

Un @id distinto en cada página. Si el autor tiene un identificador nuevo en cada artículo, has creado veinte personas en lugar de una con veinte artículos. Toda la ventaja del formato —enlazar— se pierde justo ahí.

Romperlo con una coma. JSON es implacable: una coma de más al final de una lista, unas comillas tipográficas coladas del procesador de textos o un carácter sin escapar invalidan el bloque entero. No hay error visible ni aviso en Search Console: simplemente deja de contar. Por eso hay que validar después de cada cambio de plantilla, no solo el día que se implementa.

Insertarlo con JavaScript de terceros. Google puede procesar JSON-LD inyectado tras la carga, pero depende de que el renderizado ocurra y de que el script llegue a tiempo. Otros rastreadores directamente no lo verán. Si tu sitio puede emitirlo en el HTML inicial, emítelo ahí: es gratis y no depende de nada.

Marcarlo todo por si acaso. Media docena de tipos bien puestos y coherentes valen más que treinta a medias con propiedades inventadas. El marcado excesivo no suma; solo multiplica las probabilidades de contradecirte a ti mismo.