JSON-LD como infraestrutura de dados para SEO, GEO e AEO: fundamentos, arquitetura, implementação e auditoria

Atualizado em 05/08/2026 28 min de leitura Publicado em 29/07/2026

TL;DR

JSON-LD é uma camada de publicação de dados que explicita entidades e relações para máquinas. Este guia mostra como planejar, implementar, validar, monitorar e governar a marcação para SEO, GEO e AEO sem confundir validade técnica com garantia de ranqueamento, rich results ou citações em IA.

JSON-LD costuma ser apresentado como um recurso de SEO que adiciona estrelas, preços, perguntas ou outros elementos aos resultados de busca. Essa descrição não está totalmente errada, mas é pequena demais para representar o papel real dos dados estruturados.

Em uma implementação madura, JSON-LD funciona como uma camada de publicação de dados: transforma informações já existentes no site em entidades, propriedades e relacionamentos legíveis por máquinas. Essa camada pode ajudar mecanismos de busca a interpretar uma página, tornar determinados conteúdos elegíveis a recursos visuais e reduzir ambiguidades sobre organizações, pessoas, produtos, artigos e outras entidades.

Isso não significa que adicionar marcação fará uma página subir de posição, receber um rich result ou ser citada por uma inteligência artificial. Entre uma marcação tecnicamente válida e um resultado de negócio existem várias etapas: rastreamento, renderização, indexação, suporte do consumidor, conformidade com políticas, elegibilidade algorítmica, exibição, impressão, clique e conversão.

Este guia apresenta uma abordagem de engenharia para planejar, implementar, testar, monitorar e governar JSON-LD. O foco não está em instalar mais um plugin ou copiar blocos prontos, mas em construir uma infraestrutura semântica coerente, auditável e conectada aos objetivos reais do site.

NOTA TÉCNICA: Todas as informações contidas aqui retratam a minha experiência e o meu método de trabalho, você é o total responsável por alterações no seu site ou no site de seus clientes. Nos responsabilizamos exclusivamente em parcerias formalizadas por contratos. Em dúvida, visite o Aviso Legal.

Escopo temporal: as informações sobre recursos suportados e descontinuados foram verificadas em julho de 2026. Como mecanismos de busca modificam seus recursos ao longo do tempo, a documentação oficial deve ser consultada antes de cada projeto ou revisão relevante.

Fundamentos: dados estruturados, Schema.org, JSON-LD e grafos

Quatro conceitos que não são sinônimos

Dados estruturados são informações organizadas de acordo com campos, tipos e relações previamente definidos. Uma tabela de produtos com nome, SKU, preço e disponibilidade é um conjunto de dados estruturados, mesmo que ainda não esteja publicado em uma página.

Schema.org é um vocabulário compartilhado para descrever entidades e suas propriedades. Ele contém tipos como Organization, Person, Article, Product, Event e Service, além de propriedades como name, url, author, offers e sameAs. O projeto foi fundado por Google, Microsoft, Yahoo e Yandex e evolui por um processo comunitário aberto.

JSON-LD, ou JavaScript Object Notation for Linked Data, é um formato baseado em JSON para serializar dados conectados. Ele permite publicar o vocabulário Schema.org sem espalhar atributos por todo o HTML visível.

Grafo de entidades é o modelo resultante quando os objetos deixam de ser registros isolados e passam a se relacionar. Um artigo pode ser publicado por uma organização, escrito por uma pessoa, integrar um website e ser a entidade principal de uma página. O valor arquitetural está tanto nos nós quanto nas relações entre eles.

Um exemplo mínimo:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://www.example.com/#organization",
  "name": "Example Engenharia Digital",
  "url": "https://www.example.com/"
}
</script>

Esse bloco declara que existe uma entidade do tipo Organization, atribui a ela um identificador persistente e informa seu nome e sua URL. Ele não prova que a empresa é confiável, não cria autoridade por si só e não garante um painel de conhecimento. Ele apenas publica uma afirmação estruturada que um consumidor pode considerar juntamente com outras fontes e sinais.

JSON-LD não é o banco de dados nem a fonte de verdade

Um erro conceitual comum é tratar a marcação como cadastro principal da empresa, do produto ou do conteúdo. Em uma arquitetura correta, o JSON-LD é uma saída derivada de fontes de verdade já governadas:

cadastro institucional;
perfil do autor;
CMS editorial;
catálogo de produtos;
sistema de preços e estoque;
agenda de eventos;
banco de dados do curso;
informações visíveis na página.

Se o preço muda no ERP, mas não muda no JSON-LD, a marcação se torna inconsistente. Se a biografia do autor é atualizada, mas o grafo continua apontando para uma página removida, a identidade se degrada. O problema não é somente sintático: é um problema de sincronização entre sistemas.

Portanto, antes de escrever qualquer marcação, responda:

Qual sistema possui o valor oficial de cada campo?
Quem pode alterar esse valor?
Como a atualização chega à página e ao JSON-LD?
Qual atraso entre os sistemas é aceitável?
Como uma divergência será detectada?

O que JSON-LD pode e não pode fazer

JSON-LD pode:

