Visualizador de JSON-LD e verificador de dados estruturados

O que é JSON-LD e por que é um grafo

JSON-LD são dados estruturados escritos como JSON dentro de uma tag <script type="application/ld+json">. Ele descreve a página no vocabulário schema.org (isto é um Product chamado Blue Mug, custa 24 USD, é vendido por esta Organization) para que mecanismos de busca e assistentes de IA não precisem adivinhar pelo layout. O Google lê JSON-LD, Microdata e RDFa, e recomenda JSON-LD.

Todo objeto tem um @type. Também pode ter um @id, um identificador que geralmente é a URL da página mais um fragmento, como https://example.com/#organization. Qualquer outro objeto pode então apontar para ele por esse @id em vez de repeti-lo. É assim que uma página diz: esta WebPage pertence a este WebSite, o WebSite é publicado por esta Organization, e o Product da página é feito pela mesma Organization.

Quando as referências se alinham, a página descreve um conjunto conectado de fatos. Quando uma não se alinha, por um erro de digitação em um @id ou um ponteiro para uma Organization que só a página inicial imprime, cada bloco ainda é interpretado e a conexão se perde em silêncio. Uma lista de propriedades não mostra isso. Um grafo mostra: a entidade que deveria estar conectada fica sozinha, ou uma seta termina em um cartão tracejado.

Como ler o grafo

• Cada cartão é uma entidade. Os rótulos coloridos são o @type dela. Abaixo está o nome (ou headline, title ou URL) e até quatro das propriedades em texto simples.
• Uma seta vai da entidade que tem a propriedade até a entidade para a qual ela aponta, rotulada com o nome da propriedade: offers, brand, publisher, author, isPartOf.
• Entidades para as quais nada aponta ficam na coluna da esquerda. Cada coluna à direita é um passo mais adiante.
• Um cartão tracejado marcado como “Referenciado, nunca definido” é um @id para o qual algo aponta, mas que nada nesta página descreve.
• Objetos que compartilham um @id são unidos em um cartão, mesmo quando estão em blocos script separados. Se você esperava dois cartões e vê um, eles compartilham um @id.
• Somente JSON-LD é lido, não Microdata nem RDFa. Grafos muito grandes mostram as primeiras 150 entidades. Baixar PNG salva o grafo em fundo branco, pronto para um ticket ou um relatório de cliente.

O que a pontuação e os problemas significam

A pontuação vai de 0 a 100 e pesa seis coisas: se o JSON-LD está bem formado (20%), se as propriedades que o Google exige para um resultado avançado estão presentes (30%), se os valores têm o formato certo (20%), propriedades recomendadas (15%), se as referências @id resolvem (10%) e pequenas boas práticas (5%). Uma página sem JSON-LD recebe 0.

Os problemas são listados com os erros primeiro. Cada um começa com um caminho como Product.offers.price, que você pode buscar no seu modelo. Estas são as mensagens que você verá e o que fazer com cada uma:

o bloco não é JSON válido

Um erro de sintaxe, então o bloco inteiro é ignorado. As causas usuais são uma vírgula sobrando, aspas duplas sem escape dentro de uma string ou uma variável de modelo que não imprimiu nada. Passe o bloco por um analisador de JSON e corrija a linha indicada.

@context está ausente

Sem @context, os nomes das propriedades não significam nada. Adicione "@context": "https://schema.org" a cada objeto de nível superior. Se o seu disser http://schema.org, isso ainda funciona; https é a forma preferida, então aparece só como um aviso.

o nó não tem @type

Um objeto com propriedades, mas sem tipo, não pode ser interpretado. Adicione o @type que diz o que ele é, como Offer, Person ou PostalAddress.

… exige …; sem isso o resultado avançado não é elegível

O Google lista essa propriedade como obrigatória para o resultado avançado do tipo. Um Event precisa de name, startDate e location; um BreadcrumbList precisa de itemListElement. Adicione, usando o valor real mostrado na página.

… deveria incluir …

Uma propriedade recomendada está ausente. A marcação continua elegível sem ela, mas o resultado pode mostrar menos. Adicione somente se for verdade: não invente uma avaliação ou uma contagem de avaliações para limpar um aviso.

esperava um número / uma URL http(s) absoluta / uma data ISO 8601 / um objeto aninhado com um @type

O valor tem o formato errado. Um preço de "$24.00" deve ser 24.00, com a moeda em priceCurrency. Uma data como "Sept 3, 2026" deve ser "2026-09-03". Um caminho de imagem como /img/mug.jpg deve ser a URL completa. Um author dado como texto simples deve ser um objeto Person ou Organization com um name. Valores de uma lista fixa, como availability, precisam ser um dos listados, como https://schema.org/InStock.

… contém …, esperava …

O objeto aninhado tem o tipo errado, como um address que contém um Person. Mude o @type para o que a mensagem indica.

as posições … precisam ir de 1..n sem lacunas / cada migalha, exceto a última, precisa de um item

Em um BreadcrumbList, position precisa contar 1, 2, 3 sem lacunas, e cada migalha, exceto a última (a página atual), precisa de um item com a URL dessa migalha.

@id "…" é referenciado, mas nunca definido nesta página

Este é o cartão tracejado no grafo: algo aponta para um @id que nada nesta página descreve. Geralmente é um erro de digitação (#org em vez de #organization, http em vez de https, uma barra final ausente) ou a entidade só é impressa em outra página, muitas vezes a Organization da página inicial. Uma referência não é um link, e nada vai buscá-la, então corrija a grafia ou também imprima a entidade nesta página.

… entidades separadas sem referências cruzadas de @id entre elas

Várias entidades de nível superior que nunca apontam umas para as outras. Isso é válido, mas elas são lidas como fatos sem relação. Dê a cada uma um @id e conecte-as: o isPartOf da WebPage ao WebSite, o publisher de um Article à Organization.

… não tem um resultado avançado que possamos verificar

Não temos regras para esse tipo. Não é um erro: a entidade ainda aparece no grafo, e tudo aninhado dentro dela ainda é verificado.

Um exemplo comentado

Uma página de produto imprime uma Organization, uma WebPage e um Product em um @graph. Cada parte é interpretada e, à primeira vista, parece certo:

{
  "@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"
      }
    }
  ]
}

O grafo mostra o que o código esconde. A Organization fica sozinha na coluna da esquerda, sem nada apontando para ela, e a seta brand do Product termina em um cartão tracejado de https://example.com/#org. A lista de problemas diz o mesmo, com caminhos:

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

A correção são duas linhas: aponte brand para o @id que a Organization de fato usa e tire o símbolo da moeda do preço.

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

A pontuação vai de 79 para 94 e a Organization agora está conectada ao Product. Os quatro avisos restantes pedem sameAs, sku, aggregateRating e a url da oferta. Adicione os que forem verdadeiros para a loja; um produto sem avaliações não deveria ter uma nota.

Perguntas