Construindo dados estruturados que sistemas de pesquisa e IA podem analisar

Os dados estruturados respondem a uma pergunta que as máquinas não conseguem adivinhar com segurança em prosa: do que se trata esta página e quem está por trás dela? JSON-LD é o formato que a maioria dos desenvolvedores usa para respondê-la, porque fica em uma única tag de script em vez de ser interligado pelo HTML. O SitePoint já possui um guia prático para adicionando marcação de esquema com JSON-LD que cobre a sintaxe, configurações de estrutura e validadores.

Este artigo aborda um problema diferente: descrever a mesma entidade de forma consistente em todo o site, para que os mecanismos de pesquisa e os sistemas de IA possam dizer que as peças pertencem umas às outras, e verificar se sua marcação realmente faz isso.

Descreva as entidades uma vez e depois referencie-as

Um snippet de nível de página descreve um artigo. Mas um artigo tem um autor e um editor, e o editor é uma organização que existe em todo o site. Se cada página descreve de forma um pouco diferente, “Example Studio” em uma página e “Example Studio Ltd” em outra, um analisador terá que adivinhar se essas são a mesma organização.

A correção é aquela que você usaria em um banco de dados: dê a cada entidade um identificador estável, defina-o uma vez e aponte para ele de qualquer outro lugar. Em JSON-LD esse identificador é @ide um @graph permite que uma tag de script contenha vários nós conectados.

HTML

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": (
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "Example Studio",
      "url": "https://example.com/",
      "sameAs": (
        "https://www.linkedin.com/company/example-studio",
        "https://github.com/example-studio"
      )
    },
    {
      "@type": "Article",
      "@id": "https://example.com/blog/json-ld/#article",
      "headline": "JSON-LD for Developers",
      "author": { "@id": "https://example.com/#org" },
      "publisher": { "@id": "https://example.com/#org" }
    }
  )
}
script>

Três detalhes são importantes. O @id é um identificador, não necessariamente uma página que existe, e um URL em seu próprio domínio com um fragmento, como https://example.com/#orgé uma convenção comum. Uma referência é escrita como um objeto que contém apenas um @idque informa ao processador que o nó está definido em outro lugar no gráfico. E sameAs lista páginas que identificam a mesma entidade: schema.org define isso como o URL de uma página de referência que indica inequivocamente a identidade do item. Uma página de perfil oficial se qualifica. Uma notícia sobre a organização, não.

Construa o gráfico a partir de uma fonte de verdade

Desvios JSON-LD escritos à mão. O nome da organização muda no rodapé e ninguém atualiza a marcação. Guia de Saifullah Adenwalla para tratando metadados de SEO como um contrato de aplicação mostra como gerar metadados e dados estruturados a partir dos mesmos dados de rota que renderizam a página visível, e a mesma ideia se aplica às entidades.

Mantenha um registro para cada entidade na configuração, com seu nome, URL, @id e sameAs lista e faça com que o gráfico de cada página seja lido a partir dela. Os fatos na marcação podem diferir da página visível somente quando o registro em si estiver errado e houver um local para corrigi-lo.

Verifique se cada referência resolve

Um erro de digitação @id não gera um erro. O JSON permanece válido, os validadores permanecem silenciosos e a referência aponta silenciosamente para nada. Uma breve verificação detecta isso coletando os identificadores definidos no gráfico e relatando qualquer referência que não tenha definição:

javascript

function findUnresolvedReferences(graph) {
  const defined = new Set(
    graph.filter((node) => node('@type')).map((node) => node('@id'))
  );
  const unresolved = new Set();

  const visit = (value) => {
    if (Array.isArray(value)) return value.forEach(visit);
    if (value && typeof value === 'object') {
      const keys = Object.keys(value);
      if (keys.length === 1 && keys(0) === '@id') {
        if (!defined.has(value('@id'))) unresolved.add(value('@id'));
      }
      Object.values(value).forEach(visit);
    }
  };

  graph.forEach(visit);
  return (...unresolved);
}

Defina entidades como nós de nível superior no gráfico para que sejam coletadas. Uma página que faça referência a uma entidade definida em outro lugar será sinalizada; portanto, inclua o nó dessa entidade no gráfico de cada página, gerado a partir do registro compartilhado, ou adicione o identificador a uma lista permitida.

