Renderice JSON-LD desde un Server Component como un script de tipo application/ld+json, y reemplace cada < de la cadena serializada por \u003c antes de que llegue al HTML. Construya el objeto solo con datos que la página ya muestra. Next.js documenta este patrón para page.tsx y layout.tsx en el App Router (guía de JSON-LD de Next.js, última actualización el 27 de febrero de 2026).
El marcado renderizado en el servidor está en la primera respuesta HTML, así que puede leerlo en el código fuente antes de que se ejecute cualquier JavaScript del cliente. Google dice que puede procesar datos estructurados que JavaScript agrega a la página renderizada, y sus recomendaciones indican que se incluyan datos estructurados en el resultado renderizado en el servidor al usar renderizado del lado del servidor (guía de datos estructurados con JavaScript de Google).
Ninguna prueba garantiza posicionamiento, resultados enriquecidos ni citas en IA, así que cada comprobación se refiere a la exactitud y la disponibilidad.
JSON, JSON-LD y Schema.org
JSON es un formato de texto de claves y valores: objetos, arreglos, cadenas, números, booleanos y null. Páselo por un analizador para confirmar que la sintaxis es válida.
JSON-LD es JSON con algunas claves reservadas para Linked Data, definidas por el W3C (especificación JSON-LD 1.1). @context indica el vocabulario, @type indica el tipo de cosa que se describe, y @id da a esa cosa un identificador estable. Schema.org es el vocabulario compartido de tipos y propiedades, así que Article y headline vienen de Schema.org, mientras que las claves con @ vienen de JSON-LD.
Los datos estructurados son información legible por máquinas que describe lo que la página ya dice. No agregan contenido visible. Google recomienda JSON-LD porque es más fácil de mantener a gran escala, y sus directrices indican que el marcado debe coincidir con el contenido visible de la página y que nunca se garantiza un resultado enriquecido (introducción a los datos estructurados de Google, directrices generales de Google).
Renderizar JSON-LD desde un Server Component en el App Router
Next.js recomienda un elemento <script> en layout.js o page.js. Utilice page.tsx para datos de una página concreta, como un artículo, y layout.tsx para datos que se repiten en una sección del sitio, como la organización editora. Un Server Component se ejecuta en el servidor, así que el script llega al HTML que recibe el navegador.
El siguiente ejemplo es el patrón de Next.js con datos ficticios. Construye un objeto, lo serializa, escapa el carácter menor que y renderiza el script junto al encabezado visible.
const jsonLd = {
"@context": "https://schema.org",
"@type": "Article",
"@id": "https://example.com/articles/rendering-json-ld#article",
"url": "https://example.com/articles/rendering-json-ld",
"headline": "Renderizar JSON-LD en un sitio React con renderizado en el servidor",
"description": "Una guía ficticia para renderizar JSON-LD seguro en React.",
"image": [
"https://example.com/images/json-ld-1x1.jpg",
"https://example.com/images/json-ld-4x3.jpg",
"https://example.com/images/json-ld-16x9.jpg"
],
"author": {
"@type": "Person",
"@id": "https://example.com/about/example-author#person",
"name": "Example Author",
"url": "https://example.com/about/example-author"
},
"publisher": {
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Example Publishing",
"url": "https://example.com"
},
"datePublished": "2026-01-10T09:00:00-06:00",
"dateModified": "2026-02-02T14:30:00-06:00",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://example.com/articles/rendering-json-ld"
}
};
const jsonLdString = JSON.stringify(jsonLd).replace(/</g, "\\u003c");
export default function Page() {
return (
<>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: jsonLdString }}
/>
<main>
<h1>Renderizar JSON-LD en un sitio React con renderizado en el servidor</h1>
</main>
</>
);
}Reemplace cada valor example.com por la URL de su propia página, las URL de sus imágenes, la página del autor y la organización. Luego haga que los valores coincidan con la página: el headline debe coincidir con el encabezado visible, las fechas deben coincidir con la firma de autoría o con las fechas que muestra la página, y el autor debe ser la persona o la organización que aparece allí. En un proyecto real, lea estos valores de la misma fuente que renderiza la página visible, para que el marcado y el texto no puedan desfasarse.
Escapar el carácter menor que antes de insertarlo
La guía de Next.js advierte que la salida normal de JSON.stringify no sanitiza cadenas maliciosas, lo que supone un riesgo de cross-site scripting (XSS). XSS significa que el contenido no confiable se interpreta como marcado o script ejecutable. Dentro de un elemento script, el navegador analiza primero el HTML, así que un valor de cadena que contenga </script> podría cerrar el elemento antes de tiempo. Reemplazar < por \u003c elimina esa posibilidad, y como \u003c es un escape estándar de JSON, un analizador JSON lo sigue leyendo como <.
Esto importa sobre todo cuando un valor viene de usuarios o de un CMS, como el título de una entrada escrito en un editor. Cuando los datos son totalmente confiables, aplicar el escape cuesta una sola línea, así que conviene aplicarlo en todas partes en lugar de decidir caso por caso. Un componente compartido pequeño mantiene esa línea en un solo lugar.
type JsonLdProps = { data: Record<string, unknown> };
export function JsonLd({ data }: JsonLdProps) {
const json = JSON.stringify(data).replace(/</g, "\\u003c");
return (
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: json }}
/>
);
}Importe JsonLd en cualquier página o layout y pase el objeto como data. El escape es una capa, no toda la defensa. Next.js indica que la carga útil debe armarse con datos confiables y validados, así que revise el tipo de cada valor del CMS, por ejemplo que una fecha sea una fecha y una URL sea una URL, antes de que entre en el objeto.
Renderizar JSON-LD en el servidor en otras configuraciones de React
Fuera del App Router, la regla es la misma: el script debe estar en el HTML que produce su servidor o su paso de compilación. En una aplicación React, renderice el script durante el renderizado del lado del servidor o la generación estática cuando sea posible. El componente JsonLd de arriba es un elemento de React común, así que funciona en cualquier lugar donde la página que lo rodea se renderiza a HTML en el servidor o durante la compilación.
Una aplicación React que solo se renderiza en el navegador es diferente. Su primera respuesta HTML es un esqueleto vacío, y cualquier script agregado en un effect existe solo después de que se ejecute JavaScript. Google todavía puede leerlo desde la página renderizada, pero ahora depende de que el script cargue, de que terminen las solicitudes a la API y de que el rastreador renderice la página. Si el marcado es importante, muévalo al renderizado en el servidor o a la generación estática.
La hidratación de React agrega una regla más. La hidratación es el proceso en el que React asocia el comportamiento del cliente con el HTML que ya produjo el servidor, y espera que ambos lados coincidan. Mantenga determinista el objeto JSON-LD, es decir, sin fechas, identificadores ni valores aleatorios que se generen por separado en el servidor y en el navegador. Calcúlelos una sola vez a partir de sus datos y páselos al componente.
Utilice un ejemplo completo de Article y elija sus propiedades
El objeto Article de abajo es JSON-LD válido, con datos ficticios y URL de example.com. Es el mismo objeto que construye el componente de la página, escrito como JSON simple para que pueda pegarlo en un validador.
{
"@context": "https://schema.org",
"@type": "Article",
"@id": "https://example.com/articles/rendering-json-ld#article",
"url": "https://example.com/articles/rendering-json-ld",
"headline": "Renderizar JSON-LD en un sitio React con renderizado en el servidor",
"description": "Una guía ficticia para renderizar JSON-LD seguro en React.",
"image": [
"https://example.com/images/json-ld-1x1.jpg",
"https://example.com/images/json-ld-4x3.jpg",
"https://example.com/images/json-ld-16x9.jpg"
],
"author": {
"@type": "Person",
"@id": "https://example.com/about/example-author#person",
"name": "Example Author",
"url": "https://example.com/about/example-author"
},
"publisher": {
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Example Publishing",
"url": "https://example.com"
},
"datePublished": "2026-01-10T09:00:00-06:00",
"dateModified": "2026-02-02T14:30:00-06:00",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://example.com/articles/rendering-json-ld"
}
}La documentación de Article de Google menciona Article, NewsArticle y BlogPosting como tipos compatibles y no indica propiedades obligatorias. Recomienda agregar las que correspondan: headline, image, author (con author.name y author.url), datePublished y dateModified (datos estructurados de Article de Google). Las propiedades url, description, publisher, mainEntityOfPage y @id son opcionales para esa función de Google. Cada una pertenece al vocabulario de Schema.org, independientemente de lo que Google muestre (Article en Schema.org).
Que una propiedad sea «obligatoria» depende de quién lo pregunte. Una propiedad puede ser opcional para la función Article de Google y, aun así, ser útil para el significado que Schema.org da a la página o para otro consumidor. Antes de llamar obligatoria a una propiedad, indique para quién lo es. La guía de schema de Article explica con más detalle las decisiones sobre autor y fechas, y el generador de schema de Article puede construir el objeto a partir de un formulario.
Agregar una ruta de navegación y un grafo combinado
Agregue un BreadcrumbList solo cuando la ruta de navegación sea visible en la página, porque el marcado debe describir lo que los lectores pueden ver. La ruta de abajo corresponde a una ruta visible de Artículos seguida del título del artículo.
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"@id": "https://example.com/articles/rendering-json-ld#breadcrumb",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Artículos",
"item": "https://example.com/articles"
},
{
"@type": "ListItem",
"position": 2,
"name": "Renderizar JSON-LD en un sitio React con renderizado en el servidor",
"item": "https://example.com/articles/rendering-json-ld"
}
]
}La función Breadcrumb de Google tiene sus propios requisitos vigentes, así que lea su página de función en la galería de datos estructurados de Google al publicar, y mantenga eso separado de si el tipo es válido en BreadcrumbList de Schema.org. La guía de schema de ruta de navegación y el generador de schema de ruta de navegación explican los detalles.
Dos objetos en una misma página pueden renderizarse como dos elementos script, uno por objeto. Para vincularlos, colóquelos en un solo @graph, de modo que el Article pueda apuntar al autor y al editor mediante @id en lugar de repetirlos. El grafo de abajo conserva los mismos datos y agrega la ruta de navegación.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Article",
"@id": "https://example.com/articles/rendering-json-ld#article",
"url": "https://example.com/articles/rendering-json-ld",
"headline": "Renderizar JSON-LD en un sitio React con renderizado en el servidor",
"description": "Una guía ficticia para renderizar JSON-LD seguro en React.",
"image": "https://example.com/images/json-ld-16x9.jpg",
"author": { "@id": "https://example.com/about/example-author#person" },
"publisher": { "@id": "https://example.com/#organization" },
"datePublished": "2026-01-10T09:00:00-06:00",
"dateModified": "2026-02-02T14:30:00-06:00",
"mainEntityOfPage": { "@id": "https://example.com/articles/rendering-json-ld" }
},
{
"@type": "Person",
"@id": "https://example.com/about/example-author#person",
"name": "Example Author",
"url": "https://example.com/about/example-author"
},
{
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Example Publishing",
"url": "https://example.com"
},
{
"@type": "BreadcrumbList",
"@id": "https://example.com/articles/rendering-json-ld#breadcrumb",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Artículos", "item": "https://example.com/articles" },
{ "@type": "ListItem", "position": 2, "name": "Renderizar JSON-LD en un sitio React con renderizado en el servidor", "item": "https://example.com/articles/rendering-json-ld" }
]
}
]
}En una página de Next.js, pase todo este objeto al componente JsonLd, y el HTML renderizado contendrá un solo script para el grafo. La guía de grafos JSON-LD explica cómo funcionan las referencias @id, la guía de ejemplos de schema JSON-LD incluye más tipos para copiar, y el Schema Graph Builder puede armar un grafo sin escribir las referencias a mano.
No agregue marcado FAQPage para intentar obtener un resultado enriquecido de preguntas frecuentes de Google. Google anunció que los resultados enriquecidos de preguntas frecuentes dejarían de aparecer a partir del 7 de mayo de 2026, y eliminó la documentación de la función de preguntas frecuentes en junio de 2026 (actualizaciones de la documentación de Google). FAQPage sigue siendo un tipo válido de Schema.org, así que el marcado existente no se rompe, pero la antigua función de visualización de Google ya no está disponible. La guía de schema de preguntas frecuentes explica dónde todavía encaja.
Agregar tipos de TypeScript con schema-dts
El paquete schema-dts ofrece definiciones de TypeScript para Schema.org en forma de JSON-LD. Da uniones discriminadas, autocompletado y una comprobación de tipos más estricta, de modo que una propiedad mal escrita o una forma de valor incorrecta falla en su editor y no en producción. Lo mantiene Google, pero no es un producto con soporte oficial de Google (schema-dts en GitHub).
import type { Article, WithContext } from "schema-dts";
const jsonLd: WithContext<Article> = {
"@context": "https://schema.org",
"@type": "Article",
"@id": "https://example.com/articles/rendering-json-ld#article",
"url": "https://example.com/articles/rendering-json-ld",
"headline": "Renderizar JSON-LD en un sitio React con renderizado en el servidor",
"description": "Una guía ficticia para renderizar JSON-LD seguro en React.",
"image": "https://example.com/images/json-ld-16x9.jpg",
"author": {
"@type": "Person",
"name": "Example Author",
"url": "https://example.com/about/example-author"
},
"datePublished": "2026-01-10T09:00:00-06:00",
"dateModified": "2026-02-02T14:30:00-06:00"
};
const jsonLdString = JSON.stringify(jsonLd).replace(/</g, "\\u003c");Instale el paquete como dependencia de desarrollo, reemplace los valores de ejemplo y conserve la línea de escape. Los tipos detectan muchos errores de estructura, pero no demuestran que el contenido sea visible, veraz, apto para una función de Google ni aceptado por otro proveedor. Combínelos con un análisis de JSON, la validación de Schema.org, una prueba de la función de Google, una revisión del HTML renderizado y las herramientas específicas de cada proveedor que necesite.
Inserción del lado del cliente y renderizado de Google
Google dice que puede procesar datos estructurados en el DOM renderizado, que es la estructura del documento después de que un navegador o un rastreador ejecuta JavaScript. Eso incluye los datos que inserta JavaScript. Google también recomienda probar la URL publicada, y no solo el código pegado, porque probar código pegado tiene limitaciones con JavaScript (guía de datos estructurados con JavaScript de Google).
El renderizado en el servidor sigue teniendo su lugar. La inserción en el cliente funciona cuando la página renderizada final contiene marcado válido, pero depende de que se ejecute JavaScript, de que terminen las solicitudes a la API, del momento de la carga y del renderizado del rastreador. Los gestores de etiquetas tienen la misma dependencia, y Google advierte específicamente que el marcado de producto generado por un script puede hacer que los rastreos de Shopping sean menos frecuentes o menos confiables. La guía de schema con Google Tag Manager explica esa vía cuando un gestor de etiquetas es la única opción.

