Cómo JSON-LD ayuda a la IA a entender tu sitio web

Jun 3, 2026 · 9 min read

Cómo JSON-LD ayuda a la IA a entender tu sitio web

JSON-LD es un formato basado en <script> para incrustar el vocabulario de Schema.org como metadatos estructurados y legibles por máquinas en tu HTML. Permite que los motores de búsqueda y los sistemas de IA identifiquen entidades —artículos, organizaciones, productos, rutas de navegación, personas— sin necesidad de inferirlas a partir del texto. Para Google Search, un JSON-LD correcto hace que las páginas sean elegibles para funciones específicas de búsqueda y contribuye a poblar el Knowledge Graph. Para los crawlers de IA como GPTBot, ClaudeBot y PerplexityBot, existe una limitación técnica fundamental que los desarrolladores frontend pasan por alto sistemáticamente: estos crawlers no ejecutan JavaScript, por lo que el JSON-LD debe estar presente en la respuesta del servidor para que puedan acceder a él.

Este artículo explica qué hace realmente JSON-LD, en qué casos ayuda y en cuáles no, tres ejemplos funcionales que puedes adaptar, la brecha de renderizado que inutiliza el marcado inyectado desde el cliente para los crawlers de IA, y cómo validar lo que publicas.

Puntos clave

JSON-LD es el formato de datos estructurados recomendado por Google y utiliza el vocabulario de Schema.org para describir entidades y sus relaciones en un formato legible por máquinas.
Los crawlers de IA, incluidos GPTBot, ClaudeBot y PerplexityBot, no ejecutan JavaScript: el JSON-LD inyectado mediante useEffect, Google Tag Manager o cualquier ruta del lado del cliente es invisible para ellos.
Las funciones AI Overviews y AI Mode no requieren un marcado específico para IA; se aplican los mismos criterios de elegibilidad de Google Search estándar, y los datos estructurados favorecen la interpretación del contenido, pero no garantizan su inclusión.
Google dejó de mostrar rich results de FAQ en mayo de 2026, y el soporte en Search Console y en Rich Results Test se eliminará en junio de 2026; FAQPage sigue siendo un tipo válido en Schema.org, pero ya no es una táctica de crecimiento mediante rich results.
Para la validación a largo plazo, validator.schema.org es la opción más segura por defecto: verifica el vocabulario completo de Schema.org, mientras que Google Rich Results Test solo cubre las funciones compatibles con Google.

Qué es JSON-LD y por qué existe

JSON-LD (JavaScript Object Notation for Linked Data) es una sintaxis estandarizada por el W3C para expresar Linked Data en JSON. En la web, se utiliza casi siempre para incrustar el vocabulario de Schema.org dentro de una etiqueta <script type="application/ld+json"> en el documento. Los datos describen las entidades de la página —de qué trata, quién la escribió, qué organización la publicó, cómo se relaciona con otras páginas— en un formato que un parser puede procesar sin necesidad de leer el texto.

La razón de su existencia es el coste interpretativo. Sin datos estructurados, un crawler debe inferir que “Apple” en una página hace referencia a la empresa y no a la fruta; que el nombre “Jane Chen” en el crédito es la autora y no el tema del artículo; que un precio en el marcado pertenece al producto de la página y no a un artículo relacionado en una barra lateral. Schema.org asigna tipos y propiedades explícitas a esos datos. JSON-LD los entrega en un bloque desacoplado del DOM visible, razón por la cual Google lo recomienda frente a Microdata y RDFa: puedes generarlo y actualizarlo sin tocar el layout.

Conviene ser precisos sobre algunas afirmaciones: JSON-LD no es un factor de posicionamiento confirmado en los sistemas de ranking documentados de Google. No garantiza rich results —la elegibilidad es necesaria pero no suficiente—. No garantiza la inclusión en AI Overviews ni en AI Mode. Y los sistemas de IA no requieren JSON-LD; pueden leer texto en prosa. Lo que JSON-LD hace es reducir el trabajo inferencial, lo que aumenta la probabilidad de una interpretación correcta y reduce las posibilidades de que el contenido ambiguo sea clasificado erróneamente.

