JSON-LD: dónde colocarlo y qué propiedades son obligatorias

PublicadoHerramientaGenerador de esquemas JSON-LD

Contenido
  1. Los datos estructurados no afectan al ranking, sino a lo que se muestra
  2. ¿Cómo es un bloque JSON-LD?
  3. Dónde se coloca
  4. Cómo crearlo y validarlo sin herramientas
  5. Las propiedades obligatorias no son lo mismo que las recomendadas
  6. Por qué no aparecen los resultados enriquecidos aunque ya hayas añadido el marcado
  7. En resumen
  8. Preguntas frecuentes

Si has leído que hay que “añadir JSON-LD” a un blog o a una página de producto, pero no tienes claro qué es exactamente ni dónde se coloca, este artículo es para ti.

En resumen: JSON-LD son datos que describen el contenido de la página en un formato que los motores de búsqueda pueden leer y que se incluyen dentro de la etiqueta <script type="application/ld+json"> del HTML.

Antes de entrar en materia, dejemos algo claro: añadir el marcado no hace que aparezcan resultados enriquecidos como estrellas o imágenes. La propia documentación de Google indica que “aunque el marcado sea correcto, no se garantiza que aparezca en los resultados de búsqueda”.

Resumen ① JSON-LD son datos JSON que se incluyen dentro de <script type="application/ld+json"> y, según la documentación de Google, pueden ir tanto en <head> como en <body>. ② Para optar a resultados enriquecidos, cada tipo tiene sus propiedades obligatorias. Article no tiene ninguna y un negocio local requiere name y address. ③ Aunque completes todas las propiedades obligatorias, no se garantiza que se muestren. Hay funciones que incluso desaparecen, como los resultados enriquecidos de FAQ.

Los datos estructurados no afectan al ranking, sino a lo que se muestra

Los resultados de búsqueda que incluyen elementos adicionales como estrellas, precios, imágenes o el nombre del sitio se llaman resultados enriquecidos (rich results). Estos elementos no son valores deducidos a partir del texto de la página, sino que provienen de los datos que la propia página declara.

Esa declaración es lo que se conoce como datos estructurados, y uno de los lenguajes para escribirla es JSON-LD. El vocabulario es schema.org y el formato de representación es JSON-LD 1.1 (recomendación del W3C de julio de 2020).

Aquí surgen malentendidos con frecuencia. Los datos estructurados son datos que afectan a la apariencia de los resultados de búsqueda, no un mecanismo para subir posiciones. La documentación de Google explica, en relación con las acciones manuales por datos estructurados, que “solo se pierde la posibilidad de aparecer como resultado enriquecido; no afecta al posicionamiento de la página en la búsqueda web”.

¿Cómo es un bloque JSON-LD?

Un bloque JSON-LD se compone de tres partes: la etiqueta que lo envuelve, @context, que indica el vocabulario, y @type, que aclara a qué se refieren los datos.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "구조화 데이터 입문 가이드",
  "author": { "@type": "Person", "name": "홍길동" },
  "datePublished": "2026-07-20",
  "image": "https://example.com/cover.jpg"
}
</script>

El valor del atributo type debe ser application/ld+json. Si escribes text/javascript, el navegador intentará ejecutar el JSON que contiene como código y dará un error; si escribes application/json, no se ejecutará, pero los motores de búsqueda no lo reconocerán como datos estructurados.

@context es la declaración que indica que los nombres que aparecen después, como headline y author, deben interpretarse con el vocabulario de schema.org. @type determina si estos datos describen un artículo, un producto o un comercio. Si falta alguno de los dos, el resto no se interpretará, por bien escrito que esté.

Cuando un valor es a su vez otro objeto, se escribe como un objeto anidado. Es lo que ocurre con author en el ejemplo anterior. Por eso, incluso para indicar el nombre de una persona, se envuelve en la forma { "@type": "Person", "name": "…" }.

Dónde se coloca

La documentación de Google describe JSON-LD como “una notación que se incluye en una etiqueta <script> dentro de los elementos <head> y <body> de una página HTML”. Es decir, puedes ponerlo en cualquiera de los dos.

El mismo documento señala que también puede leer el JSON-LD que JavaScript o un widget insertan más tarde. Esto ayuda si tu entorno no permite insertarlo directamente en el HTML estático.

También puedes incluir varios bloques en una misma página. Por ejemplo, en una página de artículo puedes poner un bloque Article y otro de ruta de navegación (BreadcrumbList).

Cómo crearlo y validarlo sin herramientas

El proceso consta de cuatro pasos. Puedes hacerlo perfectamente a mano.

