JSON-LD para SEO

TL;DR — JSON-LD é um pequeno bloco de código que você adiciona a uma página para explicar sobre o que ela é — que é um artigo, um produto, uma receita — em um formato que mecanismos de busca e sistemas de IA leem facilmente. Ele fica em sua própria tag <script> e nunca muda nada que os visitantes veem. O Google o recomenda em vez dos outros dois formatos porque é o mais fácil de adicionar e manter organizado. Ele não fará você ranquear melhor, mas pode tornar seus resultados mais ricos (estrelas, preços, FAQs).

O que é JSON-LD

Quando você publica uma página, um humano pode lê-la e descobrir “ah, isso é uma receita para pão de banana.” Um mecanismo de busca tem que adivinhar isso a partir das palavras. Dados estruturados é como você para de adivinhar — você rotula a página em código legível por máquina para que os mecanismos saibam que é uma receita, quem é o autor, qual é a avaliação.

JSON-LD é a forma mais popular de escrever esse rótulo. O nome significa Notação de Objetos JavaScript para Dados Vinculados. Evidence for this claim JSON-LD is a structured-data format that can express Schema.org types and properties in a script block. Scope: Schema.org JSON-LD guidance; JSON-LD is a format, not the vocabulary itself. Confidence: high · Verified: 2026-07-14 Schema.org: JSON-LD Você não precisa saber o que isso significa para usá-lo. Na prática, JSON-LD é um pedaço de código que parece uma lista de fatos rotulados, dentro de uma tag <script>:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How to Bake Banana Bread",
  "author": { "@type": "Person", "name": "Patrick Stox" },
  "datePublished": "2026-06-26"
}
</script>

O ponto principal: esse bloco vive separadamente das palavras na sua página. Ele não muda nada do que seus visitantes veem. É apenas instruções para os robôs.

Por que o Google gosta dele

Na verdade, existem três maneiras de escrever dados estruturados — JSON-LD, Microdata, e RDFa. Os outros dois funcionam espalhando código extra dentro do seu HTML visível, embaralhado com seus títulos e parágrafos. JSON-LD mantém tudo em uma caixa organizada.

É por isso que o Google recomenda JSON-LD: é o mais fácil de adicionar, o mais fácil de manter correto, e você tem muito menos probabilidade de quebrar algo. Nas palavras do Google: “the easiest solution for website owners to implement and maintain at scale.” (tradução) «a solução mais fácil para proprietários de sites implementarem e manterem em escala.» Todos os três formatos são bons — JSON-LD é apenas o menos propenso a erros.

O que ele realmente faz por você

Duas coisas honestas, e um mito:

• Ele pode tornar seu resultado de busca mais rico. Avaliações de receitas, preços de produtos, menus suspensos de FAQ, datas de eventos — esses “rich results” vêm de dados estruturados.
• Ele ajuda os mecanismos (e a IA) a entenderem seu conteúdo. Ele conecta sua página a coisas conhecidas — seu negócio, um autor, um produto.
• Ele não faz você ranquear melhor. Este é o mito. Adicionar JSON-LD não é um aumento de ranqueamento. O Google disse isso de forma clara e repetida.

A única regra que importa

Marque apenas o que está realmente na página. Não afirme uma avaliação de 5 estrelas no seu JSON-LD se nenhuma avaliação é mostrada aos visitantes. Não descreva um preço que não está lá. Os dados estruturados têm que corresponder à página visível — descrever coisas que não estão lá é contra as regras e pode fazer seus rich results serem removidos.

Quer a versão precisa — a sintaxe @context / @type / @id, o padrão @graph, a armadilha de injeção de JavaScript que esconde sua marcação dos rastreadores de IA, e como validá-la? Mude para a aba Avançado.

TL;DR — JSON-LD (Notação de Objetos JavaScript para Dados Vinculados) é uma Recomendação da W3C de 2014 — construída sobre JSON, mas @context é o que a torna dados vinculados, não apenas JSON. É o formato de dados estruturados que o Google recomenda porque é o mais fácil de implementar e manter em escala e nunca toca o HTML visível; Microdata e RDFa são igualmente válidos quando corretos. A espinha dorsal da sintaxe é @context (vocabulário — schema.org para a maioria das marcações de SEO, embora a especificação permita outros contextos), @type (entidade), @id (um URI estável útil, mas opcional, para referência cruzada de entidades — a base de @graph, em si um padrão válido entre outros, não um requisito). Coloque-o no <head> ou <body> — o Google aceita ambos. O Googlebot renderiza JS, então JSON-LD injetado dinamicamente funciona para Google; vários rastreadores de IA (GPTBot, ClaudeBot incluídos, conforme testado) não executam JS, mas isso é específico do provedor e da data — verifique diretamente em vez de assumir isso para cada rastreador de IA, e renderize no servidor o que você não puder confirmar. Dados estruturados não são um sinal de ranqueamento — eles impulsionam a elegibilidade para rich results e o entendimento de entidades, e devem descrever conteúdo visível na página.