Cómo encaja JSON-LD en AI Overviews y AI Mode

AI Overviews y AI Mode operan sobre el índice de búsqueda existente de Google. Las directrices publicadas por Google indican que no existe un marcado específico para IA: las páginas se vuelven elegibles para las funciones de IA a través de las mismas señales de contenido y datos estructurados que rigen la búsqueda convencional. Si tu página está correctamente indexada, estructurada y responde a la intención del usuario, los datos estructurados que publiques para Search son los mismos que utilizan esas funciones.

La perspectiva honesta: los datos estructurados ayudan a los sistemas de IA a interpretar tu contenido correctamente. No garantizan la inclusión en las respuestas generadas. Trátalo como una forma de eliminar ambigüedades, no como una palanca de crecimiento.

La brecha de renderizado para crawlers de IA

Este es el punto técnico de mayor impacto para los desarrolladores frontend, y está ausente en la mayoría de los artículos sobre JSON-LD: los crawlers de IA deben tratarse, en términos generales, como crawlers sin capacidad de renderizado, por lo que los datos estructurados deben estar presentes en la respuesta HTML inicial.

GPTBot de OpenAI obtiene el HTML y no renderiza JavaScript del lado del cliente.
ClaudeBot de Anthropic funciona como un crawler HTTP estándar sin ejecución de JS.
PerplexityBot también lee HTML sin procesar.

Googlebot es la excepción: generalmente renderiza JavaScript en un proceso diferido, por lo que el JSON-LD inyectado desde el cliente eventualmente será procesado para Search. Los crawlers de IA no realizan ese proceso adicional. Si tu JSON-LD solo existe tras la hidratación, es invisible para los sistemas sobre los que más preguntas reciben los equipos actualmente.

Un fallo habitual en producción, visible en aplicaciones frontend reales: un desarrollador añade JSON-LD dentro de un hook useEffect, o lo publica a través de Google Tag Manager. El bloque aparece en el DOM renderizado, Rich Results Test (que sí renderiza) lo muestra como válido, y el equipo da el trabajo por terminado. Mientras tanto, todos los crawlers sin capacidad de renderizado reciben una respuesta HTML sin ningún dato estructurado.

La solución es incluir el bloque <script type="application/ld+json"> en la respuesta inicial del servidor.

Renderizado en servidor de JSON-LD por framework

Framework	Dónde colocar JSON-LD
Next.js App Router	`<script type="application/ld+json">` inline en un Server Component, o el campo `other` en la Metadata API
Next.js Pages Router	`<script>` inline dentro de `<Head>` de `next/head`, renderizado en las rutas `getServerSideProps`/`getStaticProps`
Nuxt 3	`useHead` con una entrada `script`, invocado en un contexto de servidor
Astro	`<script type="application/ld+json">` inline directamente en la plantilla `.astro` (estático por defecto, sin ejecución de JS requerida)
SvelteKit	Bloque `<svelte:head>` que contiene el script, renderizado en el servidor

El principio es idéntico en todos los stacks: el bloque JSON-LD debe existir en los bytes que devuelve el servidor, no en bytes añadidos por el navegador tras el primer renderizado.

Tres ejemplos funcionales de JSON-LD

Los ejemplos siguientes utilizan el vocabulario de Schema.org según la versión 30.0, publicada el 19 de marzo de 2026.

BlogPosting (un subtipo de Article)

