Seu site pode ter schema em todas as páginas e, ainda assim, um mecanismo de IA não conseguir identificar a qual site aquela WebPage pertence nem quem o administra. O problema não é a quantidade de marcações, mas o fato de elas não se reconhecerem. Criar Organization, WebSite e WebPage como blocos isolados de JSON-LD equivale a entregar à máquina três cartões de visita sem nenhuma ligação entre si. @graph cria essa ligação e permite que a IA compreenda, de uma só vez, a estrutura de entidades de todo o site.
Por que schemas desconectados impedem a IA de compreender seu site
Na maioria dos sites, o schema é gerado automaticamente por plugins ou modelos do CMS: Organization na página inicial, Article nos artigos e Product na página de preços. Analisado separadamente, cada bloco pode estar correto e até passar no Rich Results Test. O problema aparece quando a máquina tenta responder: “Quem publicou este artigo e essa fonte é confiável?”. Ela encontra vários objetos soltos, sem um campo que indique que o publisher de Article é a mesma Organization definida na página inicial. Para mecanismos de resumo e respostas por IA, uma parte importante da decisão de citar uma fonte é conseguir associar o conteúdo a uma organização real e verificável. Sem essa relação, o conteúdo deixa de parecer uma informação oficial da empresa e passa a ser apenas um texto de origem desconhecida.
O que @graph faz, na prática
@graph é um campo de nível superior do JSON-LD. Seu valor é um array capaz de reunir vários objetos de entidade. Assim, entidades que normalmente seriam distribuídas por diversas tags script passam a compartilhar o mesmo arquivo e o mesmo namespace. O ganho principal não está apenas em “colocar tudo junto”, mas em permitir que os objetos façam referência uns aos outros por meio de @id. Você declara um @id em Organization e informa esse mesmo @id no campo publisher de WebSite. Com isso, a máquina entende que ambos apontam para a mesma entidade, sem que seja necessário copiar todo o objeto Organization. Definir uma vez e referenciar em todos os lugares é um princípio básico dos grafos de conhecimento. O schema.org oferece suporte a @graph justamente para que uma página expresse relações entre entidades, em vez de apenas listar atributos.
Uma única tag script comporta todo o @graph da página. Isso também resolve um problema antigo: três plugins diferentes declarando a mesma Organization, cada um com atributos que podem entrar em conflito. Com @graph, a empresa aparece uma única vez, torna-se a fonte única de verdade para todo o site e exige manutenção em apenas um ponto.
@id: um endereço estável para cada entidade
@id é a base de toda essa implementação. Trata-se de uma string de identificação única em todo o domínio, normalmente formada por uma URL seguida de um fragmento com cerquilha, como https://example.com/#organization. Esse endereço não precisa necessariamente abrir no navegador: sua função é identificar, não servir como link. Desde que a mesma entidade use sempre o mesmo @id em todo o site, a IA consegue agrupar sob um único sujeito as informações distribuídas por várias páginas. Quando o mesmo @id aparece na página inicial, em um artigo e na página de preços, a máquina pode reunir as descrições da empresa e formar um registro de entidade mais completo e difícil de falsificar.
- Para Organization, use a raiz do domínio seguida de um fragmento, como https://example.com/#organization. O valor deve ser único em todo o site e apontar sempre para a mesma empresa.
- Para WebSite, use a raiz do domínio seguida de #website para representar o site como uma entidade completa.
- Para a WebPage de cada página, use “URL da página + #webpage”. O valor muda de uma página para outra.
- Padronize os nomes dos fragmentos com a equipe (#organization, #website, #webpage). Não use #org hoje e #company amanhã.
- Depois que um @id estiver em produção, não o altere sem necessidade. A mudança equivale à criação de uma nova entidade e rompe todas as associações acumuladas anteriormente.
Como as três entidades apontam umas para as outras
A direção das conexões segue uma lógica: da entidade mais específica para a mais ampla, da página para a organização responsável. WebSite usa publisher para apontar para Organization e declarar que o site é operado por aquela empresa. Cada WebPage usa isPartOf para apontar para WebSite e informar que faz parte daquele site. Se a página tratar da própria empresa, como nas seções “Sobre nós” ou de preços, use about ou mainEntity para fazer referência à Organization. Nos artigos, faça também o publisher de Article apontar para o @id dessa Organization. Assim, a relação de publicação fica completa.
Exemplo completo e pronto para implementar
Insira o @graph abaixo no <head> da página. Uma única tag script comporta as três entidades: cada uma declara seu @id uma vez e usa @id para fazer referência às demais, sem duplicar Organization. Na prática, Organization e WebSite podem ser extraídos para um modelo compartilhado por todo o site e declarados uma única vez. Já WebPage pode receber dinamicamente url, name e @id de cada página. { "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://example.com/#organization", "name": "Example company", "url": "https://example.com/", "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" }, "sameAs": [ "https://www.linkedin.com/company/example", "https://x.com/example" ] }, { "@type": "WebSite", "@id": "https://example.com/#website", "url": "https://example.com/", "name": "Example", "publisher": { "@id": "https://example.com/#organization" } }, { "@type": "WebPage", "@id": "https://example.com/pricing#webpage", "url": "https://example.com/pricing", "name": "Pricing plan", "isPartOf": { "@id": "https://example.com/#website" }, "about": { "@id": "https://example.com/#organization" } } ] }
Os quatro erros mais comuns
- @id inconsistente: a página inicial usa #organization, mas o publisher do artigo recebe uma URL diferente ou sem o fragmento após a cerquilha. A máquina interpreta os valores como duas empresas distintas.
- Objeto completo no lugar da referência: todo o objeto Organization é reescrito dentro de publisher. Isso cria duas cópias da mesma entidade, cujos atributos podem entrar em conflito.
- Entidades soltas: WebPage não tem isPartOf e Article não tem publisher. Embora os objetos sejam válidos, permanecem desconectados da entidade principal.
- URL variável usada como @id: quando uma URL com parâmetros de rastreamento ou de sessão muda, uma nova entidade é criada e todas as associações precisam ser reconstruídas.
Para conquistar a confiança da IA, você não precisa de mais marcações, e sim de referências claras entre as entidades.
Antes de publicar, verifique estes três pontos
Publicar o schema não significa que ele esteja correto. Primeiro, cole o @graph completo no Rich Results Test ou no Schema Markup Validator e confirme que não há erros de sintaxe destacados em vermelho. Depois, faça uma verificação que muita gente ignora: localize cada @id referenciado e compare os valores um a um para confirmar que todos estão realmente definidos no mesmo grafo. Não aponte para identificadores inexistentes. Por fim, carregue a página no navegador, examine o HTML renderizado e confirme que o script foi de fato incluído. Muitos sistemas de SSR ou CMS descartam silenciosamente essa marcação nessa etapa. A conexão entre entidades é uma frente de alto retorno no GEO técnico: não exige muitas horas de trabalho, mas influencia diretamente a disposição da IA de tratar seu site como uma fonte confiável. Se você não souber se Organization, WebSite e WebPage estão realmente conectados ou se a relação de publisher foi interrompida, agende um diagnóstico de GEO de 30 minutos. Vamos capturar o HTML renderizado do seu site e indicar, uma a uma, as conexões ausentes.