JSON-LD é um formato, não um vocabulário

Primeiro, uma distinção que esclarece muita confusão: JSON-LD é o formato; schema.org é o vocabulário. JSON-LD é como você escreve a marcação; os tipos Article, Product, Organization do schema.org são o que você diz. Os rich results são a camada de recursos sobre ambos. Esta página é sobre o formato. (O ângulo de vocabulário para IA está em Schema Markup for AI.)

JSON-LD é uma Recomendação da W3C, publicada pela primeira vez em 2014 — ela precede sua adoção em SEO e foi projetada para interoperabilidade geral de dados vinculados na web, não especificamente para busca. Essa história é o motivo pelo qual uma propriedade como @id existe, e é o ponto de nível de especificação que a maioria dos guias de SEO ignora: JSON-LD não é apenas JSON. É construído sobre a sintaxe JSON, mas a declaração @context é o que torna os dados vinculados — identificáveis e conectáveis na web. Remova @context e você terá dados que um parser não consegue interpretar.

JSON-LD também não é casado com schema.org. A especificação permite que @context referencie qualquer vocabulário publicado — seus próprios exemplos vinculam a contextos não-schema.org — então JSON-LD é a resposta certa para “qual formato” enquanto schema.org é uma resposta, a comum para marcação de busca e busca por IA, para “qual vocabulário”. Uma página poderia validamente usar JSON-LD com um vocabulário diferente; só não seria mais marcação schema.org.

JSON-LD vs. Microdata vs. RDFa

Há três maneiras de expressar dados estruturados, e o Google suporta todas elas:

A recomendação do Google é explícita, mas de escopo restrito: “In general, Google recommends using JSON-LD for structured data if your site’s setup allows it, as it’s the easiest solution for website owners to implement and maintain at scale (in other words, less prone to user errors).” (tradução) «Em geral, o Google recomenda usar JSON-LD para dados estruturados se a configuração do seu site permitir, pois é a solução mais fácil para os proprietários de sites implementarem e manterem em escala (em outras palavras, menos propensa a erros do usuário).»

A nuance que os concorrentes geralmente ignoram — e que vale a pena manter — vem da mesma página do Google: “All 3 formats are equally fine for Google, as long as the markup is valid and properly implemented per the feature’s documentation.” (tradução) «Todos os 3 formatos são igualmente aceitáveis para o Google, desde que a marcação seja válida e implementada corretamente de acordo com a documentação do recurso.» Portanto, a recomendação é sobre facilidade de implementação e taxa de erro, não sobre velocidade de análise ou vantagem de ranqueamento. Usar Microdata não é uma penalidade. JSON-LD apenas vence na prática porque não entrelaça dados estruturados com a marcação que um designer pode editar amanhã.

A sintaxe: @context, @type, @id, propriedades, aninhamento

Aqui está um bloco Article anotado:

<script type="application/ld+json">
{
  "@context": "https://schema.org",          // the vocabulary — the common value for SEO
  "@type": "Article",                          // the entity type
  "@id": "https://example.com/post#article",   // a stable URI for this entity
  "headline": "How JSON-LD Works",            // a property (key/value)
  "datePublished": "2026-06-26",
  "author": {                                  // a nested entity
    "@type": "Person",
    "name": "Patrick Stox",
    "url": "https://patrickstox.com/"
  }
}
</script>