fornecer pistas explícitas sobre o significado de uma página;
descrever entidades e relações;
tornar páginas elegíveis a recursos compatíveis;
facilitar consistência entre templates;
servir como uma interface pública e legível por máquinas;
apoiar auditorias sobre autoria, datas, preços, disponibilidade e identidade;
reduzir ambiguidades quando os identificadores são estáveis e as relações são coerentes.

JSON-LD não pode:

garantir posicionamento;
garantir rich result;
compensar conteúdo fraco;
tornar indexável uma página bloqueada;
corrigir uma arquitetura de URLs defeituosa;
substituir links internos;
provar experiência, autoridade ou confiabilidade;
fazer uma empresa entrar automaticamente no Knowledge Graph;
garantir citação em AI Overviews, AI Mode, ChatGPT, Copilot ou qualquer outro sistema generativo.

O mecanismo de busca também pode extrair informações diretamente do texto, do HTML, dos links, das imagens e de outras fontes. Dados estruturados são uma declaração adicional, não a única forma de compreensão.

Os níveis de evidência

Para impedir que hipóteses sejam ensinadas como fatos, toda recomendação deve ser classificada:

Nível	Definição	Exemplo
Documentado	Há documentação primária do consumidor	`Product` pode tornar uma página elegível a experiências de produto no Google
Inferência técnica	A arquitetura sugere benefício, mas o consumidor não oferece garantia específica	Identificadores estáveis reduzem ambiguidade dentro do próprio grafo
Hipótese experimental	A relação precisa ser testada e pode variar por sistema	Determinada expansão de entidade pode aumentar citações em respostas generativas

Essa classificação muda a forma de comunicar o projeto. Uma oportunidade documentada pode entrar no escopo com critério claro de aceite. Uma inferência técnica deve ser justificada como decisão arquitetural. Uma hipótese deve ter plano de teste, prazo, métrica e possibilidade explícita de resultado nulo.

SEO, AEO e GEO em um sistema híbrido de recuperação

Palavras-chave não foram substituídas por entidades

A evolução dos mecanismos de busca não foi uma passagem simples de “palavras-chave” para “entidades”. Sistemas modernos combinam correspondência lexical, intenção, entidades, passagens, contexto, relações, links, sinais de qualidade, informações locais, mídia e modelos de aprendizado de máquina.

As palavras continuam importantes porque pessoas usam linguagem. Entidades adicionam persistência e desambiguação. Passagens permitem recuperar trechos específicos. Modelos semânticos aproximam conceitos que não usam os mesmos termos. Sistemas generativos podem decompor uma pergunta em várias consultas e sintetizar respostas a partir de múltiplas fontes.

Um conteúdo tecnicamente maduro não abandona palavras-chave. Ele combina:

linguagem que corresponde às necessidades reais do usuário;
conceitos e entidades definidos sem ambiguidade;
relações explícitas;
conteúdo original e verificável;
hierarquia editorial;
URLs estáveis;
links internos;
metadados coerentes;
dados estruturados quando aplicáveis.

Como SEO, AEO e GEO se relacionam

SEO busca tornar conteúdo rastreável, indexável, compreensível, competitivo e capaz de receber tráfego qualificado em mecanismos de busca.

AEO concentra-se em tornar respostas identificáveis e aproveitáveis por interfaces que respondem perguntas, como resultados diretos, assistentes e mecanismos de resposta.

GEO concentra-se na presença e representação de marcas, fontes e conteúdos em experiências generativas.

As fronteiras desses termos não são padronizadas e diferentes profissionais podem usá-los com amplitudes distintas. Por isso, um projeto deve definir operacionalmente qual superfície, comportamento e resultado está chamando de AEO ou GEO, em vez de assumir que o nome da disciplina já descreve a entrega.

Essas disciplinas se sobrepõem, mas nenhuma deve ser tratada como substituta ou consequência automática da outra. A base comum inclui:

acesso do crawler;
indexação;
conteúdo textual disponível;
resposta clara à necessidade;
originalidade;
informação verificável;
autoria transparente;
fontes e evidências;
arquitetura interna;
consistência da entidade;
dados estruturados coerentes com o conteúdo.

No caso específico do Google, não há requisito técnico adicional para aparecer como link de apoio em AI Overviews ou AI Mode. A página precisa estar indexada e elegível a aparecer com snippet. Isso reduz o espaço para “táticas secretas de GEO” e aumenta a importância da infraestrutura tradicional bem executada.

O papel real do JSON-LD em GEO e AEO

É tecnicamente razoável afirmar que dados estruturados tornam determinadas informações mais explícitas para máquinas. Não é razoável transformar essa propriedade em garantia de seleção, citação ou recomendação.

O papel defensável do JSON-LD é:

publicar fatos em formato padronizado;
manter identidades e relações consistentes;
reduzir divergências entre templates;
facilitar o consumo por sistemas que suportem aquele vocabulário;
criar uma camada reutilizável de dados públicos.

Se um projeto quiser testar impacto em experiências generativas, deve separar correlação de causalidade. Uma marcação pode ser publicada no mesmo período em que conteúdo, links internos, autoridade externa e rastreamento também melhoram. Sem desenho experimental, não será possível atribuir o efeito ao JSON-LD.

O ciclo de vida de um recurso

Um tipo pode continuar válido no Schema.org mesmo depois que um mecanismo de busca deixa de exibi-lo. O ciclo típico é:

