Como o JSON-LD Ajuda a IA a Compreender o Seu Website

Jun 3, 2026 · 8 min read

Como o JSON-LD Ajuda a IA a Compreender o Seu Website

O JSON-LD é um formato baseado em <script> para incorporar o vocabulário do Schema.org como metadados estruturados e legíveis por máquina no seu HTML. Permite que motores de busca e sistemas de IA identifiquem entidades — artigos, organizações, produtos, breadcrumbs, pessoas — sem precisar de as inferir a partir do texto. Para o Google Search, um JSON-LD correto torna as páginas elegíveis para funcionalidades específicas de pesquisa e ajuda a popular o Knowledge Graph. Para crawlers de IA como o GPTBot, o ClaudeBot e o PerplexityBot, existe uma limitação técnica que os developers de frontend ignoram sistematicamente: estes crawlers não executam JavaScript, pelo que o JSON-LD tem de estar presente na resposta do servidor para que chegue até eles.

Este artigo aborda o que o JSON-LD realmente faz, onde ajuda e onde não ajuda, três exemplos funcionais que pode adaptar, o problema de renderização que invalida o markup injetado pelo cliente para crawlers de IA, e como validar o que coloca em produção.

Pontos-Chave

O JSON-LD é o formato de dados estruturados recomendado pelo Google e utiliza o vocabulário do Schema.org para descrever entidades e as suas relações de forma legível por máquina.
Os crawlers de IA, incluindo o GPTBot, o ClaudeBot e o PerplexityBot, não executam JavaScript — o JSON-LD injetado via useEffect, Google Tag Manager ou qualquer caminho client-side é invisível para eles.
Os AI Overviews e o AI Mode não requerem markup específico para IA; aplicam-se os mesmos critérios de elegibilidade do Google Search regular, e os dados estruturados ajudam na interpretação, mas não garantem inclusão.
O Google deixou de apresentar rich results de FAQ em maio de 2026, com o suporte no Search Console e no Rich Results Test a ser removido em junho de 2026; o FAQPage continua a ser um tipo válido do Schema.org, mas deixou de ser uma tática de crescimento através de rich results.
Para validação a longo prazo, o validator.schema.org é a opção mais segura por defeito — verifica o vocabulário completo do Schema.org, enquanto o Google Rich Results Test cobre apenas as funcionalidades suportadas pelo Google.

O que é o JSON-LD e por que existe

O JSON-LD (JavaScript Object Notation for Linked Data) é uma sintaxe padronizada pelo W3C para expressar Linked Data em JSON. Na web, é quase sempre utilizado para incorporar o vocabulário do Schema.org dentro de uma tag <script type="application/ld+json"> no documento. Os dados descrevem as entidades da página — sobre o que trata, quem a escreveu, que organização a publicou, como se relaciona com outras páginas — numa forma que um parser pode consumir sem precisar de ler o texto.

O “porquê” está no custo interpretativo. Sem dados estruturados, um crawler tem de inferir que “Apple” numa página se refere à empresa e não à fruta; que o nome “Jane Chen” no byline é a autora e não um sujeito; que um preço no markup pertence ao produto da página e não a um item relacionado numa barra lateral. O Schema.org fornece a esses factos tipos e propriedades explícitos. O JSON-LD entrega-os num bloco desacoplado do DOM visível, razão pela qual o Google o recomenda em detrimento do Microdata e do RDFa — pode gerá-lo e atualizá-lo sem tocar no layout.

Algumas afirmações que merecem precisão: o JSON-LD não é um fator de ranking confirmado nos sistemas de ranking documentados do Google. Não garante rich results — a elegibilidade é necessária, mas não suficiente. Não garante inclusão nos AI Overviews ou no AI Mode. E os sistemas de IA não requerem JSON-LD; conseguem ler texto. O que o JSON-LD faz é reduzir o trabalho inferencial, o que torna a interpretação correta mais provável e o conteúdo ambíguo menos suscetível de ser classificado incorretamente.

Como o JSON-LD se integra nos AI Overviews e no AI Mode

Os AI Overviews e o AI Mode operam sobre o índice de pesquisa existente do Google. A orientação publicada pelo Google é que não existe markup específico para IA — as páginas tornam-se elegíveis para funcionalidades de IA através dos mesmos sinais de conteúdo e dados estruturados que regem o Search regular. Se a sua página estiver corretamente indexada, estruturada e corresponder à intenção do utilizador, os dados estruturados que disponibiliza para o Search são os mesmos dados que essas funcionalidades utilizam.

A perspetiva honesta: os dados estruturados ajudam os sistemas de IA a interpretar corretamente o seu conteúdo. Não garantem inclusão em respostas geradas. Trate-os como uma forma de eliminar ambiguidade, não como uma alavanca de crescimento.

O problema de renderização para crawlers de IA

Este é o ponto técnico de maior impacto para developers de frontend, e está ausente da maioria dos artigos sobre JSON-LD: os crawlers de IA devem geralmente ser tratados como crawlers sem renderização, pelo que os dados estruturados devem estar presentes na resposta HTML inicial.