• @context — estabelece a estrutura semântica (o vocabulário). Para marcação SEO do schema.org, normalmente é "https://schema.org", mas isso é uma convenção, não uma regra: @context mapeia termos para identificadores, e a especificação permite que ele aponte para outros vocabulários. Ele informa ao analisador como interpretar cada nome de propriedade que se segue. Esta é a parte que o torna linked data.
• @type — declara a entidade: Article, Product, Organization, BreadcrumbList, etc. Ele mapeia para um tipo do schema.org. Use o tipo mais específico aplicável — NewsArticle em vez de Article se for adequado.
• @id — um URI único que identifica o recurso. É o mecanismo que permite referenciar uma entidade a partir de outra (veja @graph abaixo), e vale a pena defini-lo em qualquer coisa que você vá referenciar cruzadamente — mas não é universalmente obrigatório. A especificação JSON-LD permite nós em branco não identificados, então JSON-LD válido pode omitir @id em entidades que você nunca precise referenciar em outro lugar.
• Propriedades — pares comuns de chave/valor em JSON, usando termos de vocabulário do @context.
• Aninhamento — entidades filhas são expressas como objetos JSON aninhados (o objeto author acima) ou arrays de objetos.

O padrão @graph (a abordagem escalável)

A maioria das páginas precisa de mais de uma entidade: uma Organization, um WebSite, um BreadcrumbList e o próprio Article ou WebPage. A abordagem ingênua é usar quatro blocos <script> separados que repetem dados. Uma alternativa escalável é um único bloco com @graph — um array de entidades, referenciadas cruzadamente por @id. Nem a especificação JSON-LD nem o Google exigem @graph como o padrão — é sintaxe para expressar um grafo, e outros layouts válidos existem (blocos tipados separados, objetos aninhados sem um @graph de nível superior, nós em branco sem @id algum) — mas em um site com várias entidades referenciadas cruzadamente, é o padrão que evita repetir os mesmos dados de Organization ou WebSite em todas as páginas:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "Example Co",
      "url": "https://example.com/"
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "publisher": { "@id": "https://example.com/#org" }   // reference, not a copy
    },
    {
      "@type": "WebPage",
      "@id": "https://example.com/post#webpage",
      "isPartOf": { "@id": "https://example.com/#website" },
      "breadcrumb": { "@id": "https://example.com/post#breadcrumb" }
    }
  ]
}
</script>

Defina Organization uma vez e depois aponte para ela com { "@id": "...#org" } em todos os outros lugares, em vez de repetir o nome, o logotipo e a URL. É assim que os principais plugins de schema dos CMS constroem sua saída, e é por isso que @id existe. O Bing faz o mesmo argumento para o aninhamento do JSON-LD: ele “makes defining links and relationships between data and entities… easy because it supports nested data.” (tradução) «torna a definição de links e relacionamentos entre dados e entidades… fácil porque suporta dados aninhados.»

Onde colocá-lo: <head> ou <body>

O Google confirma que ambos funcionam — “You can put the JSON-LD data in the <head> or the <body> of the page.” (tradução) «Você pode colocar os dados JSON-LD no <head> ou no <body> da página.» <head> é convencional, mas muitos plugins de CMS injetam-no perto do final do <body>, e isso é aceitável. O Bing concorda que ele pode ficar “in the header, body or foot of the page.” (tradução) «no cabeçalho, corpo ou rodapé da página.» Não perca tempo realocando um bloco válido do corpo para o cabeçalho; isso não muda nada. Evidence for this claim Google permits JSON-LD in either the head or body of an HTML document for supported structured-data features. Scope: Google Search JSON-LD guidance; markup must still match visible page content. Confidence: high · Verified: 2026-07-14 Google: Structured data introduction

Gerando JSON-LD dinamicamente — e a pegadinha do rastreador de IA

Você pode construir JSON-LD dinamicamente com JavaScript, e o Google documenta duas maneiras de fazê-lo:

1. Google Tag Manager — uma tag HTML personalizada contendo o JSON-LD, extraindo valores de variáveis do GTM. (Evite duplicar dados entre a página e a tag.)
2. JavaScript personalizado — crie o elemento de script programaticamente:

   const script = document.createElement('script');
   script.setAttribute('type', 'application/ld+json');
   script.textContent = structuredDataText;
   document.head.appendChild(script);

Isso funciona para o Googlebot, porque o Google renderiza a página: “O Google Search pode entender e processar dados estruturados que estão disponíveis no DOM quando renderiza a página.” Até aqui, tudo bem.

Aqui está o detalhe que a maioria dos guias ignora, dito com cuidado. Vários rastreadores de IA — incluindo GPTBot e ClaudeBot, como comumente testados — não executaram JavaScript. Se o seu JSON-LD só existe depois que um script do lado do cliente é executado, um rastreador que ignora JavaScript nunca o vê — ele fica invisível para esse bot, mesmo que Googlebot o leia perfeitamente, porque o Google documenta a renderização do DOM antes de procurar dados estruturados.