Si su JSON-LD no aparece en el código fuente de la página, pero sí en el inspector del navegador, se está agregando después de la carga. El código fuente muestra la respuesta HTML inicial, mientras que el inspector muestra el DOM renderizado. Mueva el script a un Server Component o a la generación estática, compile de nuevo y revise otra vez. En el caso del marcado crítico, trate el renderizado en el servidor como la opción predeterminada y la inserción en el cliente como la excepción.
Pruebe la página publicada
Pruebe la URL publicada, no solo el código de su editor, porque la caché, el middleware y la hidratación pueden cambiar lo que reciben los visitantes y los rastreadores. Empiece por la comprobación más sencilla: obtenga la página y confirme que el HTML contiene los scripts que espera, que cada uno se analiza correctamente y que no hay duplicados. Este fragmento hace eso para una URL.
const url = "https://example.com/articles/rendering-json-ld";
const html = await (await fetch(url)).text();
const pattern = /<script type="application\/ld\+json">([\s\S]*?)<\/script>/g;
const blocks = [...html.matchAll(pattern)];
console.log(`${blocks.length} JSON-LD script(s) found`);
blocks.forEach((match, index) => {
const data = JSON.parse(match[1]);
console.log(index + 1, data["@type"] ?? "@graph");
});Reemplace la URL por una página de su sitio. El patrón espera el orden simple de atributos que se muestra, así que ajústelo si su compilación agrega atributos al elemento script. Un error al ejecutar el fragmento significa que un script contiene JSON no válido, y un número de scripts mayor al que pretendía significa que un layout y una página emiten el mismo objeto.
Después, confirme que cada dato marcado sea visible en la página: el titular, el nombre del autor, las fechas y cada etiqueta de la ruta de navegación. Luego use el validador adecuado para cada pregunta. La Prueba de resultados enriquecidos comprueba la elegibilidad para las funciones compatibles de Google, no todas las propiedades de Schema.org. El Schema Markup Validator revisa la sintaxis del vocabulario, pero no predice cómo mostrará Google la página. La herramienta URL Inspection (Inspección de URL) de Google Search Console muestra la página renderizada que Google obtuvo.