O GPTBot da OpenAI obtém o HTML e não renderiza JavaScript client-side.
O ClaudeBot da Anthropic funciona como um crawler HTTP padrão, sem execução de JS.
O PerplexityBot lê igualmente o HTML em bruto.

O Googlebot é a exceção: renderiza geralmente JavaScript numa passagem diferida, pelo que o JSON-LD injetado pelo cliente será eventualmente processado para o Search. Os crawlers de IA não farão o mesmo. Se o seu JSON-LD só existir após a hidratação, é invisível para os sistemas sobre os quais a maioria dos leitores pergunta atualmente.

Um padrão de falha comum em aplicações frontend reais: um developer adiciona JSON-LD dentro de um hook useEffect, ou envia-o via Google Tag Manager. O bloco aparece no DOM renderizado, o Rich Results Test (que renderiza) mostra-o como válido, e a equipa assume que o trabalho está feito. Entretanto, todos os crawlers sem renderização recebem uma resposta HTML sem qualquer dado estruturado.

A solução é colocar o bloco <script type="application/ld+json"> na resposta inicial do servidor.

Server-rendering de JSON-LD por framework

Framework	Onde colocar o JSON-LD
Next.js App Router	`<script type="application/ld+json">` inline num Server Component, ou no campo `other` da Metadata API
Next.js Pages Router	`<script>` inline dentro de `<Head>` do `next/head`, renderizado nas paths de `getServerSideProps`/`getStaticProps`
Nuxt 3	`useHead` com uma entrada `script`, chamado num contexto de servidor
Astro	`<script type="application/ld+json">` inline diretamente no template `.astro` (estático por defeito, sem execução de JS necessária)
SvelteKit	Bloco `<svelte:head>` contendo o script, renderizado server-side

O princípio é idêntico em todas as stacks: o bloco JSON-LD tem de existir nos bytes que chegam do servidor, não nos bytes adicionados pelo browser após o primeiro paint.

Três exemplos funcionais de JSON-LD

Os exemplos abaixo utilizam o vocabulário do Schema.org na versão 30.0, lançada a 19 de março de 2026.

BlogPosting (um subtipo de Article)

Na hierarquia do Schema.org, BlogPosting é um subtipo de Article, que é por sua vez um subtipo de CreativeWork. Declarar "@type": "BlogPosting" herda implicitamente todas as propriedades de Article — não é necessário declarar ambos.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "@id": "https://openreplay.com/blog/json-ld-ai-search#article",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://openreplay.com/blog/json-ld-ai-search"
  },
  "headline": "How JSON-LD Helps AI Understand Your Website",
  "description": "A frontend-focused guide to JSON-LD, Schema.org, and the server-rendering requirement for AI crawlers.",
  "image": "https://openreplay.com/images/blog/json-ld-ai-search.png",
  "datePublished": "2026-05-20T09:00:00-04:00",
  "dateModified": "2026-05-20T09:00:00-04:00",
  "author": {
    "@type": "Organization",
    "name": "OpenReplay Team",
    "url": "https://openreplay.com"
  },
  "publisher": {
    "@id": "https://openreplay.com/#organization"
  }
}
</script>

Utilize este tipo em páginas de artigos de formato longo. mainEntityOfPage associa o artigo ao seu URL canónico; dateModified é relevante porque o Google utiliza-o quando a atualidade é um sinal de pesquisa.

Organization

O tipo Organization descreve a entidade publicadora. Utilize sameAs para apontar para perfis externos canónicos — é assim que os sistemas distinguem a sua marca de outras com nomes semelhantes.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://openreplay.com/#organization",
  "name": "OpenReplay",
  "url": "https://openreplay.com",
  "logo": {
    "@type": "ImageObject",
    "url": "https://openreplay.com/images/logo.png",
    "width": 512,
    "height": 512
  },
  "sameAs": [
    "https://github.com/openreplay",
    "https://www.linkedin.com/company/openreplay",
    "https://x.com/OpenReplayHQ"
  ]
}
</script>

Inclua este bloco uma vez, em todo o site — tipicamente no head do documento de todas as páginas. Reutilize o @id noutros blocos de schema (como BlogPosting.publisher faz acima) para que uma única definição canónica de Organization seja referenciada em todo o lado, em vez de duplicada.

BreadcrumbList

O BreadcrumbList descreve a posição da página na hierarquia do site. O Google suporta rich results de breadcrumb, e os mesmos dados ajudam os sistemas de IA a compreender a estrutura do site.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://openreplay.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog",
      "item": "https://openreplay.com/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "How JSON-LD Helps AI Understand Your Website"
    }
  ]
}
</script>

O último item omite item porque é a página atual. position é indexado a partir de 1.

Manter os dados estruturados alinhados com o conteúdo visível

As diretrizes de dados estruturados do Google são explícitas: o conteúdo no JSON-LD tem de corresponder ao que está na página. Marcar reviews que não existem na página, preços que não aparecem, ou nomes de autores que contradizem os bylines visíveis representa um risco de ação manual. Os dados estruturados destinam-se a descrever a página, não a enriquecê-la com afirmações que não estão fundamentadas no DOM.

