Visor de JSON-LD y comprobador de datos estructurados

Qué es JSON-LD y por qué es un grafo

JSON-LD son datos estructurados escritos como JSON dentro de una etiqueta <script type="application/ld+json">. Describe la página con el vocabulario de schema.org (esto es un Product llamado Blue Mug, cuesta 24 USD, lo vende esta Organization) para que los buscadores y los asistentes de IA no tengan que adivinarlo a partir del diseño. Google lee JSON-LD, Microdata y RDFa, y recomienda JSON-LD.

Cada objeto tiene un @type. También puede tener un @id, un identificador que suele ser la URL de la página más un fragmento, como https://example.com/#organization. Cualquier otro objeto puede apuntar a él con ese @id en lugar de repetirlo. Así es como una página dice: esta WebPage pertenece a este WebSite, el WebSite lo publica esta Organization y el Product de la página lo fabrica la misma Organization.

Cuando las referencias coinciden, la página describe un conjunto de hechos conectado. Cuando una no coincide, por un error en un @id o un puntero a una Organization que solo imprime la página de inicio, cada bloque sigue siendo válido y la conexión se pierde en silencio. Una lista de propiedades no te muestra eso. Un grafo sí: la entidad que debería estar conectada queda sola, o una flecha termina en una tarjeta discontinua.

Cómo leer el grafo

• Cada tarjeta es una entidad. Las etiquetas de color son su @type. Debajo está su nombre (o headline, title o URL) y hasta cuatro de sus propiedades de texto.
• Una flecha va de la entidad que tiene la propiedad a la entidad a la que apunta, etiquetada con el nombre de la propiedad: offers, brand, publisher, author, isPartOf.
• Las entidades a las que no apunta nada están en la columna izquierda. Cada columna a la derecha es un paso más abajo.
• Una tarjeta discontinua marcada como “Referenciado, nunca definido” es un @id al que algo apunta, pero que nada en la página describe.
• Los objetos que comparten un @id se fusionan en una tarjeta, aunque estén en bloques script distintos. Si esperabas dos tarjetas y ves una, comparten un @id.
• Solo se lee JSON-LD, no Microdata ni RDFa. Los grafos muy grandes muestran sus primeras 150 entidades. Descargar PNG guarda el grafo sobre fondo blanco, listo para un ticket o un informe para el cliente.

Qué significan la puntuación y los problemas

La puntuación va de 0 a 100 y pondera seis cosas: si el JSON-LD está bien formado (20%), si están las propiedades que Google exige para un resultado enriquecido (30%), si los valores tienen el formato correcto (20%), las propiedades recomendadas (15%), si las referencias @id se resuelven (10%) y las buenas prácticas menores (5%). Una página sin JSON-LD puntúa 0.

Los problemas se listan con los errores primero. Cada uno empieza con una ruta como Product.offers.price que puedes buscar en tu plantilla. Estos son los mensajes que verás y qué hacer con cada uno:

el bloque no es JSON válido

Un error de sintaxis, así que se ignora todo el bloque. Las causas habituales son una coma final, una comilla doble sin escapar dentro de una cadena o una variable de plantilla que no imprimió nada. Pasa el bloque por un analizador de JSON y corrige la línea que señala.

falta @context

Sin @context, los nombres de las propiedades no significan nada. Añade "@context": "https://schema.org" a cada objeto de nivel superior. Si el tuyo dice http://schema.org, también funciona; https es la forma preferida, así que solo se muestra como aviso.

el nodo no tiene @type

Un objeto con propiedades pero sin tipo no se puede interpretar. Añade el @type que dice qué es, como Offer, Person o PostalAddress.

… exige …; sin ello el resultado enriquecido no es apto

Google indica esa propiedad como obligatoria para el resultado enriquecido del tipo. Un Event necesita name, startDate y location; un BreadcrumbList necesita itemListElement. Añádela, con el valor real que se muestra en la página.