Duas ressalvas honestas sobre esse comportamento de rastreadores de IA: é a própria documentação do Google que estabelece o lado do Googlebot; o lado dos rastreadores de IA vem de testes e relatos de provedores individuais, não de uma especificação que qualquer um deles publique, então é específico do provedor e da data — o suporte a JavaScript de um rastreador pode mudar, e eu não verifiquei cada provedor diretamente. Não trate “rastreadores de IA ignoram JS” como uma regra universal para construir em cima; trate como um motivo para verificar o rastreador que você realmente se importa (ou use renderização no servidor por padrão quando não puder verificar). Se não estiver no HTML renderizado no servidor e você não confirmou que o rastreador executa JS, assuma que ele não pode vê-lo. Para visibilidade em busca de IA, renderize JSON-LD no servidor dentro do HTML estático, a menos que você tenha verificado o contrário. (Este é o problema de renderização JavaScript de um ângulo de dados estruturados — veja JavaScript SEO.)

Há uma segunda ressalva para ecommerce: o Google avisa que a marcação Product dinamicamente gerada “pode tornar os rastreamentos do Shopping menos frequentes e menos confiáveis,” o que é um problema real para preço e disponibilidade que mudam rapidamente. Para produtos, prefira renderização no servidor, independentemente de IA.

As políticas (agora elas têm consequências)

As diretrizes de dados estruturados do Google são curtas e essenciais:

• “Não marque conteúdo que não esteja visível para os leitores da página.”
• “Não marque conteúdo irrelevante ou enganoso, como avaliações falsas.”
• “Coloque os dados estruturados na página que eles descrevem.”
• “Use os nomes de tipo e propriedade mais específicos aplicáveis definidos pelo schema.org.”
• Não bloqueie suas páginas de dados estruturados do Googlebot via robots.txt ou noindex.

A regra de conteúdo visível é a que você deve internalizar. Schema que descreve conteúdo não mostrado na página sempre foi uma violação; a aplicação de schema “invisível” foi reforçada. O Bing coloca o aviso de forma direta: “even though the markup is not visible on your page, it is still read by the search engines, and putting spam data in the markup can hamper your presence.” (tradução) «mesmo que a marcação não seja visível na página, ela ainda é lida pelos mecanismos de busca, e inserir dados de spam na marcação pode prejudicar sua presença.»

Erros comuns de JSON-LD

• Marcação que não corresponde à página visível — o problema nº 1 de política (uma avaliação no JSON-LD que nenhum visitante vê).
• JSON malformado — uma vírgula final, uma aspa sem escape ou aspas inteligentes do Word (" em vez de ") que quebram silenciosamente todo o bloco. JSON-LD é estrito.
• Nomes de propriedades errados — inventar propriedades que não estão no schema.org, ou escrever errado as reais, fazendo o parser ignorá-las.
• Um tipo genérico onde existe um específico — Thing ou Article onde Recipe ou NewsArticle era o adequado.
• Blocos Organization duplicados e inconsistentes entre páginas com nomes/logos conflitantes.
• Propriedades obrigatórias ausentes para o rich result que você está segmentando (cada recurso lista seus próprios campos obrigatórios).
• Marcação injetada via JS assumida como visível para todos os crawlers — o Google renderiza, mas alguns crawlers de IA não, e vale verificar por crawler (a ressalva acima).

Validando JSON-LD

Quatro perguntas diferentes são feitas sob “meu JSON-LD é válido”, e elas não são a mesma pergunta — passar em uma não significa passar nas outras:

• Teste por URL, não por código colado, para páginas renderizadas via JS. O modo de entrada de código do Rich Results Test não executa seus scripts nem resolve referências relativas da mesma forma que o teste de URL ao vivo — ele não pode dizer como um bloco injetado no lado do cliente fica após a renderização.
• Bing Webmaster Tools — Validador de Marcação — o Bing valida JSON-LD desde agosto de 2018.
• Nenhum desses testes fala por crawlers que não renderizam JavaScript (veja a ressalva do crawler de IA acima) — testar a URL renderizada confirma o que o Google vê, não o que um bot que ignora JS recebe.

JSON-LD ajuda no SEO?

Defina expectativas honestamente:

