Schema JSON-LD e llms.txt: implementação e limites

JSON-LD descreve fatos da página com um vocabulário estruturado; llms.txt oferece um índice em Markdown para consumidores que adotem essa proposta. Use o primeiro quando houver dados relevantes para marcar. Avalie o segundo pela necessidade de acesso à documentação, com um responsável por mantê-lo atualizado.

Os formatos têm usos diferentes e não precisam ser implantados como um pacote. Um artigo pode ser encontrado e citado sem llms.txt, sem @graph e sem uma coleção extensa de tipos Schema.org. Para o Google, não há marcação especial exigida para busca generativa, e llms.txt não interfere em visibilidade ou ranking.

A implementação começa pela informação publicada: quem assina, qual página descreve a empresa e quais datas são verdadeiras. Um bloco tecnicamente válido que inventa uma oferta ou desatualiza o autor piora a documentação que deveria organizar.

Use identificadores estáveis para referenciar a mesma entidade e inclua somente as propriedades que consegue manter. @graph reúne vários objetos num documento; ele facilita a organização, mas não é a única forma válida de fazer referências em JSON-LD.

O exemplo hipotético abaixo descreve uma empresa e um artigo publicado por ela. Substitua nomes, endereço e data pelos dados reais. A empresa precisa estar identificada no site e a página do artigo deve exibir a informação correspondente.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://exemplo.com/#empresa",
      "name": "Empresa Exemplo",
      "url": "https://exemplo.com/"
    },
    {
      "@type": "Article",
      "@id": "https://exemplo.com/guia/#artigo",
      "url": "https://exemplo.com/guia/",
      "headline": "Como escolher uma integração",
      "datePublished": "2026-10-06",
      "publisher": {
        "@id": "https://exemplo.com/#empresa"
      }
    }
  ]
}

Acrescente o autor real e outras propriedades recomendadas para seu tipo de conteúdo. dateModified deve acompanhar uma alteração editorial efetiva, enquanto datePublished preserva a publicação original. Um campo ausente é preferível a um dado inventado para satisfazer uma lista.

Reserve sameAs para referências que identifiquem a mesma entidade. O perfil oficial da empresa é diferente de um texto que apenas a menciona. Evite associar uma pessoa a uma organização com o mesmo identificador: são objetos distintos.

Publique o JSON-LD como script do tipo application/ld+json no HTML da página que ele descreve. O Google aceita o bloco no head ou no body. No Next.js, a documentação mostra implementação em layout ou page; a escolha depende do alcance dos dados.

Um layout pode concentrar dados compartilhados, e a página pode declarar seu próprio artigo ou produto. Antes de adicionar outro componente, confira se o sistema de conteúdo já emite marcação. Duas declarações contraditórias sobre preço ou autor precisam ser corrigidas, mesmo que ambas tenham sintaxe válida.

Gere os dados estruturados a partir da mesma origem usada pelo conteúdo visível. Ao inserir JSON em HTML, use uma serialização segura para que valores de texto não encerrem o elemento script. A documentação do Next.js recomenda tratar esse risco, inclusive escapando o caractere menor que.

A aprovação exige abrir a página publicada, localizar os blocos application/ld+json e confrontar seus valores com o texto visível. Compilar TypeScript ou visualizar o componente no editor não substitui essa conferência.

Llms.txt faz sentido quando um agente, uma integração ou um fluxo de documentação consegue usá-lo para localizar material relevante. Defina essa finalidade antes de duplicar conteúdo. Um arquivo extenso abandonado acrescenta outra versão da mesma informação para manter.

A versão dois da proposta, atualizada em agosto de 2026, admite o arquivo na raiz ou em um subdiretório, cobrindo os endereços daquele caminho. Um índice em /docs/llms.txt, por exemplo, pode tratar apenas da documentação técnica. Não é um controle de permissão nem uma declaração automática de licença.

# Empresa Exemplo

> Documentação de integração para equipes técnicas.

Os guias descrevem as funções disponíveis no produto.

## Integração

- [Autenticação](https://exemplo.com/docs/autenticacao.md): formas de acesso.
- [Erros](https://exemplo.com/docs/erros.md): códigos e recuperação.

O exemplo é hipotético: publique primeiro os destinos e teste cada endereço antes de criar o índice. Mantenha o detalhe nas páginas ligadas. O arquivo serve como caminho de consulta, sem transformar uma descrição comercial em instrução para o assistente recomendar a empresa.

Escolha uma origem para cada fato e gere o índice a partir do catálogo de páginas sempre que isso reduzir duplicação. O front-matter, bloco de metadados no início de alguns arquivos Markdown, não é uma exigência universal da proposta llms.txt.

A proposta descreve relações de descoberta como rel="describedby" para o índice e rel="alternate" com type="text/markdown" para a versão Markdown de uma página. Adote essas relações apenas se as versões indicadas existirem e corresponderem ao conteúdo público.

Inclua na rotina de publicação a retirada de links que perderam utilidade, a atualização de destinos redirecionados e a correção de informação vencida. Uma data de atualização serve à manutenção; ela não demonstra que um assistente leu aquela versão.

Se existir cache, uma cópia temporária na infraestrutura, confira quanto tempo a versão antiga permanece disponível. Escolha esse período pela frequência real de mudança e pelo mecanismo de invalidação. Não aumente o catálogo sem definir quem responde pelos arquivos derivados.

Valide três coisas separadamente: o que o servidor entrega, se o formato pode ser interpretado e se a informação está correta. Um status 200 não basta: o endereço pode devolver uma página de erro com esse código.

1. Baixe o HTML da página publicada e o arquivo de índice, se houver.
2. Confira o status final, os redirecionamentos e o tipo de conteúdo.
3. Abra o corpo recebido e procure o título e uma informação exclusiva.
4. Teste o JSON-LD no Schema Markup Validator e, quando aplicável, no Rich Results Test.
5. Abra cada link do índice e compare os fatos com a página original.
6. Registre o resultado, o responsável e a data do próximo teste.

curl -L -D pagina-cabecalhos.txt -o pagina.html https://exemplo.com/guia/
curl -L -D indice-cabecalhos.txt -o indice.txt https://exemplo.com/docs/llms.txt

Use curl.exe no Windows quando necessário. Esses comandos fazem uma requisição com corpo, evitando depender apenas de HEAD, que pode receber tratamento diferente no servidor. Não confunda uma página de desafio do firewall com o documento que queria baixar.

O benefício imediato verificável é publicar dados corretos e evitar versões divergentes. Para avaliar uso do índice, acompanhe requisições nos registros do servidor, considerando identificação legítima, erros e volume. Um nome de robô no registro não prova utilização do conteúdo numa resposta.

Se quiser medir impacto sobre respostas, preserve perguntas e condições da coleta antes e depois da mudança. Atualizações de modelos, concorrentes e outras páginas continuam sendo explicações possíveis para a diferença. Não atribua um ganho inteiro ao JSON-LD ou ao índice com base em uma comparação isolada.

Hoje, escolha uma página e conclua a validação de ponta a ponta antes de ampliar a implantação. O diagnóstico de GEO e autoridade temática do Portal Leadlovers 2026 ajuda a decidir se a próxima tarefa é técnica ou editorial.