Cómo agregar marcado de schema (JSON-LD) y probarlo

Por el equipo de Mayab Media · Nivel: Intermedio · Tiempo: 1 hora

Agregaste schema a tu sitio y en Google no cambió nada. O corriste una prueba y te salió «No se ha detectado ningún elemento», un error rojo de «Falta un campo» o una advertencia que no entiendes. A lo mejor un plugin agregó tres bloques Organization distintos y no sabes cuál lee Google.

El marcado de schema son datos estructurados: un bloque corto de código que le dice a los buscadores de qué trata una página, en un formato fácil de leer para las máquinas. Google recomienda el formato JSON-LD dentro de una etiqueta <script>. Cuando el marcado es válido y coincide con lo que se ve en la página, esta puede volverse apta para resultados enriquecidos, como precios y calificaciones de productos, rutas de exploración, fechas de eventos o miniaturas de video.

La palabra clave es «apta». Un marcado válido no garantiza un resultado enriquecido. Esta guía te muestra cómo elegir un tipo que Google todavía admite, escribir el JSON-LD, agregarlo en las plataformas más comunes y probarlo con tres herramientas para saber exactamente dónde está el problema.

Respuesta rápida

1. Revisa la galería de búsqueda de Google para confirmar que el resultado enriquecido que quieres sigue existiendo y lee sus propiedades obligatorias.
2. Escribe un bloque JSON-LD que describa solo lo que se ve en la página.
3. Agrégalo al HTML (tema, plugin, inyección de código o plantilla), de preferencia una vez por tipo de página.
4. Prueba el código o la URL publicada en la Prueba de resultados enriquecidos para funciones de Google y en el Schema Markup Validator para la sintaxis general de schema.org.
5. Cuando Google vuelva a rastrear, revisa Inspección de URLs y los informes de Mejoras (o Shopping) en Search Console.
6. Corrige los errores en la plantilla y haz clic en VALIDATE FIX (Validar corrección) en el problema.

Antes de empezar

Necesitas:

• Acceso para editar las plantillas del sitio, un plugin de SEO o el área de inyección de código de la plataforma.
• Acceso a la propiedad de Search Console para ver los informes de resultados enriquecidos.
• Los datos que vas a marcar: nombre del negocio, URL del logo, dirección, teléfono, precios de productos, fechas de eventos, etcétera. Deben coincidir con lo que dice la página.

Haz un respaldo antes de empezar. En WordPress, exporta la configuración del plugin o respalda el sitio. En Squarespace y Shopify, copia en un archivo de texto cualquier inyección de código o archivo del tema que ya exista.

Revisa lo que ya tienes. Muchos temas y plugins de SEO agregan schema en automático. Si sumas el tuyo encima, puedes crear duplicados o conflictos.

Paso 1: Elige un tipo de schema que Google siga admitiendo

Abre la galería de búsqueda (Search gallery) de funciones de datos estructurados de Google. Ahí están los tipos que hoy pueden generar un resultado enriquecido. En noviembre de 2026 incluye Article, Breadcrumb, Carousel, Course list, Dataset, Discussion forum, Education Q&A, Employer aggregate rating, Event, Image metadata, Job posting, Local business, Math solver, Movie, Organization, Product, Profile page, Q&A, Recipe, Review snippet, Software app, Speakable, Subscription and paywalled content, Vacation rental y Video. Revisa la página en vivo, porque la lista se sigue reduciendo.

Varias funciones ya se retiraron:

• FAQ (preguntas frecuentes): Google anunció que los resultados enriquecidos de FAQ ya no aparecen en la Búsqueda desde el 7 de mayo de 2026, y retiró la documentación de FAQ en junio de 2026. También anunció que en junio de 2026 quitaría la apariencia de búsqueda de FAQ, su informe en Search Console y el soporte en la Prueba de resultados enriquecidos.
• HowTo: se retiró de los resultados en 2023.
• Siete más en 2025: Google eliminó Book actions, Course info, Claim review, Estimated salary, Learning video, Special announcement y Vehicle listing para simplificar la página de resultados.