Paso 1: Elige el tipo y revisa las propiedades obligatorias

Primero define qué es la página (artículo, producto, comercio, etc.). Después abre la documentación de la función correspondiente en Google Search Central y consulta la tabla de propiedades obligatorias. La lista varía según el tipo y la documentación se actualiza de vez en cuando.

Paso 2: Escribe el JSON

Con la forma del ejemplo anterior, escribe primero @context y @type, y después completa las propiedades que hayas consultado. Para las propiedades cuyo valor desconozcas, es mejor omitirlas que dejarlas como una cadena vacía. Un valor vacío puede interpretarse como un dato incorrecto.

Paso 3: Revisa la sintaxis

En JSON, una sola coma mal puesta invalida todo el bloque. Si pegas lo siguiente en la consola de las herramientas de desarrollo del navegador (normalmente, F12), sabrás al instante si todos los bloques JSON-LD de esa página se analizan correctamente.

[...document.querySelectorAll('script[type="application/ld+json"]')]
  .map(s => { try { return JSON.parse(s.textContent); } catch (e) { return "파싱 실패: " + e.message; } })

Paso 4: Comprueba si cumples los requisitos

La prueba de resultados enriquecidos de Google (search.google.com/test/rich-results) te indica a qué funciones de resultados enriquecidos de Google puede optar la página. Si solo quieres revisar la sintaxis, usa el validador de marcado de schema.org (validator.schema.org). Las dos herramientas no comprueban lo mismo.

El problema está en los pasos 1 y 2. Tienes que buscar cada vez en la documentación los nombres de las propiedades y la estructura anidada, copiarlos y ajustar a mano las comas y las llaves.

Pruébalo con el Generador de esquemas JSON-LD, nuestra herramienta gratuita. Elige uno de los tipos Article, Product, FAQ o LocalBusiness en la pestaña superior y rellena el formulario; el JSON-LD se completa en tiempo real. Los campos que dejes vacíos se excluyen automáticamente del resultado y, si activas la opción de envolverlo en una etiqueta <script>, obtendrás una versión lista para pegar.

Generador de esquemas JSON-LD

Se genera directamente en el navegador, sin instalación ni registro, y el contenido que escribes no se envía al servidor.

Las propiedades obligatorias no son lo mismo que las recomendadas

Aquí es donde suele haber confusión. El vocabulario de schema.org en sí no incluye ninguna marca de “obligatorio”. Las propiedades obligatorias son una lista que los motores de búsqueda exigen aparte para una función concreta de resultados enriquecidos.

Si nos atenemos a la documentación de Google, el resumen es este:

TipoPropiedades obligatorias que exige Google
Article (artículo)Ninguna: solo tiene propiedades recomendadas
Product (fragmento de producto)name y uno de review, aggregateRating u offers
LocalBusiness (negocio local)name, address

Puede parecer extraño que Article no tenga propiedades obligatorias. La documentación de Google señala que “no hay propiedades obligatorias; incluye las propiedades que correspondan al contenido”. En cambio, establece headline, image, datePublished, dateModified y author como propiedades recomendadas.

Por el contrario, para un fragmento de producto el nombre no basta. Para optar a él, debe haber al menos una reseña, una valoración agregada o información de venta.

Podría parecer que cuantas más propiedades recomendadas incluyas, mejor, pero la documentación de Google especifica que es mejor incluir pocas y correctas que rellenar todas las propiedades recomendadas de forma deficiente.

Por qué no aparecen los resultados enriquecidos aunque ya hayas añadido el marcado

Puede que hayas completado todas las propiedades obligatorias y aun así los resultados de búsqueda sigan igual. Por lo general, la causa es una de estas cuatro.

SituaciónQué ocurre
La función ya no existeEl marcado es válido, pero no hay ningún sitio donde mostrarlo
Marcas contenido que no aparece en la páginaEs una infracción de las políticas y puedes perder la elegibilidad
Faltan propiedades obligatoriasNi siquiera se genera la elegibilidad para esa función
Hay elegibilidad, pero no se muestraEl buscador decide de qué forma lo enseña

La primera fila tiene un ejemplo real: las preguntas frecuentes. Los resultados enriquecidos de FAQ se limitaron en agosto de 2023 a sitios muy conocidos de los ámbitos gubernamental y de salud, y desde el 7 de mayo de 2026 no se muestran en la Búsqueda de Google.

El marcado FAQPage sigue siendo datos válidos de schema.org. Lo que ya no ocurre es que aparezca como acordeón de preguntas frecuentes en la Búsqueda de Google.