• Não é um sinal de ranqueamento. John Mueller disse que dados estruturados não farão um site ranquear melhor. Ponto final.
• Elegibilidade para rich results. É o que torna você elegível para recursos aprimorados de SERP (estrelas, preços, FAQs, breadcrumbs) — elegibilidade, não garantia.
• CTR, indiretamente. Resultados com aparência mais rica podem gerar mais cliques, que é o retorno real para a maioria dos sites.
• Entendimento de entidades. Ajuda os mecanismos a conectar sua página a entidades conhecidas e ao Knowledge Graph.
• Busca por IA. Fabrice Canel (Bing) confirmou em 2025 que a marcação de schema ajuda os LLMs da Microsoft a entender conteúdo — mas observe a ressalva do estudo controlado em Schema Markup for AI: é infraestrutura para desambiguação, não uma alavanca direta de citação.

Então: implemente JSON-LD para elegibilidade de rich results, clareza de entidades e compreensão por IA/LLM — não como um truque de ranqueamento.

Este artigo está no hub de dados estruturados. Para a abordagem específica de IA sobre o vocabulário do schema.org, consulte Schema Markup para IA; para os mecanismos de renderização por trás da injeção dinâmica, consulte JavaScript SEO.

Resumo de IA

Uma visão condensada da versão Avançada:

• O que é: JSON-LD (Notação de Objetos JavaScript para Dados Vinculados) é um formato de dados estruturados, não um vocabulário — um bloco <script type="application/ld+json">. No lado do SEO, normalmente é combinado com o vocabulário do schema.org, mas @context pode apontar para outro lugar. É uma Recomendação do W3C desde 2014 e se baseia em JSON, mas @context é o que o torna dados vinculados, não apenas JSON.
• Por que o Google recomenda: é “the easiest solution… to implement and maintain at scale” (tradução) «a solução mais fácil… de implementar e manter em escala» e nunca toca no HTML visível. Mas todos os três formatos (JSON-LD, Microdata, RDFa) são igualmente válidos quando corretos — a vantagem está na taxa de erro, não na análise ou no ranqueamento.
• Espinha dorsal da sintaxe: @context (vocabulário — schema.org para a maioria das marcações de SEO, não o único valor válido) · @type (entidade, use a mais específica) · @id (útil, URI estável opcional para referência cruzada; nós anônimos não identificados também são JSON-LD válido) · propriedades (chave/valor) · aninhamento (objetos/arrays).
• Padrão @graph: um bloco, um array de entidades com referência cruzada por @id — defina Organization uma vez, referencie em todos os lugares. Uma abordagem escalável para páginas com múltiplas entidades, não uma exigência de especificação ou do Google; outros layouts de grafo válidos existem.
• Posicionamento: <head> ou <body> — o Google aceita ambos; não mova blocos válidos.
• Injeção dinâmica + ressalva de IA: o Googlebot renderiza JS, então JSON-LD injetado funciona para o Google; vários rastreadores de IA — GPTBot e ClaudeBot incluídos, conforme testado — não executaram JS, mas isso é específico do provedor e da data, não uma regra universal, então verifique cada rastreador e renderize no servidor o que você não puder confirmar. A marcação dinâmica de Product também corre o risco de rastreamentos de Shopping menos frequentes.
• Políticas: marque apenas conteúdo visível; corresponda à página; tipo mais específico; não bloqueie a página dos rastreadores. A aplicação de schema “invisível” foi intensificada.
• Erros comuns: marcação incompatível ou invisível, JSON malformado (aspas inteligentes, vírgulas finais), nomes de propriedades errados, tipos genéricos, propriedades obrigatórias ausentes.
• Validação: quatro verificações separadas (sintaxe JSON, vocabulário schema.org, elegibilidade para rich results do Google, análise ao vivo do Search Console) que não substituem umas às outras — Rich Results Test (por URL, não código colado), Schema.org Validator, relatórios de melhorias do GSC e validador de marcação do Bing.
• Efeito no SEO: não é um sinal de ranqueamento. Impulsiona a elegibilidade para resultados avançados, CTR, compreensão de entidades e compreensão por LLMs (Canel, Bing, 2025).

Documentação oficial

Documentação de fonte primária dos mecanismos de busca e da especificação.

Google

• Introdução a Como Funciona o Markup de Dados Estruturados — a recomendação de JSON-LD, a nuance de que “todos os 3 formatos são igualmente válidos” e o posicionamento em <head>/<body>.
• Diretrizes Gerais de Dados Estruturados — as políticas: apenas conteúdo visível, correspondência com a página, tipo mais específico, não bloquear rastreadores.
• Gerar dados estruturados com JavaScript — as abordagens de injeção via GTM e JS personalizado, além da ressalva sobre rastreamento de Shopping para Product dinâmico.
• Rich Results Test — valide a elegibilidade (teste por URL para páginas renderizadas por JS).