o tipo existe no vocabulário;
um consumidor decide interpretá-lo;
o consumidor cria um recurso;
surgem documentação, validador e relatório;
o recurso pode ser limitado;
o recurso pode ser retirado;
o tipo pode continuar válido para outros consumidores.

Isso explica por que guias antigos acumulam recomendações mortas. SearchAction continua sendo uma expressão válida, mas o sitelinks search box do Google deixou de ser exibido globalmente em novembro de 2024. FAQPage continua existindo no Schema.org, mas o FAQ rich result deixou de aparecer no Google em 7 de maio de 2026.

“Válido” não significa “prioritário”. A manutenção de qualquer marcação precisa de um consumidor, finalidade ou hipótese de negócio identificável.

Como priorizar schemas por página, consumidor e resultado

A cadeia de decisão

Antes de implementar, percorra esta sequência:

Qual é a entidade principal da página?
O conteúdo correspondente está visível?
O tipo existe no Schema.org?
O consumidor-alvo declara suporte?
Existe um recurso ativo ou apenas valor semântico?
Quais propriedades são obrigatórias e recomendadas para esse consumidor?
Qual resultado operacional ou comercial justifica o custo?
Como os valores serão mantidos atualizados?
Como a implementação será validada e monitorada?

Essa cadeia evita começar pela pergunta errada: “Qual schema está em alta?”.

Matriz de decisão

Arquétipo	Tipo principal provável	Resultado documentado no Google	Observação operacional
Site institucional	`Organization` e `WebSite`	Informações organizacionais e preferência de site name	Normalmente concentrar detalhes institucionais na home ou página da organização
Negócio com localização física	subtipo de `LocalBusiness`	Experiências locais e informações do negócio	Usar o subtipo mais específico e manter dados coerentes com fontes públicas
Artigo editorial	`Article`, `BlogPosting` ou `NewsArticle`	Melhor compreensão de título, imagens, datas e autoria	Datas, imagens e autor precisam corresponder ao conteúdo visível
Perfil de autor	`ProfilePage` e `Person`	Identificação de página de perfil	Conectar `author` a um nó `Person`; nesse nó, usar `url`, `sameAs` ou um `@id` coerente
Produto	`Product` e `Offer`	Product snippets e, quando aplicável, merchant listings	Preço, moeda e disponibilidade exigem sincronização rigorosa
Serviço B2B	`Service`	Não há rich result genérico equivalente a `Product`	Valor principalmente descritivo e semântico; não prometer efeito visual
Curso	`Course` e, quando aplicável, `CourseInstance`	Recursos específicos dependem da experiência atualmente suportada	Não confundir Course list com recursos de Course info já retirados
Evento	`Event`	Experiência de evento	Data, local, status e oferta precisam ser atualizados
Vaga	`JobPosting`	Experiência de busca de vagas	Remover ou atualizar vagas encerradas
Vídeo principal da página	`VideoObject`	Recursos de vídeo e possíveis key moments	O vídeo deve ser conteúdo principal e seus arquivos precisam ser acessíveis
Perguntas respondidas pelo próprio site	`FAQPage`	FAQ rich result retirado em maio de 2026	Manter apenas com justificativa semântica ou consumidor identificado
Fórum com uma pergunta e respostas de usuários	`QAPage`	Recurso de Q&A, quando elegível	Não usar como substituto de FAQ; usuários precisam poder enviar respostas

As propriedades “obrigatórias” e “recomendadas” devem ser interpretadas no contexto do consumidor. O Schema.org define um vocabulário amplo; o Google, o Bing ou outro sistema podem consumir apenas uma parte e impor requisitos próprios para uma experiência específica. Uma propriedade opcional no vocabulário pode ser necessária para determinado recurso, enquanto uma propriedade válida pode ser ignorada por aquele consumidor.

`Organization`, `LocalBusiness` e `WebSite`

Organization descreve a entidade organizacional. LocalBusiness deve ser usado quando existe um negócio local compatível, preferencialmente com o subtipo mais específico. Eles não devem ser tratados como rótulos intercambiáveis escolhidos por conveniência.

O Google recomenda publicar os detalhes completos da organização na home ou em uma única página institucional, como “Sobre”. Não é necessário repetir o cadastro inteiro em todas as páginas. Se um plugin reproduzir o mesmo nó de forma consistente em um grafo site-wide, isso não é automaticamente um erro; o problema aparece quando os nós usam identificadores ou valores conflitantes.

WebSite representa o site, não a empresa. Na home, ele também é importante para indicar a preferência de site name por meio de name e, quando necessário, alternateName. Organização e website podem ter nomes semelhantes, mas continuam sendo entidades diferentes.

Exemplo institucional:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://www.example.com/#organization",
      "name": "Example Engenharia Digital",
      "legalName": "Example Engenharia Digital Ltda.",
      "url": "https://www.example.com/",
      "logo": {
        "@type": "ImageObject",
        "@id": "https://www.example.com/#logo",
        "url": "https://www.example.com/assets/logo.png",
        "contentUrl": "https://www.example.com/assets/logo.png",
        "width": 512,
        "height": 512
      },
      "sameAs": [
        "https://www.linkedin.com/company/example",
        "https://www.instagram.com/example"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://www.example.com/#website",
      "url": "https://www.example.com/",
      "name": "Example Engenharia Digital",
      "alternateName": "Example",
      "publisher": {
        "@id": "https://www.example.com/#organization"
      },
      "inLanguage": "pt-BR"
    },
    {
      "@type": "WebPage",
      "@id": "https://www.example.com/#webpage",
      "url": "https://www.example.com/",
      "name": "Example Engenharia Digital",
      "isPartOf": {
        "@id": "https://www.example.com/#website"
      },
      "about": {
        "@id": "https://www.example.com/#organization"
      },
      "inLanguage": "pt-BR"
    }
  ]
}
</script>