La segunda fila también importa. Las directrices de Google son tajantes: «no marques contenido que no sea visible para quien lee la página». Un caso típico de infracción es poner en el JSON-LD una valoración o un precio que no aparecen en pantalla.

La cuarta fila es el punto de partida de este artículo: la elegibilidad es cuestión de aprobar o no, y la visualización depende de lo que decida el buscador. Aunque la prueba de resultados enriquecidos confirme que cumples los requisitos, en los resultados reales puedes aparecer como texto normal.

En resumen

  • JSON-LD son datos JSON que se colocan dentro de <script type="application/ld+json">, y deben incluir obligatoriamente @context y @type.
  • Se puede poner tanto en el <head> como en el <body>, y puede haber varios bloques en una misma página.
  • Las propiedades obligatorias no las marca schema.org, sino la lista que el buscador exige para cada función. Article no tiene propiedades obligatorias, y en un negocio local name y address son obligatorias.
  • En las propiedades recomendadas, conviene rellenarlas con exactitud antes que aumentar su número.
  • Aunque el marcado sea correcto, no se garantiza que aparezcan resultados enriquecidos, y hay funciones que desaparecen, como ocurrió con FAQ.
  • Los datos estructurados influyen en cómo se muestran los resultados de búsqueda, no son un mecanismo para subir posiciones.
Generador de esquemas JSON-LD

Se genera directamente en el navegador, sin instalación ni registro, y el contenido que escribes no se envía al servidor.

Preguntas frecuentes

¿El JSON-LD va en el head o en el body?

La documentación de Google describe la forma de incluirlo en una etiqueta <script> dentro de los elementos <head> y <body>. Se lee en cualquiera de los dos sitios. Además, indica que también se puede leer el JSON-LD insertado más tarde con JavaScript en el mismo documento, así que hay alternativa incluso en entornos donde cuesta tocar la plantilla directamente.

¿Añadir el marcado mejora mi posición en los resultados de búsqueda?

Los datos estructurados influyen en cómo se muestran los resultados, no en la posición. Sobre las acciones manuales por datos estructurados, la documentación de Google explica que «solo se pierde la elegibilidad para aparecer como resultado enriquecido, pero no afecta a la posición de la página en la Búsqueda web». También especifica que, aunque el marcado sea correcto, no se garantiza que se muestren resultados enriquecidos.

¿Ya no hace falta añadir el marcado de FAQ?

Los resultados enriquecidos de FAQ de la Búsqueda de Google no se muestran desde el 7 de mayo de 2026. Aun así, FAQPage sigue siendo un tipo válido de schema.org y dejar el marcado no supone ningún problema. Si lo añadías esperando que apareciera como acordeón de preguntas frecuentes en la Búsqueda de Google, ahora mismo ese efecto ya no existe.

¿Lo que escribo en el formulario se envía a un servidor?

No. En el Generador de esquemas JSON-LD, la creación del JSON-LD se hace por completo dentro del navegador, y valores como el título, la dirección o el teléfono que introduces no se envían ni se guardan en ningún servidor. Los campos que dejas vacíos se excluyen automáticamente del JSON resultante, así que en el código solo queda lo que has rellenado.

Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano

Artículos relacionados

  1. Lotería 6/45: combinaciones, casos posibles y generadorAprende cuántas combinaciones hay en la lotería 6/45 (8.145.060), cómo se reducen al fijar o excluir números y la extracción justa con Fisher-Yates.
  2. Qué es la dirección MAC y cómo la MAC aleatoria evita el rastreoUna dirección MAC es un valor fijo por dispositivo, así que puede vincular tus conexiones wifi. Descubre cómo la MAC aleatoria rompe ese rastro.
  3. Meta description vs. og:description: diferencias y comprobaciónMeta description, og:description y twitter:description son etiquetas distintas: qué lee cada plataforma y cómo comprobarlo en el código fuente.
  4. ¿Qué es una frase de contraseña? Su fuerza según la entropíaDescubre qué es una frase de contraseña y compara con cifras si una contraseña corta y compleja o una combinación larga de palabras es más segura.
  5. Contraseña de 8 vs 12 caracteres: 2,6 billones de veces másPasar de 8 letras minúsculas a 12 caracteres con mayúsculas, números y símbolos multiplica las combinaciones por 2,6 billones. Estas son las fórmulas.
  6. CLS por imágenes: cómo evitar que la pantalla se desplacePor qué las imágenes sin tamaño provocan CLS y cómo reservar su espacio con width, height o aspect-ratio, o con un marcador de posición.

Herramientas relacionadas