Bing / Microsoft

• Marcando seu site com dados estruturados — O Bing recomenda JSON-LD, aceita a colocação no cabeçalho/corpo/rodapé e alerta sobre marcação inválida.
• Apresentando o suporte a JSON-LD no Bing Webmaster Tools (ago. 2018) — quando o Bing adicionou a validação de JSON-LD.

Padrões / vocabulário

• JSON-LD 1.1 — Recomendação W3C — a própria especificação.
• json-ld.org — a página inicial do formato, com a definição em linguagem simples.
• Começando com Schema.org — o vocabulário que o JSON-LD expressa e a regra de conteúdo visível.
• Validador Schema.org — valida em relação ao vocabulário.

Citações da fonte

Declarações oficiais do Google, do Bing e da especificação. Cada link leva à passagem citada na página de origem, quando a página expõe o texto.

Documentos do Google — a recomendação e a nuance

• “In general, Google recommends using JSON-LD for structured data if your site’s setup allows it, as it’s the easiest solution for website owners to implement and maintain at scale (in other words, less prone to user errors).” (tradução) «Em geral, o Google recomenda usar JSON-LD para dados estruturados se a configuração do seu site permitir, pois é a solução mais fácil para os proprietários de sites implementarem e manterem em escala (ou seja, menos propensa a erros do usuário).» Ir para a citação
• “All 3 formats are equally fine for Google, as long as the markup is valid and properly implemented per the feature’s documentation.” (tradução) «Todos os 3 formatos são igualmente aceitáveis para o Google, desde que a marcação seja válida e implementada corretamente de acordo com a documentação do recurso.» Ir para a citação
• “Google Search can understand and process structured data that’s available in the DOM when it renders the page.” (tradução) «O Google Search pode entender e processar dados estruturados que estão disponíveis no DOM quando renderiza a página.» Ir para a citação

Documentos do Google — as políticas

• “Don’t mark up content that is not visible to readers of the page.” (tradução) «Não marque conteúdo que não esteja visível para os leitores da página.» Ir para a citação
• “Use the most specific applicable type and property names defined by schema.org.” (tradução) «Use os nomes de tipo e propriedade mais específicos aplicáveis definidos pelo schema.org.» Ir para a citação

John Mueller, Google — preferência por JSON-LD e ranqueamento

• “We currently prefer JSON-LD markup. I think most of the new structured data that kind of come out are for JSON-LD first. So that is what we prefer.” (tradução) «Atualmente preferimos marcação JSON-LD. Acho que a maioria dos novos dados estruturados que surgem são para JSON-LD primeiro. Então é isso que preferimos.» — Google Webmaster Hangout, março de 2019. Cobertura
• Sobre ranqueamento: “Structured data won’t make your site rank better.” (tradução) «Dados estruturados não farão seu site ranquear melhor.» — 2025. (Transmitido via Search Engine Roundtable; confirme textualmente na publicação original.) Cobertura

Bing / Microsoft

• JSON-LD “makes defining links and relationships between data and entities between the data present on your pages easy because it supports nested data.” (tradução) «torna fácil definir links e relacionamentos entre dados e entidades entre os dados presentes nas suas páginas porque suporta dados aninhados.» — Documentação do Bing Webmaster Tools. Ir para a citação
• “Webmasters should be very alert as to not put invalid and incorrect information in the markup, as even though the markup is not visible on your page, it is still read by the search engines.” (tradução) «Os webmasters devem estar muito atentos para não colocar informações inválidas e incorretas na marcação, pois mesmo que a marcação não esteja visível na sua página, ela ainda é lida pelos mecanismos de busca.» — Documentação do Bing Webmaster Tools. Ir para a citação

Fabrice Canel, Microsoft Bing — schema e LLMs

• Na SMX Munique (março de 2025), Canel confirmou que a marcação de schema ajuda os modelos de linguagem grandes da Microsoft a entender o conteúdo da web. (Parafraseado em várias coberturas; confirme a citação verbatim com a gravação da conferência ou no LinkedIn antes de tratar qualquer frase específica como definitiva.) Cobertura

A especificação — json-ld.org