Isto também é relevante para os sistemas de IA. Se o seu texto visível diz uma coisa e o seu JSON-LD diz outra, criou exatamente a ambiguidade que os dados estruturados deveriam resolver.

Validar antes de colocar em produção

Dois ferramentas cobrem o fluxo de trabalho:

Ferramenta	Verifica	Melhor para
Google Rich Results Test	Elegibilidade para os tipos de rich results suportados pelo Google	Verificação pré-deployment para Article, Product, Breadcrumb, etc.
Schema Markup Validator	Conformidade com o vocabulário completo do Schema.org	Validação geral; qualquer tipo que o Google não apresente como rich result

O Rich Results Test renderiza a página (pelo que vê o JSON-LD injetado pelo cliente que os crawlers de IA não verão). Para confirmar o que os crawlers sem renderização recebem, execute curl -A "GPTBot" https://your-page no seu URL e procure application/ld+json na resposta. Se o bloco não estiver nesse HTML em bruto, os crawlers de IA não o verão.

A secção Enhancements do Google Search Console reporta erros de parsing e elegibilidade para os tipos de dados estruturados que o Google monitoriza. Utilize-o para monitorização contínua, não como substituto da validação pré-deployment.

Uma nota sobre o FAQPage

O FAQPage continua a ser um tipo válido do Schema.org e o Google continua a utilizá-lo para compreensão de conteúdo. No entanto, o Google indica na sua documentação do FAQPage que as funcionalidades de Search relacionadas com FAQ estão a ser removidas: os rich results de FAQ deixaram de aparecer no Search em maio de 2026; os relatórios no Search Console e o suporte no Rich Results Test estão a ser removidos em junho de 2026; o suporte à API do Search Console segue-se em agosto de 2026. Se está a escolher schema para implementar agora com vista a ganhos visíveis em rich results, o FAQPage não é a resposta. Implemente-o se tiver uma página de FAQ genuína e quiser registar a semântica — não como uma estratégia para ocupar mais espaço nas SERPs.

É também por isso que o validator.schema.org é a opção mais segura por defeito para trabalho de validação a longo prazo: não depende das funcionalidades que o Google escolhe apresentar como rich results.

O que implementar primeiro

Se está a começar do zero, a sequência de maior valor é: um único bloco Organization em todo o site, BreadcrumbList em todas as páginas que não sejam a homepage, e Article/BlogPosting em conteúdo editorial. Faça server-render de tudo. Valide com ambas as ferramentas. Depois verifique a resposta HTML em bruto com um user agent sem renderização para confirmar que os crawlers de IA recebem efetivamente o que escreveu.

Os dados estruturados não vão mover rankings por si só e não garantem inclusão nos AI Overviews. O que fazem — de forma consistente, quando implementados corretamente — é eliminar as suposições interpretativas que levam os motores de busca e os sistemas de IA a compreender mal o seu conteúdo. Para equipas de frontend, o trabalho que mais importa não é quais os tipos de schema a adicionar, mas onde no pipeline de renderização eles residem. Coloque o JSON-LD na resposta do servidor, e o resto é uma questão de conteúdo.

FAQs

Use JSON-LD. O Google recomenda-o explicitamente em detrimento do Microdata e do RDFa porque reside num único bloco de script desacoplado do DOM visível, o que significa que pode gerar e atualizar dados estruturados sem tocar no markup de layout. Os três formatos conseguem expressar o vocabulário do Schema.org e são analisados pelo Google, mas o JSON-LD é mais fácil de manter, mais fácil de fazer server-render, e é o formato que o Google utiliza nos seus próprios exemplos ao longo da documentação de dados estruturados.

Sim. O Google suporta múltiplas tags script separadas numa única página, que é o padrão habitual para combinar tipos como Organization, BreadcrumbList e BlogPosting. A alternativa é um único script contendo um array de grafo sob a chave @graph, onde cada entidade tem o seu próprio @id. Ambas as abordagens são válidas; o padrão @graph é mais limpo quando as entidades se referenciam mutuamente via @id, uma vez que mantém uma única definição canónica por entidade.

Apenas se o JSON-LD estiver na resposta inicial do servidor. As SPAs que injetam dados estruturados após a hidratação são invisíveis para crawlers sem renderização como o GPTBot, o ClaudeBot e o PerplexityBot. A solução é o server-side rendering ou a geração estática para páginas que precisam de dados estruturados — utilizando Next.js, Nuxt, Astro ou SvelteKit nos seus modos SSR ou SSG — para que a tag script exista nos bytes HTML antes de qualquer JavaScript ser executado.

Atualize dateModified apenas quando o conteúdo substantivo do artigo muda — correções, novas secções, factos atualizados, exemplos renovados. Não o atualize em cada deploy ou para edições cosméticas como correções de erros tipográficos ou ajustes de estilo. O Google utiliza dateModified como sinal de atualidade para pesquisas sensíveis ao tempo, e inflacioná-lo sem alterações reais de conteúdo contradiz a regra de que os dados estruturados devem corresponder ao conteúdo visível, o que representa um risco de ação manual.

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.