En la jerarquía de Schema.org, BlogPosting es un subtipo de Article, que a su vez es un subtipo de CreativeWork. Declarar "@type": "BlogPosting" hereda implícitamente todas las propiedades de Article; no es necesario declarar ambos tipos.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "@id": "https://openreplay.com/blog/json-ld-ai-search#article",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://openreplay.com/blog/json-ld-ai-search"
  },
  "headline": "How JSON-LD Helps AI Understand Your Website",
  "description": "A frontend-focused guide to JSON-LD, Schema.org, and the server-rendering requirement for AI crawlers.",
  "image": "https://openreplay.com/images/blog/json-ld-ai-search.png",
  "datePublished": "2026-05-20T09:00:00-04:00",
  "dateModified": "2026-05-20T09:00:00-04:00",
  "author": {
    "@type": "Organization",
    "name": "OpenReplay Team",
    "url": "https://openreplay.com"
  },
  "publisher": {
    "@id": "https://openreplay.com/#organization"
  }
}
</script>

Utiliza este bloque en páginas de artículos de formato largo. mainEntityOfPage vincula el artículo con su URL canónica; dateModified es relevante porque Google lo utiliza cuando la frescura del contenido es una señal para la consulta.

Organization

El tipo Organization describe la entidad que publica el contenido. Usa sameAs para apuntar a perfiles externos canónicos: así es como los sistemas distinguen tu marca de otras con nombres similares.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://openreplay.com/#organization",
  "name": "OpenReplay",
  "url": "https://openreplay.com",
  "logo": {
    "@type": "ImageObject",
    "url": "https://openreplay.com/images/logo.png",
    "width": 512,
    "height": 512
  },
  "sameAs": [
    "https://github.com/openreplay",
    "https://www.linkedin.com/company/openreplay",
    "https://x.com/OpenReplayHQ"
  ]
}
</script>

Publica este bloque una sola vez, a nivel de todo el sitio —típicamente en el head del documento de cada página—. Reutiliza el @id desde otros bloques de schema (como hace BlogPosting.publisher en el ejemplo anterior) para que una única definición canónica de Organization sea referenciada en todas partes en lugar de duplicarse.

BreadcrumbList

BreadcrumbList describe la posición de la página dentro de la jerarquía del sitio. Google admite rich results de breadcrumb, y los mismos datos ayudan a los sistemas de IA a comprender la estructura del sitio.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://openreplay.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog",
      "item": "https://openreplay.com/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "How JSON-LD Helps AI Understand Your Website"
    }
  ]
}
</script>

El último elemento omite item porque corresponde a la página actual. position comienza en 1.

Mantén los datos estructurados alineados con el contenido visible

Las directrices de datos estructurados de Google son explícitas: el contenido en JSON-LD debe coincidir con lo que aparece en la página. Marcar reseñas que no existen en la página, precios que no se muestran, o nombres de autores que contradicen los créditos visibles supone un riesgo de acción manual. Los datos estructurados deben describir la página, no enriquecerla con afirmaciones que no están respaldadas en el DOM.

Esto también es relevante para los sistemas de IA. Si tu texto visible dice una cosa y tu JSON-LD dice otra, habrás creado exactamente la ambigüedad que los datos estructurados pretenden resolver.

Valida antes de publicar

Dos herramientas cubren el flujo de trabajo:

Herramienta	Qué verifica	Mejor para
Google Rich Results Test	Elegibilidad para los tipos de rich results compatibles con Google	Verificación previa al despliegue para Article, Product, Breadcrumb, etc.
Schema Markup Validator	Conformidad con el vocabulario completo de Schema.org	Validación general; cualquier tipo que Google no muestre como rich result

Rich Results Test renderiza la página (por lo que detecta el JSON-LD inyectado desde el cliente que los crawlers de IA no verán). Para confirmar lo que ven los crawlers sin capacidad de renderizado, ejecuta curl -A "GPTBot" https://tu-pagina contra tu URL y busca application/ld+json en la respuesta. Si el bloque no está en ese HTML sin procesar, los crawlers de IA no lo verán.

La sección Mejoras de Google Search Console reporta errores de análisis y la elegibilidad para los tipos de datos estructurados que Google monitoriza. Úsala para el seguimiento continuo, no como sustituto de la validación previa al despliegue.

Una nota sobre FAQPage