Execute a verificação no gráfico de cada página em seus testes ou CI e, em seguida, use o Validador de marcação de esquema para confirmar se os tipos e propriedades são reconhecidos. Um gráfico válido não é o mesmo que um gráfico preciso, portanto compare também a saída com a página visível. A marcação deve descrever o que os visitantes podem realmente ver.

O que os dados estruturados fazem e o que não fazem na pesquisa de IA

É aqui que os artigos sobre o tema tendem a exagerar, por isso vale a pena ser preciso. Guia do Google para otimização de recursos generativos de IA diz que dados estruturados não são necessários para pesquisa generativa de IA e que não há marcação especial do schema.org para adicionar. Ele ainda recomenda o uso de dados estruturados como parte de uma estratégia geral de SEO, porque ajuda na elegibilidade para resultados aprimorados.

Portanto, trate JSON-LD como uma descrição precisa e legível por máquina de suas entidades, não como uma opção que produz citações. Outros sistemas de IA publicam pouco sobre como leem as páginas, o que torna qualquer afirmação sobre eles uma hipótese a ser testada em seu próprio site.

Alguns editores argumentam que dados de entidades consistentes em várias fontes facilitam a identificação de uma empresa pelos sistemas de IA. O guia do DirJournal para o pilha de confiança da entidade estabelece uma dessas estruturas. O DirJournal é um diretório de empresas e descreve seu próprio teste de 41 listagens como uma associação temporal, não um teste causal controlado; portanto, trate a afirmação como uma hipótese.

Uma maneira prática de usar essa ideia é testá-la. Salve os prompts executados, com suas datas, registre quais URLs são citados e compare os resultados antes e depois de alterar sua marcação.

Erros Comuns

Marcando fatos que a página não mostra. Os dados estruturados devem representar a página em que aparecem. Alegações que os visitantes não conseguem ver tornam a marcação enganosa.

Descrever uma entidade de duas maneiras. Dois nós com nomes ou URLs diferentes para a mesma organização recriam a ambiguidade que @id destina-se a remover.

Preenchimento igual ao. Links para um perfil que pertence a outra pessoa, para um artigo sobre a entidade ou para um nome que mudou após uma reformulação da marca enfraquecem o sinal. Verifique os destinos em uma programação.

Tratando o gráfico como concluído. Nomes, fundadores e URLs de perfil mudam. A geração do gráfico a partir de um registro mantém essas atualizações em uma única edição.

Perguntas frequentes

O JSON-LD garante que as ferramentas de pesquisa de IA citarão meu site?

O Google afirma que dados estruturados não são necessários para seus recursos de IA generativos e que não existe nenhuma marcação especial, e outros sistemas documentam muito pouco. Use JSON-LD para descrever suas entidades com precisão e medir você mesmo os resultados.

Para onde deve ir o script JSON-LD?

Em uma tag de script com o tipo application/ld+jsonna cabeça ou no corpo. A marcação renderizada pelo servidor é a mais simples, porque está na resposta inicial. O Google também pode ler JSON-LD injetado dinamicamente, mas verifica a saída final renderizada em vez de presumi-la.

Um @id precisa ser uma página real?

Não. Tem que ser um identificador único e estável. Uma URL em seu próprio domínio com um fragmento é uma convenção comum e não precisa retornar uma página.

Cada página deve repetir o nó da organização?

Qualquer abordagem pode funcionar, mas um gráfico independente em cada página é mais fácil de testar. A verificação de referência passa sem exceções e cada página pode ser validada por si só. Gere o nó a partir do registro compartilhado para que as cópias não possam desviar.

Resumo

JSON-LD é mais útil quando descreve entidades e não apenas páginas: defina cada entidade uma vez com um valor estável @idfaça referência a ele em qualquer outro lugar e gere o gráfico a partir de uma fonte de verdade. Uma pequena verificação de referência e um validador de esquema detectam os erros que parecem válidos, mas não apontam para lugar nenhum. Para pesquisa de IA, a posição documentada é modesta, porque não são necessários dados estruturados e não existe nenhuma marcação especial, portanto, descreva suas entidades com precisão e teste qualquer reivindicação maior em suas próprias páginas.