Os valores são ilustrativos. Nenhum campo deve ser publicado apenas porque apareceu no exemplo. Se a organização não usa determinado perfil, não existe motivo para incluí-lo. Se um dado não deve ser público, ele não deve entrar no grafo.

Artigo, autor e perfil

Em páginas editoriais, Article, BlogPosting ou NewsArticle descrevem a obra. Person descreve o autor. ProfilePage descreve a página cujo assunto principal é esse autor. Organization pode representar o publisher.

Essa arquitetura torna a autoria explícita, mas não cria E-E-A-T automaticamente. A credibilidade continua dependendo de biografia visível, experiência demonstrada, transparência editorial, precisão, reputação e fontes externas.

Exemplo de artigo conectado:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "BlogPosting",
      "@id": "https://www.example.com/blog/json-ld/#article",
      "url": "https://www.example.com/blog/json-ld/",
      "headline": "JSON-LD como infraestrutura de dados",
      "description": "Guia técnico sobre arquitetura, implementação e auditoria de JSON-LD.",
      "datePublished": "2026-07-29T09:00:00-03:00",
      "dateModified": "2026-07-29T09:00:00-03:00",
      "inLanguage": "pt-BR",
      "image": [
        "https://www.example.com/media/json-ld-1x1.jpg",
        "https://www.example.com/media/json-ld-4x3.jpg",
        "https://www.example.com/media/json-ld-16x9.jpg"
      ],
      "author": {
        "@id": "https://www.example.com/autor/felipe/#person"
      },
      "publisher": {
        "@id": "https://www.example.com/#organization"
      },
      "mainEntityOfPage": {
        "@id": "https://www.example.com/blog/json-ld/#webpage"
      }
    },
    {
      "@type": "WebPage",
      "@id": "https://www.example.com/blog/json-ld/#webpage",
      "url": "https://www.example.com/blog/json-ld/",
      "name": "JSON-LD como infraestrutura de dados",
      "isPartOf": {
        "@id": "https://www.example.com/#website"
      },
      "breadcrumb": {
        "@id": "https://www.example.com/blog/json-ld/#breadcrumb"
      },
      "inLanguage": "pt-BR"
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://www.example.com/blog/json-ld/#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Início",
          "item": "https://www.example.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Blog",
          "item": "https://www.example.com/blog/"
        },
        {
          "@type": "ListItem",
          "position": 3,
          "name": "JSON-LD como infraestrutura de dados"
        }
      ]
    },
    {
      "@type": "Person",
      "@id": "https://www.example.com/autor/felipe/#person",
      "name": "Felipe Ferreira",
      "url": "https://www.example.com/autor/felipe/",
      "sameAs": [
        "https://www.linkedin.com/in/example"
      ]
    },
    {
      "@type": "Organization",
      "@id": "https://www.example.com/#organization",
      "name": "Example Engenharia Digital",
      "url": "https://www.example.com/"
    }
  ]
}
</script>

O Google aceita itens aninhados ou separados. @graph foi usado para tornar as relações visíveis e facilitar a governança, não porque múltiplos scripts seriam inválidos.

O nó mínimo de Organization foi repetido para que o exemplo seja compreensível isoladamente. Em produção, se o CMS ou plugin já publica a organização com o mesmo @id, a implementação deve reutilizar essa identidade e evitar criar outro nó concorrente.

O breadcrumb continua semanticamente útil para representar a hierarquia, mas sua apresentação como recurso do Google está disponível somente em resultados para desktop desde 2025. A implementação não deve presumir o mesmo efeito visual em dispositivos móveis.

`Product`, `Service`, `Course`, `Event` e `VideoObject`

Product possui suporte documentado a experiências de produto. Isso justifica uma disciplina maior sobre Offer, preço, moeda, disponibilidade, avaliações, frete e devolução.

Service descreve serviços, mas não deve ser vendido como equivalente de Product para rich results. Em uma landing page B2B, ele pode integrar o grafo:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Service",
  "@id": "https://www.example.com/servicos/auditoria-tracking/#service",
  "name": "Auditoria de tracking e web analytics",
  "url": "https://www.example.com/servicos/auditoria-tracking/",
  "description": "Auditoria técnica de GA4, Google Tag Manager e eventos de conversão.",
  "provider": {
    "@id": "https://www.example.com/#organization"
  },
  "areaServed": {
    "@type": "Country",
    "name": "Brasil"
  }
}
</script>

Esse bloco não deve conter preço, prazo, certificação ou resultado que não estejam apresentados e sustentados na página. Para indicar o idioma do conteúdo, use inLanguage no nó que representa a página ou outra obra, como WebPage; a propriedade não é esperada em um Service genérico. Se a intenção for descrever os idiomas em que o serviço está disponível, modele essa informação com uma propriedade compatível com essa finalidade.