• “JSON-LD is a lightweight Linked Data format. It is easy for humans to read and write. It is based on the already successful JSON format and provides a way to help JSON data interoperate at Web-scale.” (tradução) «JSON-LD é um formato leve de Linked Data. É fácil para humanos lerem e escreverem. É baseado no já bem-sucedido formato JSON e fornece uma maneira de ajudar os dados JSON a interoperar em escala Web.» Ir para a citação

Sintaxe JSON-LD — referência rápida

O wrapper

<script type="application/ld+json">
{ ...your markup... }
</script>

As palavras-chave reservadas

Single entity

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Widget",
  "offers": { "@type": "Offer", "price": "19.99", "priceCurrency": "USD" }
}

Aninhamento — uma entidade filha é um objeto aninhado (ou uma matriz de objetos):

"author": { "@type": "Person", "name": "Patrick Stox" }

O padrão @graph — defina uma vez, referencie por @id:

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", "@id": "https://ex.com/#org", "name": "Ex Co" },
    { "@type": "WebSite", "publisher": { "@id": "https://ex.com/#org" } }
  ]
}

Propriedades comuns por tipo

• Article / BlogPosting: headline, author, datePublished, image, publisher
• Product: name, image, brand, offers (→ price, priceCurrency, availability)
• Organization: name, url, logo, sameAs (URIs sociais/Wikidata)
• BreadcrumbList: itemListElement → ListItem (position, name, item)
• FAQPage: mainEntity → Question → acceptedAnswer → Answer

Regras práticas

• @context é "https://schema.org" para a maioria das marcações de SEO — isso é uma convenção, não um requisito da especificação. Use aspas reto, nunca aspas inteligentes.
• Sem vírgulas finais — JSON é estrito.
• Use o @type mais específico disponível.
• Marque apenas o que está visível na página.
• Coloque no <head> ou no <body> — ambos são válidos.
• @id e @graph ajudam você a fazer referência cruzada e organizar entidades, mas não são obrigatórios — nós em branco e outros layouts também são válidos.
• Para rastreadores que você não verificou que executam JavaScript (vários rastreadores de IA, incluindo GPTBot e ClaudeBot, não executam em testes), renderize no lado do servidor.
• Valide em camadas separadas: Teste de resultados avançados (por URL) para elegibilidade do Google + Validador Schema.org para vocabulário — um passar não significa que o outro também.

Ferramentas para validar JSON-LD

• Validador Schema.org — a verificação de vocabulário mais ampla. Um bloco pode passar aqui e ainda falhar nas regras específicas de recurso do Google.
• Teste de resultados avançados do Google — teste a URL implantada quando a renderização importa, especialmente para marcação injetada no lado do cliente. Este teste cobre os resultados avançados suportados pelo Google, não todos os tipos do schema.org.

Erros de JSON-LD a evitar

Marcar fatos que os visitantes não podem ver. Uma avaliação, preço, autor ou outra afirmação em JSON-LD deve concordar com a página visível. Dados estruturados ocultos ou enganosos podem custar à página sua elegibilidade para rich results. Em vez disso: gere a marcação a partir da mesma fonte de verdade do conteúdo visível.

Tratar JSON válido como schema válido. Um parser pode aceitar JSON perfeitamente formado cujos nomes de propriedades não existem em schema.org. Em vez disso: execute tanto uma verificação de vocabulário JSON-LD quanto os requisitos do Google para o recurso alvo.

Usar aspas inteligentes ou vírgulas finais. JSON é estrito; aspas tipográficas e uma vírgula após a última propriedade podem invalidar todo o bloco. Em vez disso: serialize os dados em vez de montar strings JSON manualmente.

Escolher um tipo genérico quando um específico existe. Marcação Thing ou Article ampla joga fora significado útil quando a página é claramente um Recipe, Product ou NewsArticle. Em vez disso: use o tipo schema.org mais específico aplicável.

Duplicar entidades com detalhes conflitantes. Múltiplos blocos Organization com nomes, logos ou URLs diferentes tornam o grafo ambíguo. Em vez disso: dê à entidade um @id estável, defina-a uma vez e referencie esse identificador em outros lugares.

Assumir que a validade do schema.org garante um rich result do Google. O Google suporta um subconjunto de tipos e adiciona propriedades obrigatórias e políticas de conteúdo próprias. Em vez disso: valide o vocabulário primeiro, depois teste a elegibilidade para o recurso específico do Google.

