Lo que aprendí al auditar datos JSON-LD en CI
Los datos estructurados JSON-LD pueden desaparecer de tu sitio sin romper nada visible. Tu build tiene éxito. Tu despliegue se completa. Tus páginas se ven bien en el navegador.
Pero Googlebot lee las etiquetas script para decidir tus resultados enriquecidos (rich results). Si los datos faltan o están dañados, no lo sabrás hasta que Search Console lo señale semanas después.
Añadí un paso de auditoría post-despliegue a mi pipeline de CI. Encuentra estos errores en menos de 60 segundos.
Cómo funciona:
Ejecuto tres sitios estáticos construidos con Astro y desplegados a través de Cloudflare Pages. Estos sitios utilizan esquemas como SoftwareApplication, VideoGame e ItemList. Al ser estáticos, un cambio en la plantilla puede eliminar el esquema de miles de páginas sin activar un error de build.
El script de auditoría hace lo siguiente:
• Obtiene la página de inicio en vivo y páginas de detalle de muestra. • Lee el sitemap en vivo para encontrar URLs reales. • Extrae todos los bloques JSON-LD usando regex. • Comprueba el desempaquetado de @graph para encontrar elementos anidados. • Compara los valores @type encontrados con mi lista de valores esperados.
Ejecuto esto contra las páginas desplegadas en vivo en lugar de los artefactos de build. Esto detecta problemas con el almacenamiento en caché de la CDN o la entrega en el edge.
El script encontró tres problemas en la primera ejecución:
- ossfind.com: Falta ItemList en páginas específicas. Esto convirtió una idea vaga en una tarea concreta.
- findindiegame.com: Un protocolo http:// incorrecto en el @id de WebSite. Fue un error de copiar y pegar que parecía correcto para un humano, pero era inconsistente para Google.
- aiappdex.com: Uso de IDs de base de datos en bruto en lugar de nombres legibles para humanos en el esquema SoftwareApplication.
Estos eran errores reales. Ninguno apareció en los logs de build ni en las revisiones del navegador.
Configuré el paso de CI para que no sea fatal. Si la auditoría encuentra un problema, el despliegue se completa de todos modos, pero el error aparece en los logs. Esto me permite observar el comportamiento en el mundo real antes de hacer que la comprobación bloquee el pipeline.
Es una prueba de humo (smoke test), no una suite de validación completa. Comprueba dos muestras por sitio. No detectará todos los casos límite, pero detecta los errores grandes antes de que permanezcan en producción durante un mes.