… debería incluir …

Falta una propiedad recomendada. El marcado sigue siendo apto sin ella, pero el resultado puede mostrar menos. Añádela solo si es cierta: no inventes una valoración ni un número de reseñas para quitar un aviso.

se esperaba un número / una URL http(s) absoluta / una fecha ISO 8601 / un objeto anidado con un @type

El valor tiene la forma incorrecta. Un precio de "$24.00" debería ser 24.00, con la moneda en priceCurrency. Una fecha como "Sept 3, 2026" debería ser "2026-09-03". Una ruta de imagen como /img/mug.jpg debería ser la URL completa. Un autor dado como texto plano debería ser un objeto Person u Organization con un name. Los valores de una lista fija, como availability, deben ser uno de los indicados, como https://schema.org/InStock.

… contiene …, se esperaba …

El objeto anidado tiene el tipo incorrecto, como una dirección que contiene un Person. Cambia su @type al que nombra el mensaje.

las posiciones … deben ir de 1..n sin huecos / cada miga salvo la última necesita un item

En un BreadcrumbList, position debe contar 1, 2, 3 sin huecos, y cada miga salvo la última (la página actual) necesita un item con la URL de esa miga.

@id "…" se referencia pero nunca se define en esta página

Es la tarjeta discontinua del grafo: algo apunta a un @id que nada en esta página describe. Suele ser un error de escritura (#org en lugar de #organization, http en lugar de https, una barra final que falta) o la entidad solo se imprime en otra página, a menudo la Organization de la página de inicio. Una referencia no es un enlace y nada va a buscarla, así que corrige la escritura o incluye también la entidad en esta página.

… entidades separadas sin referencias cruzadas de @id entre ellas

Varias entidades de nivel superior que nunca se apuntan entre sí. Es válido, pero se leen como hechos sin relación. Dale a cada una un @id y conéctalas: el isPartOf de la WebPage al WebSite, el publisher de un Article a la Organization.

… no tiene un resultado enriquecido que podamos comprobar

No tenemos reglas para ese tipo. No es un error: la entidad sigue apareciendo en el grafo y todo lo anidado dentro de ella se sigue comprobando.

Un ejemplo resuelto

Una página de producto imprime una Organization, una WebPage y un Product en un @graph. Cada parte es válida y, a simple vista, parece correcta:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Coffee Co.",
      "url": "https://example.com/",
      "logo": "https://example.com/logo.png"
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/products/blue-mug#webpage",
      "name": "Blue Mug",
      "url": "https://example.com/products/blue-mug"
    },
    {
      "@type": "Product",
      "@id": "https://example.com/products/blue-mug#product",
      "name": "Blue Mug",
      "image": "https://example.com/img/blue-mug.jpg",
      "mainEntityOfPage": { "@id": "https://example.com/products/blue-mug#webpage" },
      "brand": { "@id": "https://example.com/#org" },
      "offers": {
        "@type": "Offer",
        "price": "$24.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/InStock"
      }
    }
  ]
}

El grafo muestra lo que el código esconde. La Organization queda sola en la columna izquierda, sin que nada apunte a ella, y la flecha brand del Product termina en una tarjeta discontinua de https://example.com/#org. La lista de problemas dice lo mismo, con rutas:

error  Product.offers.price
       price on Offer: expected a number, got the bare text "$24.00"
error  Product.brand
       @id "https://example.com/#org" is referenced but never defined on this page

La corrección son dos líneas: apunta brand al @id que usa de verdad la Organization y quita el símbolo de moneda del precio.

"brand": { "@id": "https://example.com/#organization" },
…
  "price": 24.00,

La puntuación pasa de 79 a 94 y la Organization queda conectada al Product. Los cuatro avisos que quedan piden sameAs, sku, aggregateRating y la url de la oferta. Añade los que sean ciertos para la tienda; un producto sin reseñas no debería llevar una valoración.

Preguntas