Injetar JSON-LD em JavaScript e assumir que todo crawler o vê. O Google pode renderizar marcação no lado do cliente, mas crawlers de IA que pulam JS podem nunca recebê-la. Em vez disso: renderize JSON-LD no servidor quando esses consumidores importarem, e teste a URL ao vivo em vez de apenas código colado.

Prove que uma implantação de JSON-LD teve efeito

Teste 1 — A página ao vivo contém JSON-LD válido e correspondente à página

• Teste a executar — Busque a URL implantada com o Schema Markup Validator e compare as entidades e valores detectados com a página visível.
• Resultado esperado — O JSON é analisado, todas as propriedades pertencem ao schema.org, as referências @id resolvem dentro do grafo quando pretendido, e afirmações como nomes, preços, avaliações e datas correspondem ao que os usuários veem.
• Interpretação de falha — Erros de parser apontam para JSON malformado; avisos de vocabulário apontam para propriedades com erro de ortografia ou não suportadas; valores incompatíveis apontam para fontes de dados de conteúdo e schema separadas que estão divergindo.
• Janela de monitoramento — Imediata após a implantação e limpeza de cache.
• Gatilho de rollback — Remova ou reverta o novo bloco se ele publicar afirmações falsas de conteúdo visível, quebrar um grafo anteriormente válido ou não puder ser analisado.

Teste 2 — O recurso de busca alvo reconhece a marcação renderizada

• Teste a executar — Execute a URL implantada no Rich Results Test do Google e depois use o Verificador de elegibilidade de rich results para inspecionar campos obrigatórios e recomendados ausentes por tipo.
• Resultado esperado — O Google detecta o tipo suportado pretendido sem erros críticos; qualquer bloco gerado no lado do cliente aparece no HTML renderizado.
• Interpretação de falha — Uma aprovação no Schema.org Validator combinada com uma falha do Google geralmente significa que o tipo não é um recurso suportado do Google, um campo obrigatório do Google está ausente, uma política de conteúdo não é atendida ou o renderizador nunca recebeu o bloco.
• Janela de monitoramento — Imediata em ambos os testes; mudanças no Search Console aguardam um recrawl.
• Gatilho de rollback — Reverta a injeção no lado do cliente se ela fizer dados estruturados anteriormente visíveis desaparecerem do resultado renderizado, ou remova afirmações de recursos não suportados do lançamento até que o conteúdo obrigatório esteja presente.

Teste-se: JSON-LD

Cinco perguntas rápidas sobre o formato JSON-LD. Escolha uma resposta para cada uma e depois verifique.

Recursos que valem seu tempo

Meus artigos relacionados

• Marcação de schema: a maneira fácil de obter rich results — o guia da Ahrefs sobre dados estruturados, tipos de schema e rich results (a camada de recursos sobre JSON-LD).
• Guia para iniciantes em SEO técnico — onde os dados estruturados se encaixam no panorama técnico mais amplo.
• Problemas e práticas recomendadas de SEO para JavaScript — o lado da renderização: por que a marcação injetada via JS se comporta de forma diferente para rastreadores que não executam JavaScript.
• Conheça os novos rastreadores da web — minha análise no Cloudflare Radar sobre rastreadores de IA (GPTBot, ClaudeBot e afins) — os bots que ignoram sua marcação de schema injetada via JS.

Oficial

• A introdução do Google ao funcionamento da marcação de dados estruturados — a recomendação de JSON-LD e a nuance dos “3 formatos”, direto da fonte.
• O guia do Google para gerar dados estruturados com JavaScript — os métodos de injeção dinâmica e a ressalva sobre Product.
• JSON-LD 1.1 — Recomendação do W3C e json-ld.org — o formato em si.

Da indústria

• Qual formato de dados estruturados o Google prefere — Search Engine Journal — a matéria sobre o comentário de Mueller: “we currently prefer JSON-LD” (tradução) «atualmente preferimos JSON-LD».
• Microsoft Bing Copilot usa schema para seus LLMs — Search Engine Land — a confirmação de Fabrice Canel no SMX Munich 2025 de que o schema ajuda os LLMs do Bing.
• O que são dados estruturados JSON-LD e por que você precisa deles? — Ignite Visibility — um passo a passo sólido para iniciantes.
• Guia para iniciantes em schema JSON-LD para profissionais de SEO — SALT.agency — um guia prático de sintaxe e implementação voltado para profissionais de SEO.

Registro de alterações