Puedes conservar el marcado FAQPage u otro marcado retirado si ya lo tienes. Sigue siendo schema.org válido, y el aviso de retirada de Google dijo que puedes quitarlo, pero que no es obligatorio. Solo no lo agregues esperando un resultado enriquecido.

Elige según el tipo de página:

Para cada tipo, abre su página de documentación en Search Central. Anota las propiedades obligatorias y recomendadas. Si falta una obligatoria, el elemento no es válido. Si falta una recomendada, solo verás una advertencia.

Paso 2: Escribe el JSON-LD

El JSON-LD va en un bloque de script. No cambia cómo se ve la página. Este es un ejemplo de Organization para la página de inicio:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Studio",
  "url": "https://example.com/",
  "logo": "https://example.com/img/logo-512.png",
  "sameAs": [
    "https://www.linkedin.com/company/example-studio",
    "https://www.instagram.com/examplestudio"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer service",
    "email": "hola@example.com"
  }
}
</script>

Y una ruta de exploración para una página interna:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {"@type": "ListItem", "position": 1, "name": "Guías", "item": "https://example.com/guias"},
    {"@type": "ListItem", "position": 2, "name": "Marcado de schema", "item": "https://example.com/guias/schema"}
  ]
}
</script>

Reglas que evitan casi todos los errores:

• Usa comillas dobles rectas, no las comillas curvas de un procesador de texto.
• No dejes una coma después del último elemento de un objeto o lista.
• Usa URLs absolutas que empiecen con https://.
• Usa fechas ISO 8601, como 2026-11-05 o 2026-11-05T09:00:00-06:00.
• Marca solo contenido que la gente pueda ver en esa página. Las directrices de Google piden no marcar información oculta o engañosa.
• No agregues estrellas de reseñas sobre tu propio negocio en tu propio sitio. Google no muestra fragmentos de reseñas autopromocionales para Organization ni LocalBusiness.

Prueba el fragmento antes de publicarlo. Abre la Prueba de resultados enriquecidos (search.google.com/test/rich-results), cambia de la pestaña URL a la pestaña CODE (Código), pega el bloque completo con las etiquetas <script> y haz clic en TEST CODE (Probar código). La prueba usa por defecto el rastreador para smartphones. Obtienes la misma pantalla de resultados que en una prueba de URL, la del paso 4. Si solo quieres revisar la sintaxis de tipos que Google no usa para resultados enriquecidos, pega el mismo código en el Schema Markup Validator.

Paso 3: Agrega el marcado a tu sitio

Pon el JSON-LD en el <head> o en el <body>. Las dos opciones funcionan. Lo importante es que esté en el HTML que renderiza Google y que cada página reciba un marcado que coincida con ella.

WordPress

La mayoría de los plugins de SEO (Yoast, Rank Math, All in One SEO y otros) generan Organization, WebSite, Article y BreadcrumbList en automático. Configúralos primero en los ajustes de schema o de «Knowledge Graph» del plugin. Llena ahí el nombre del negocio, el logo y los perfiles sociales.

Para tipos adicionales que el plugin no cubra, usa su función de schema personalizado si la tiene, o un plugin de fragmentos de código que agregue código en páginas específicas. Evita pegar schema de todo el sitio en un módulo del constructor de páginas en cada página.

Shopify

Casi todos los temas actuales ya generan marcado Product en las páginas de producto. Antes de agregar algo, prueba la URL de un producto en la Prueba de resultados enriquecidos. Si detecta Product, edita el fragmento existente del tema en lugar de agregar un segundo bloque. Los archivos del tema están en Tienda online > Temas > Editar código (las etiquetas pueden variar según la versión del panel). Antes, copia el tema con Duplicar.

Squarespace

Squarespace agrega por su cuenta algunos datos estructurados básicos. Para marcado adicional:

• Para todo el sitio (por ejemplo, Organization en todas las páginas): en Squarespace 7.1 abre el panel Pages (Páginas), baja hasta Custom Code (Código personalizado) y haz clic en Code Injection (Inyección de código). Pega el script en el cuadro HEADER (Encabezado), que inserta el código en la etiqueta head de todas las páginas, y haz clic en Save (Guardar) arriba a la izquierda. La ruta antigua Settings > Advanced > Code Injection ahora redirige a la misma pantalla. La inyección de código no está disponible en todos los planes.
• Para una sola página: abre la Configuración de la página > Avanzado y usa la Inyección de código en el encabezado de la página.

Haz clic en Save y prueba una URL publicada. Mantén cada bloque JSON-LD en su propia etiqueta <script> para que un error no rompa el resto del código del cuadro.

Google Tag Manager

Puedes insertar JSON-LD con una etiqueta de HTML personalizado. Google puede leer datos estructurados agregados con JavaScript cuando renderiza la página. Aun así, es un plan B. El renderizado puede retrasarse o fallar, y el marcado no existe para herramientas que no ejecutan JavaScript. Úsalo solo si no puedes editar las plantillas.

Sitios a la medida

Genera el JSON-LD con los mismos datos que llenan la página. Una plantilla de producto debe imprimir el precio desde el registro del producto, no un número escrito a mano. Así el marcado y el contenido visible siempre coinciden.

Paso 4: Prueba la página publicada con dos validadores

Después de publicar, prueba la URL en vivo. Usa las dos herramientas, porque responden preguntas distintas.

La Prueba de resultados enriquecidos responde: «¿Esta página puede obtener un resultado enriquecido de Google?». Solo muestra los tipos que Google admite para resultados enriquecidos y revisa las propiedades obligatorias de Google.

Ábrela, deja la pestaña URL, pega la URL publicada y haz clic en TEST URL (Probar URL).

Haz clic en un tipo para abrir sus elementos. Cada elemento muestra primero sus problemas y luego una tabla con las propiedades que leyó Google:

El Schema Markup Validator (validator.schema.org) responde: «¿Esto es schema.org válido?». Lee todos los tipos, incluso los que Google no usa para resultados enriquecidos, y señala errores de sintaxis y propiedades desconocidas. Es la herramienta correcta para revisar datos de Organization, enlaces sameAs o tipos anidados.

Lee los resultados así:

• Los problemas críticos (errores) en la Prueba de resultados enriquecidos invalidan el elemento para esa función. El resumen dice entonces que hay elementos no válidos.
• Los problemas no críticos (en naranja, marcados como «(optional)») indican que falta una propiedad recomendada. El elemento puede seguir siendo apto.
• No se ha detectado ningún elemento significa que Google no encontró marcado que admita. Revisa que el script esté en el HTML renderizado (haz clic en VIEW TESTED PAGE > HTML) y que el tipo siga vigente.
• Los bloques duplicados aparecen como dos elementos del mismo tipo. Quita una de las fuentes, normalmente la manual si un plugin ya lo cubre.

Paso 5: Da seguimiento en Search Console

Cuando Google vuelva a rastrear las páginas, dos lugares de Search Console muestran lo que encontró.

URL inspection (Inspección de URLs). Pega una URL en la barra Inspect any URL de arriba. En Enhancements & Experience (Mejoras y experiencia), el resultado lista HTTPS y cada tipo de datos estructurados que Google detectó en la versión indexada, como Breadcrumbs con «1 valid item detected». Haz clic en TEST LIVE URL para revisar una versión que acabas de cambiar.

Informes de resultados enriquecidos. En el menú izquierdo, busca en Enhancements (Mejoras), por ejemplo Breadcrumbs, Events, Review snippets o Videos. Los informes de producto están en Shopping, como Product snippets y Merchant listings. Un informe solo aparece cuando Google encuentra marcado de ese tipo en tu sitio.