Para otros motores, abra Bing Webmaster Tools y use Bing URL Inspection (Inspección de URL), cuya tarjeta «Markup» (marcado) muestra el JSON-LD que encontró Bing. Si le importa la visibilidad en Yandex, use el Yandex Structured Data Validator. El Schema Validator y el Schema Checker de Schema Nova también revisan código pegado y URL en vivo, y la guía para reemplazar la Structured Data Testing Tool explica qué comprobación responde a cada pregunta. Vuelva a probar después de cualquier actualización de Next.js o React, cambio en la hidratación, cambio en el CMS o cambio en la caché.
Haga que el marcado sea legible para Bing y la búsqueda con IA
Bing admite JSON-LD y valida los datos anotados según la especificación seleccionada (guía de Bing sobre datos estructurados), así que el bloque renderizado en el servidor le sirve. Copilot con acceso web usa resultados web de Bing, así que allí importan el acceso de Bingbot, los sitemaps y el robots.txt (acceso web de Copilot de Microsoft).
Para la búsqueda de ChatGPT, permita OAI-SearchBot en robots.txt; es independiente de GPTBot (documentación de rastreadores de OpenAI). Perplexity documenta la configuración de su rastreador y de robots.txt (guía de rastreadores de Perplexity). Mantenga el HTML visible como fuente de referencia, y consulte si los sistemas de IA usan el marcado schema.
Preguntas frecuentes
¿Un JSON-LD válido garantiza un resultado enriquecido?
No. Un marcado válido significa que la sintaxis y el vocabulario son correctos, y Google indica que un marcado correcto no garantiza un resultado enriquecido. Google también decide qué tipos de Schema.org pueden producir una función de la Búsqueda, y un tipo sin función de Google sigue siendo válido. Consulte la guía de resultados enriquecidos para ver cómo se deciden las funciones de visualización.
¿Necesito un schema especial para las AI Overviews de Google?
Google indica que las AI Overviews y el AI Mode no requieren marcado especial de Schema.org más allá de la elegibilidad normal en la Búsqueda. Siga agregando marcado preciso para los tipos de página que publica, porque esa declaración cubre solo la Búsqueda de Google, y otros consumidores documentan su propio comportamiento.
¿Debo usar schema-dts?
Es una buena opción cuando su equipo escribe en TypeScript y construye objetos en código, ya que detecta nombres de propiedades incorrectos y formas de valor equivocadas mientras escribe. Es opcional y no reemplaza la prueba de la página renderizada.
¿Dónde encuentro los pasos de configuración para WordPress, Shopify y otras plataformas?
Los sitios de Next.js y React hechos a mano se configuran con los pasos de arriba. Para las plataformas, consulte las guías de WordPress, Yoast frente a Rank Math, Shopify, Wix, Squarespace, Webflow, HubSpot y un sitio web con Perfil de Empresa de Google (Google Business Profile).
¿Cuál es la diferencia entre JSON y JSON-LD?
JSON es el formato de datos simple. JSON-LD usa la misma sintaxis y agrega claves como @context, @type y @id, para que los datos se lean como Linked Data con un vocabulario con nombre, como Schema.org.