Em cursos, eventos e vídeos, o raciocínio é semelhante: o tipo só deve ser priorizado quando o formato realmente existe e há finalidade clara. Um curso precisa ter informações reais de curso; um evento precisa ter data, local ou modo de participação; VideoObject precisa descrever um vídeo que tenha papel relevante na página.

Também é necessário distinguir tipos parecidos. A retirada do recurso Course info não significa que todas as experiências relacionadas a cursos desapareceram. A galeria atual do Google ainda deve ser consultada para verificar Course list e seus requisitos. Em julho de 2026, esse recurso está disponível somente em inglês e exige a marcação de pelo menos três cursos, além do markup de carrossel com ItemList em uma página de resumo ou em uma página que reúna todos os cursos. O nome do tipo no Schema.org não é suficiente para determinar o suporte.

Recursos retirados ou limitados

Alguns exemplos precisam integrar o material porque demonstram a necessidade de revisão contínua:

WebSite continua relevante, mas SearchAction não produz mais o sitelinks search box do Google;
FAQPage não produz mais FAQ rich results no Google desde maio de 2026;
HowTo existe no Schema.org, mas não deve ser priorizado com base em guias antigos sem verificar a galeria atual;
Breadcrumb rich results são apresentados em desktop, não em mobile;
Course info foi retirado, o que não deve ser confundido com todos os recursos de curso;
tipos não suportados pelo Google podem não aparecer no Rich Results Test nem nos relatórios de melhorias do Search Console.

Um tipo descontinuado não precisa ser removido em emergência somente porque deixou de gerar efeito visual. A decisão deve considerar custo de manutenção, existência de outros consumidores, risco de inconsistência e utilidade real.

Engenharia do grafo e implementação

`@id`, `url` e `sameAs`

Esses três campos resolvem problemas diferentes.

@id identifica o nó no grafo. Em projetos web, uma URL absoluta com fragmento é um padrão prático:

https://www.example.com/#organization
https://www.example.com/#website
https://www.example.com/autor/felipe/#person
https://www.example.com/artigo/#webpage
https://www.example.com/artigo/#article

Uma organização global não deve receber um @id baseado em cada página. Usar https://www.example.com/pagina-a/#organization e https://www.example.com/pagina-b/#organization cria dois identificadores para uma entidade que deveria ser a mesma.

url aponta para a página que representa a entidade ou o recurso. Pode ser igual à parte anterior ao fragmento de @id, mas sua função é diferente.

sameAs aponta para páginas de referência que indicam inequivocamente a identidade da entidade. O Schema.org não exige que essas páginas estejam em outro domínio, embora consumidores específicos possam recomendar perfis externos ou páginas oficiais em determinados contextos. A propriedade não deve receber qualquer link que apenas mencione a organização ou a pessoa. Perfis falsos, páginas genéricas, resultados de busca e diretórios sem controle de identidade pioram a qualidade.

Relações fundamentais

Um grafo editorial típico pode usar:

Origem	Propriedade	Destino
`WebSite`	`publisher`	`Organization`
`WebPage`	`isPartOf`	`WebSite`
`WebPage`	`breadcrumb`	`BreadcrumbList`
`Article`	`mainEntityOfPage`	`WebPage`
`Article`	`author`	`Person`
`Article`	`publisher`	`Organization`
`Service`	`provider`	`Organization`
`Product`	`offers`	`Offer`

Não é necessário adicionar toda relação possível. O objetivo é representar fielmente o que existe, não produzir o maior JSON-LD da concorrência.

Um bloco ou vários blocos?

O Google entende múltiplos itens aninhados ou declarados individualmente. Há três arquiteturas aceitáveis:

um único objeto simples;
vários blocos JSON-LD independentes;
um @graph conectando múltiplos nós.

@graph tende a ser vantajoso quando:

várias páginas reutilizam as mesmas identidades;
há relações entre autor, publisher, website, página e conteúdo;
o CMS já trabalha com grafo;
a organização precisa auditar nós e identificadores;
diferentes equipes enriquecem a mesma estrutura.

Blocos separados podem ser adequados quando:

a página tem um único objeto;
integrações independentes são responsáveis por entidades diferentes;
a união aumentaria o acoplamento sem benefício;
os identificadores mantêm os relacionamentos necessários.

A regra não é “unificar sempre”. A regra é não produzir contradição, duplicação competitiva ou perda de relacionamento.

Inventário antes da implementação

Em WordPress, nunca comece instalando outro plugin. Primeiro examine o HTML e a versão renderizada para descobrir o que já é gerado por:

WordPress;
tema;
Yoast SEO;
Rank Math;
WooCommerce;
plugin de eventos;
plugin de cursos;
plugin de reviews;
construtor de páginas;
Google Tag Manager;
código customizado.

O inventário deve registrar:

Campo	Exemplo
Template	Artigo
URL de amostra	`/blog/exemplo/`
Nós encontrados	`WebPage`, `BlogPosting`, `Person`, `Organization`
Origem	Yoast SEO
Identificador principal	`https://example.com/#organization`
Problema	Dois autores com URLs diferentes
Responsável	Conteúdo e desenvolvimento
Ação	Corrigir perfil e extensão do grafo