FAQPage sigue siendo un tipo válido en Schema.org y Google continúa utilizándolo para la comprensión del contenido. Sin embargo, Google indica en su documentación de FAQPage que las funciones de búsqueda relacionadas con FAQ están siendo eliminadas: los rich results de FAQ dejaron de aparecer en Search en mayo de 2026; los informes en Search Console y el soporte en Rich Results Test se eliminarán en junio de 2026; y el soporte en la API de Search Console seguirá en agosto de 2026. Si estás eligiendo qué schema implementar ahora para obtener visibilidad mediante rich results, FAQPage no es la respuesta. Impleméntalo si tienes una página de preguntas frecuentes genuina y quieres registrar la semántica —no como una estrategia para ganar espacio en los resultados de búsqueda.

Esta es también la razón por la que validator.schema.org es la opción más segura por defecto para el trabajo de validación a largo plazo: no depende de qué funciones decida Google mostrar como rich results.

Qué publicar primero

Si partes de cero, la secuencia de mayor valor es: un único bloque Organization a nivel de todo el sitio, BreadcrumbList en cada página que no sea la página de inicio, y Article/BlogPosting en el contenido editorial. Renderiza todo en el servidor. Valida con ambas herramientas. Luego verifica la respuesta HTML sin procesar con un agente de usuario sin capacidad de renderizado para confirmar que los crawlers de IA reciben realmente lo que escribiste.

Los datos estructurados no mejorarán el posicionamiento por sí solos ni garantizarán la inclusión en AI Overviews. Lo que sí hacen —de forma fiable, cuando se publican correctamente— es eliminar las suposiciones interpretativas que llevan a los motores de búsqueda y a los sistemas de IA a malinterpretar tu contenido. Para los equipos frontend, el trabajo que más importa no es qué tipos de schema añadir, sino en qué punto del pipeline de renderizado se encuentran. Incluye el JSON-LD en la respuesta del servidor, y el resto es cuestión de contenido.

Preguntas frecuentes

Usa JSON-LD. Google lo recomienda explícitamente frente a Microdata y RDFa porque reside en un único bloque de script desacoplado del DOM visible, lo que significa que puedes generar y actualizar datos estructurados sin tocar el marcado del layout. Los tres formatos pueden expresar el vocabulario de Schema.org y son procesados por Google, pero JSON-LD es más fácil de mantener, más fácil de renderizar en el servidor, y es el formato que Google utiliza en todos sus ejemplos de documentación de datos estructurados.

Sí. Google admite múltiples etiquetas script separadas en una sola página, que es el patrón estándar para combinar tipos como Organization, BreadcrumbList y BlogPosting. La alternativa es un único script que contenga un array de grafo bajo la clave @graph, donde cada entidad tiene su propio @id. Ambos enfoques son válidos; el patrón @graph es más limpio cuando las entidades se referencian entre sí mediante @id, ya que mantiene una única definición canónica por entidad en lugar de duplicarla.

Solo si el JSON-LD está en la respuesta inicial del servidor. Las SPAs que inyectan datos estructurados después de la hidratación son invisibles para los crawlers sin capacidad de renderizado como GPTBot, ClaudeBot y PerplexityBot. La solución es el renderizado en servidor o la generación estática para las páginas que necesitan datos estructurados —usando Next.js, Nuxt, Astro o SvelteKit en sus modos SSR o SSG— de modo que la etiqueta script exista en los bytes HTML antes de que se ejecute cualquier JavaScript.

Actualiza dateModified únicamente cuando el contenido sustancial del artículo cambie: correcciones, nuevas secciones, datos actualizados, ejemplos renovados. No lo modifiques en cada despliegue ni por ediciones cosméticas como correcciones tipográficas o ajustes de estilo. Google utiliza dateModified como señal de frescura para consultas sensibles al tiempo, y actualizarlo sin cambios reales en el contenido contradice la regla de que los datos estructurados deben coincidir con el contenido visible, lo que supone un riesgo de acción manual.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.