Debajo de la gráfica, los problemas se agrupan por tipo. Los críticos invalidan elementos; los no críticos solo limitan cómo puede verse el resultado. Haz clic en un problema para ver elementos de ejemplo y corrige la plantilla que los genera.

Los informes cuentan elementos, no páginas, y muestran una muestra. Una página puede tener varios elementos. Cuando corrijas la plantilla, abre el problema y haz clic en VALIDATE FIX (Validar corrección). Google vuelve a revisar los elementos afectados en los días o semanas siguientes.

¿Sigue sin funcionar? Causas comunes

Marcado que coincide con la página

La mayoría de los problemas que regresan vienen de un marcado que se separa de la página. Termina una oferta, cambia el precio visible y el JSON-LD escrito a mano sigue mostrando el anterior. O se quita un widget de reseñas y el marcado de calificación se queda. Si conectas el marcado con los datos de la página, estos problemas desaparecen.

Schema y búsqueda con IA

Los datos estructurados ayudan a los buscadores a entender entidades como tu negocio, tus productos y tus autores. No reemplazan un contenido claro. Úsalos para etiquetar datos que ya están en la página.

Cómo confirmar que quedó resuelto

Justo después de publicar:

1. Prueba dos o tres URLs publicadas por tipo de página en la Prueba de resultados enriquecidos. Cada una debe mostrar los tipos esperados como válidos, sin problemas críticos.
2. Pasa esas mismas URLs por el Schema Markup Validator para detectar problemas de sintaxis que la otra prueba ignora.
3. Verifica que haya un solo bloque por tipo, salvo que quieras más de uno.

En las siguientes una a cuatro semanas:

1. Usa Inspección de URLs en una página clave. La versión indexada debe listar los datos estructurados que agregaste.
2. Vigila el informe correspondiente en Mejoras o Shopping. Los elementos válidos deben subir y los no válidos, bajar.
3. Si hiciste clic en VALIDATE FIX, espera a que el estado termine como Passed (Superada).

Si tus páginas todavía no están indexadas, Google tampoco puede leer su marcado. Empieza con cómo lograr que Google indexe tu sitio. Si ya están indexadas pero son lentas, revisa cómo mejorar las Core Web Vitals.

Preguntas frecuentes

¿JSON-LD es mejor que Microdata?

Google admite JSON-LD, Microdata y RDFa, y recomienda JSON-LD porque es más fácil de agregar y mantener. Vive en un solo bloque en lugar de repartirse por tu HTML.

¿Debo quitar mi marcado FAQPage?

No es necesario. Los resultados enriquecidos de FAQ dejaron de mostrarse el 7 de mayo de 2026, pero el marcado sigue siendo schema.org válido y Google dice que no es obligatorio quitarlo. Solo no esperes que genere un resultado enriquecido, y no inviertas tiempo en agregar FAQ nuevas con ese fin.

¿Cuánto tardan en aparecer los resultados enriquecidos?

Depende de cuándo vuelva a rastrear Google la página y de si decide mostrar un resultado enriquecido. Para páginas importantes, cuenta de días a unas semanas. Algunas páginas válidas nunca lo obtienen.

¿El marcado de schema mejora el posicionamiento?

Google lo usa para entender las páginas y habilitar resultados enriquecidos, no como un impulso directo de posicionamiento. El beneficio suele venir de fichas de búsqueda más útiles.

¿Puedo poner el schema en Google Tag Manager?

Sí, y Google puede leerlo después de renderizar. Es menos confiable que el marcado en el HTML. Si usas GTM para medición, revisa nuestra guía para instalar Google Tag Manager correctamente.

Fuentes

• developers.google.com: /search/docs/appearance/structured-data/intro-structured-data
• developers.google.com: /search/docs/appearance/structured-data/search-gallery
• support.google.com: /webmasters/answer/7552505
• developers.google.com: /search/updates
• developers.google.com: /search/blog/2025/06/simplifying-search-results
• validator.schema.org: /
• search.google.com: /test/rich-results