Quando o Yoast já produz um grafo, a solução mais sustentável costuma ser estender ou filtrar as peças existentes por sua API, preservando os IDs centrais, em vez de inserir outro grafo concorrente.

Hierarquia de métodos de publicação

Método	Quando usar	Principal vantagem	Principal risco
Backend ou template server-side	Dados controlados pelo sistema	Saída presente no HTML e sincronização direta	Exige desenvolvimento e testes
Integração nativa do CMS/plugin	CMS com suporte adequado	Menor custo operacional	Limitações e conflitos entre plugins
Código estático	Poucas páginas realmente estáticas	Simplicidade inicial	Obsolescência e edição manual
JavaScript customizado	Aplicações que já dependem de renderização	Flexibilidade	Falha de renderização ou atraso
Google Tag Manager	Exceção operacional ou solução transitória	Deploy sem alterar template	Duplicação, divergência e governança paralela

O GTM é tecnicamente suportado pelo Google para gerar JSON-LD, mas não deve se tornar um banco de dados paralelo. Sempre que possível, as variáveis devem extrair os valores da própria página, em vez de duplicar título, preço ou autor dentro do container.

Para Product, dados gerados dinamicamente podem tornar os crawls de Shopping menos frequentes e menos confiáveis, um risco importante quando preço e disponibilidade mudam rapidamente. Nesses casos, renderização server-side e integração direta com a fonte comercial tendem a ser mais adequadas.

Geração segura

Nunca monte JSON-LD concatenando strings recebidas de formulários, banco de dados ou usuários. Use o serializador oficial da linguagem e aplique as proteções do framework.

Exemplo conceitual em PHP/WordPress:

<?php
$schema = [
    '@context' => 'https://schema.org',
    '@type' => 'Service',
    'name' => get_the_title(),
    'url' => get_permalink(),
];

echo '<script type="application/ld+json">';
echo wp_json_encode(
    $schema,
    JSON_HEX_TAG | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
);
echo '</script>';
?>

Esse exemplo ainda depende de contexto, escaping, revisão das fontes dos valores e compatibilidade com a arquitetura do site. Seu mérito está em serializar um objeto, não em concatenar JSON manualmente.

Em qualquer backend:

aplique allowlist de campos publicáveis;
valide tipos;
normalize URLs;
use datas ISO 8601 com fuso horário;
use códigos de país e moeda esperados;
escape conteúdo conforme o framework;
impeça que valores insiram </script> ou alterem a estrutura;
teste dados com aspas, acentos, quebras de linha e caracteres especiais;
não marque campos nulos como se fossem informação válida.

Ambientes, deploy e rollback

Uma alteração deve seguir pelo menos:

desenvolvimento;
validação de sintaxe;
validação do consumidor;
homologação em staging;
publicação em pequena amostra;
inspeção da URL renderizada;
expansão para o template;
monitoramento;
registro da mudança.

O rollback deve ser definido antes do deploy. Em CMS, isso pode significar desativar um filtro, restaurar versão do plugin, reverter template ou desligar uma feature flag. “Remover manualmente depois” não é um plano de rollback.

Validação, observabilidade e mensuração

Validade não é um estado único

Uma implementação pode ser válida em uma camada e falhar na seguinte:

Camada	Pergunta	Ferramenta ou evidência
Sintaxe JSON	O bloco pode ser analisado como JSON?	Parser e testes automatizados
JSON-LD	O contexto e as palavras-chave são processáveis?	Ferramentas compatíveis com JSON-LD
Schema.org	Tipos e propriedades pertencem ao vocabulário?	Schema Markup Validator
Consumidor	O mecanismo suporta esse tipo e essas propriedades?	Documentação e ferramenta do consumidor
Política	A marcação representa conteúdo visível e permitido?	Revisão humana e políticas oficiais
Renderização	O crawler recebe a marcação?	URL Inspection e HTML renderizado
Indexação	A página está indexada e elegível?	Search Console ou Bing Webmaster Tools
Exibição	O recurso apareceu?	SERP e relatórios de performance
Negócio	Houve impressão, clique, lead ou receita incremental?	Analytics, CRM e desenho de mensuração

Nenhuma ferramenta isolada cobre todas essas camadas.

Fluxo de validação

1. Parser de JSON

Capture erros básicos como vírgulas, aspas, colchetes e tipos inválidos antes de qualquer ferramenta externa.

2. Schema Markup Validator

Use para validar o vocabulário Schema.org independentemente do suporte específico do Google.

3. Rich Results Test

Use para verificar quais rich results do Google podem ser gerados. Um tipo válido que não alimenta um recurso suportado pode não ser reconhecido ali.

4. Inspeção de URL

Valide a URL publicada e a versão renderizada. Isso é particularmente importante quando JSON-LD é gerado por JavaScript ou GTM.

5. Search Console

Monitore relatórios de melhorias quando existirem para o tipo implementado, dados não analisáveis e ações manuais. A ausência de um relatório não significa ausência de todo dado estruturado; o Search Console não oferece relatório dedicado para todos os tipos do Schema.org.

6. Bing Webmaster Tools

Use a inspeção de URL e os detalhes de markup para avaliar como o Bing processa a página. Não presuma equivalência integral entre ferramentas do Google e do Bing.

Erro, aviso e divergência

