Nuestra herramienta no leía @graph y nos puso 0 en schema

Corrí Entiscore contra nuestro propio sitio y el reporte dijo que no teníamos ningún dato estructurado. Ese JSON-LD lo habíamos escrito a mano con Matías semanas antes, estaba en el <head> del documento y bastaba abrir el código fuente en el navegador para verlo.

Entiscore es la herramienta que construimos para auditar justamente eso en sitios ajenos. Durante semanas la probamos contra portfolios de otras personas, sitios de prueba y ejemplos armados para estresar cada parte del análisis, pero nunca la habíamos apuntado a nuestro dominio en producción. Lo hicimos sobre el final, casi por disciplina, y devolvió 52 sobre 100. El fallo no estaba en nuestro sitio sino en lo que la herramienta era capaz de leer, y encontrarlo cambió la forma en que pruebo mis propios proyectos.

Entiscore es un agente de auditoría de identidad digital que construimos con Matías Tula Sarquis para el hackathon de Kiro powered by AWS. Recibe una URL y estima qué tan reconocible es esa entidad para buscadores y para sistemas de inteligencia artificial, a partir de cuatro ejes que son datos estructurados, accesibilidad técnica, consistencia de identidad y señales de autoridad.

Todo el proyecto lo desarrollamos con Kiro como agente, siguiendo el flujo guiado por especificaciones que propone, con requisitos, diseño y tareas escritos antes de cualquier implementación. Kiro es el entorno de desarrollo con agentes de AWS, y el analizador de datos estructurados que falló en este caso se construyó dentro de ese mismo proceso.

La accesibilidad técnica estaba en 100. La consistencia de identidad daba 60 porque el analizador confirmaba el GitHub del proyecto pero no tenía más puntos de anclaje para cruzar. Las señales de autoridad daban 52, con un hallazgo sobre el meta tag de autor, que mostraba un solo nombre aunque el proyecto es de dos personas.

Lo que no encajaba era el 0 en datos estructurados junto a un hallazgo crítico que afirmaba algo falso. Sabíamos que era falso porque ese schema lo habíamos escrito nosotros.

Antes de dudar de la herramienta dudamos de nosotros. Si el schema era mínimo, lo razonable era ampliarlo. Agregamos un tipo Organization junto al WebApplication que ya existía, declaramos a los dos integrantes como creadores, corregimos un enlace a GitHub que apuntaba a una URL vieja y ajustamos los metadatos de autor. Desplegamos, esperamos a confirmar que el deploy había terminado y volvimos a correr el análisis.

El resultado seguía en 0, con el mismo hallazgo crítico.

Un schema mínimo y uno bastante más completo producían exactamente el mismo puntaje. Si el tamaño del schema no cambia el resultado, lo más probable es que quien mide no esté leyendo el schema en absoluto.

Si cambiás algo en tu sitio y la herramienta que lo mide devuelve exactamente lo mismo, ¿qué sospechás primero, tu cambio o el instrumento? A nosotros nos hizo falta un deploy completo para empezar a mirar hacia la herramienta.

Dejamos de mirar el código de los componentes y revisamos el HTML final, el mismo que recibiría un crawler. El JSON-LD usaba @graph, que es la forma que ofrece el formato para describir varias entidades relacionadas dentro de un mismo documento. Según la especificación JSON-LD 1.1 del W3C , un objeto de nivel superior que solo contiene @context y @graph no se trata como una entidad sino como un contenedor de las entidades que lleva dentro.

El origen estaba en la función del analizador que extraía los schemas, que buscaba @type directamente en la raíz del objeto.

Con @graph, la raíz solo tiene @context y @graph. La condición fallaba, la función devolvía un arreglo vacío y el analizador concluía, sin lanzar ningún error, que el sitio no tenía schema. No había un crash que rastrear en un log. Había un hueco de cobertura, porque el código hacía exactamente lo que habíamos escrito y lo que habíamos escrito no contemplaba una forma válida del propio estándar que se suponía que debía interpretar.

Mientras diagnosticábamos aparecieron otras dos. La lista de tipos reconocidos no incluía SoftwareApplication con sus campos esperados, así que aunque la extracción hubiera funcionado, el analizador no habría sabido evaluar si esa entidad estaba completa, algo que sí hacía con Person y Organization.

La otra estaba en las señales de autoridad. En el HTML habíamos declarado un meta tag de autor por cada integrante.

Un document.querySelector sobre ese selector devuelve solo la primera coincidencia, así que el analizador leía un único nombre. La información estaba completa en el HTML, pero declarada de una forma que nuestra herramienta no sabía leer.

Reemplazamos la extracción por una versión recursiva que recorre el árbol y trata @graph como lo que es, un contenedor de entidades.

Agregamos SoftwareApplication a los tipos reconocidos, con sus campos esperados definidos igual que los de Person y Organization, y consolidamos los dos meta tags de autor en uno solo.

Volvimos a correr el análisis contra el mismo dominio y esta vez el resultado se parecía a lo que sabíamos de nuestro proyecto.

El puntaje general pasó de 52 a 80 y el nivel de madurez de "medio" a "excelente". Datos estructurados subió de 0 a 92 y ahora señala algo legítimo y específico, que a la Organization le falta contactPoint. Ese hallazgo antes era imposible de ver, porque el analizador no llegaba siquiera a leer el schema.

Las señales de autoridad siguieron en 52 aunque el meta tag ya mostraba los dos nombres, que fue el resultado que menos esperábamos. Ese eje combina varias señales, y consolidar una etiqueta resolvió el hallazgo puntual pero no alcanza para mover el puntaje completo. Lo que le falta es presencia pública verificable fuera del GitHub ya detectado, y eso no se arregla con markup.

Un resultado que no responde a ningún cambio que hacés puede estar hablando del instrumento y no de lo que medís. La señal que nos puso en el camino correcto no fue que el arreglo resultara insuficiente, sino que un schema chico y uno completo dieran exactamente el mismo número.

El bug también sobrevivió a semanas de pruebas porque nuestros ejemplos esperaban lo que ya imaginábamos encontrar, y no todo lo que el estándar permite. Lo encontró el único sitio del que sabíamos con certeza qué debía aparecer, el nuestro. La conclusión práctica es probar las herramientas contra el propio trabajo, esperando que el resultado se parezca a lo que ya sabemos de él.

Quedan pendientes el campo contactPoint y el eje de autoridad, que nos obliga a construir presencia pública verificable y no solo mejores etiquetas.

¿Tu sitio declara sus entidades con @graph? Si alguna herramienta de SEO o de IA te dijo alguna vez que no tenías datos estructurados y vos sabías que sí, me gustaría saber cuál fue y cómo lo descubriste. Te leo!