Um erro crítico pode impedir que um item seja considerado válido para um recurso específico. Isso não significa necessariamente que o mecanismo foi incapaz de ler qualquer parte da página.

Um aviso normalmente indica propriedade recomendada ausente. O item pode continuar elegível, embora potencialmente menos completo.

Uma divergência é mais perigosa do que muitos avisos. Exemplos:

preço visível de R$ 499 e offers.price igual a 399;
artigo atualizado em 2024 com dateModified em 2026;
página escrita por uma pessoa e markup indicando outra;
produto indisponível marcado como InStock;
evento cancelado marcado como ativo;
organização com dois nomes e dois logotipos concorrentes;
FAQ invisível inserido apenas no JSON-LD.

Validadores sintáticos não substituem revisão de verdade factual.

Observabilidade por template

Auditar duas URLs manualmente não prova que cinco mil páginas estão corretas. O monitoramento deve trabalhar por template e por amostragem:

home;
página institucional;
artigo;
autor;
categoria;
serviço;
produto;
curso;
evento;
vídeo;
páginas paginadas;
páginas em idiomas diferentes.

Para cada template, registre uma URL canônica de teste, os nós esperados, as propriedades críticas e a origem dos dados.

KPIs operacionais

Indicadores úteis:

KPI	Fórmula ou definição
Cobertura elegível	páginas com markup válido ÷ páginas que deveriam possuir o tipo
Erro crítico	itens inválidos ÷ itens detectados
Divergência factual	páginas com diferença entre markup e conteúdo ÷ páginas auditadas
Regressão por deploy	páginas ou templates afetados após uma mudança
Tempo de correção	tempo entre detecção e homologação da solução
Atualização dentro do SLA	alterações refletidas no markup dentro do prazo definido
Search appearance	impressões, cliques e CTR do recurso quando o relatório existir
Conversão assistida	leads ou vendas associados às páginas elegíveis, com as limitações de atribuição documentadas

Evite metas como “aumentar em 30% as citações de IA por causa do schema” sem sistema capaz de detectar, classificar e atribuir essas citações.

Como testar impacto

Quando houver volume suficiente:

selecione páginas comparáveis;
registre período anterior;
não combine a implementação com grandes mudanças de conteúdo, layout e links;
implemente em uma amostra;
aguarde recrawl e reindexação;
compare elegibilidade, search appearance, CTR e conversão;
documente fatores externos;
aceite a possibilidade de efeito nulo.

O Google também recomenda testes antes e depois em algumas páginas para avaliar se o esforço valeu a pena. Mesmo assim, sazonalidade, posição, intenção, concorrência e mudanças na SERP podem confundir o resultado.

Segurança, privacidade e governança

Dados públicos continuam exigindo decisão

JSON-LD fica disponível no código da página e pode ser coletado em escala. Uma informação visível não deve ser automaticamente replicada sem avaliar finalidade, necessidade e risco.

Exemplos sensíveis:

e-mail pessoal de autor;
telefone privado;
endereço residencial;
identificadores fiscais;
nome completo de avaliador;
dados de aluno;
contato interno;
preço interno;
campo administrativo;
informação de cliente;
metadado criado para uso restrito.

A LGPD define dado pessoal como informação relacionada a pessoa natural identificada ou identificável e considera tratamento um conjunto amplo de operações, incluindo utilização, acesso, reprodução, comunicação, difusão e extração. Portanto, publicar dados de Person, autores de Review ou outros indivíduos exige análise de finalidade, base aplicável, necessidade, transparência e segurança. Este guia não substitui avaliação jurídica.

Vazamento por geração dinâmica

O risco aumenta quando o JSON-LD é produzido automaticamente a partir de objetos de banco de dados. Um serializador que recebe o modelo inteiro pode publicar campos nunca destinados ao público.

Controle recomendado:

allowlist explícita;
objetos de transferência específicos para publicação;
revisão de campos novos;
testes que bloqueiem propriedades proibidas;
dados fictícios em staging;
logs sem conteúdo pessoal desnecessário;
aprovação adicional para alterações no mapeamento;
revisão periódica do HTML público.

Injeção e conteúdo de usuário

Campos de review, FAQ, produto, evento ou perfil podem conter texto criado por usuário. Sem serialização segura, esse conteúdo pode quebrar o JSON, fechar a tag de script ou introduzir conteúdo não autorizado.

Medidas:

serializador nativo;
escaping apropriado ao contexto HTML;
sanitização;
limites de tamanho;
tipos validados;
rejeição de URLs não permitidas;
moderação de conteúdo;
testes com payloads adversariais;
política de publicação para conteúdo incentivado ou falso.

Fonte de verdade e responsabilidade

Crie uma matriz:

Entidade/propriedade	Fonte de verdade	Responsável	SLA	Evidência
`Organization.name`	cadastro institucional	direção/marketing	mudança imediata	página institucional
`Person.jobTitle`	perfil de autor	editorial	5 dias úteis	biografia aprovada
`Product.offers.price`	ERP/e-commerce	comercial/tecnologia	minutos ou horas	página e sistema
`Event.eventStatus`	plataforma de eventos	operação	imediato	página do evento
`Article.dateModified`	CMS	editorial	no deploy	histórico de revisão

Quando ninguém é responsável, a obsolescência é apenas questão de tempo.

Versionamento e change management

Registre:

versão do template;
versão do plugin;
versão relevante do Schema.org;
documentação do consumidor consultada;
data da checagem;
tipos e propriedades alterados;
URLs de teste;
evidências antes e depois;
responsável técnico;
aprovador;
rollback;
data da próxima revisão.

Mudanças externas também precisam abrir tarefas internas. A retirada do FAQ rich result em 2026 é um exemplo: não exige necessariamente remoção imediata de todas as marcações, mas exige reavaliação da prioridade, da documentação e da promessa comercial.

POP de implementação e homologação

O procedimento operacional vigente — fases, critérios de aceite, evidências, KPIs e rollback — está documentado de forma independente no POP — Implementação e homologação de JSON-LD (código POP-BA-JSONLD-001).

Este guia permanece como fundamento conceitual e arquitetural. O POP é a orientação executável para descoberta, projeto, implementação, validação, deploy e operação.

Considerações finais

JSON-LD não é um truque de SEO e não deve ser vendido como atalho para GEO. Ele é uma camada de publicação de dados que pode melhorar a explicitação de entidades, conectar informações e habilitar experiências compatíveis. Seu valor cresce quando faz parte de uma arquitetura governada e diminui quando é tratado como um bloco estático copiado de um gerador.

Uma implementação madura começa pelo modelo de negócio e pelo conteúdo real. Em seguida identifica entidades, consumidores e resultados; projeta IDs e relações; conecta o grafo às fontes de verdade; publica com segurança; valida em camadas; monitora por template; mede o que é mensurável; e revisa a estratégia quando os consumidores mudam.

Essa disciplina também protege o projeto contra dois extremos. O primeiro é ignorar dados estruturados por não serem uma garantia de ranqueamento. O segundo é atribuir a eles poderes que a documentação e a evidência não sustentam. Entre os dois está a engenharia: implementar aquilo que tem finalidade, comprovar o que pode ser comprovado e tratar o restante como hipótese.

A base de SEO e autoridade continua indispensável para experiências clássicas e generativas. JSON-LD pode fazer parte dessa base, mas não substitui rastreamento, indexação, conteúdo útil, autoria real, autoridade construída, experiência do usuário, oferta, mensuração ou operação comercial.

JSON-LD melhora o posicionamento de uma página no Google?

JSON-LD não deve ser tratado como uma alavanca direta ou garantida de posicionamento. Ele fornece informações explícitas sobre a página e pode torná-la elegível a recursos compatíveis. O efeito comercial mais mensurável costuma ocorrer quando um rich result altera a apresentação, as impressões ou o CTR, mas nem a elegibilidade garante exibição. Conteúdo, relevância, indexação, concorrência e muitos outros sistemas continuam determinando o desempenho.

Todo site precisa usar Organization, WebSite e BreadcrumbList?

Não existe um conjunto universal obrigatório. Organization é adequado quando há uma organização real a representar; WebSite é importante na home, inclusive para preferência de site name; BreadcrumbList faz sentido quando a página participa de uma hierarquia navegável. A decisão deve considerar tipo de página, conteúdo visível, consumidor, finalidade e custo de manutenção.

É melhor usar um único @graph ou vários scripts JSON-LD?

As duas abordagens podem ser válidas. @graph facilita conexões, reutilização de IDs e governança em sites complexos. Blocos separados podem funcionar bem em páginas simples ou integrações independentes. O ponto crítico é manter entidades e relacionamentos coerentes, sem nós concorrentes ou dados contraditórios.

Ainda vale a pena manter FAQPage depois da retirada do FAQ rich result?

Depende do caso. O tipo continua válido no Schema.org, mas não produz mais o FAQ rich result do Google desde maio de 2026. Sua manutenção só se justifica quando existe finalidade semântica, consumidor identificado ou custo operacional muito baixo. Não há base suficiente para prometer que mantê-lo aumentará citações em sistemas generativos.

Qual é a maneira mais segura de implementar JSON-LD no WordPress?

Primeiro inventarie o que tema e plugins já publicam. Se um plugin como o Yoast já produz um grafo, prefira estender sua arquitetura e preservar seus identificadores em vez de instalar outro gerador concorrente. Use fontes de verdade, serialização segura, staging, validação da URL renderizada, evidências de homologação, monitoramento e rollback. O método mais seguro é aquele que mantém o markup correto ao longo do tempo, não apenas no dia da instalação.

Referências

Schema.org: Documentação e vocabulário, Propriedade inLanguage, Propriedade sameAs.

W3C: JSON-LD 1.1.

Google Search Central: Introdução a dados estruturados, Diretrizes gerais de dados estruturados, Galeria de recursos suportados, Ferramentas de teste, Recursos de IA e websites, Dados estruturados gerados com JavaScript e GTM.

Google Search Central: Organization, Site names e WebSite, Article e autoria, ProfilePage, Course list, BreadcrumbList, LocalBusiness, Product, Event, JobPosting, VideoObject, QAPage.

Google Search Central: Changelog da documentação, Retirada do sitelinks search box, Retirada de recursos de structured data menos utilizados.

Bing Webmaster Tools: Inspeção de URL, Structured data.

Yoast Developer: Schema API.

WordPress Developer Resources: wp_json_encode.

Presidência da República: Lei Geral de Proteção de Dados Pessoais.