@id no JSON-LD para ligar entidades entre domínios

O que o @id faz em um grafo JSON-LD?

O @id é o identificador global de um nó no JSON-LD, e dois nós com o mesmo @id são a mesma coisa. A JSON-LD 1.1, recomendação do W3C desde 16 de julho de 2020, define o @id como a palavra-chave que identifica objetos de nó por IRI ou por identificador de nó em branco. Quando o @id falta, o processador cria um nó em branco, como o _:b0 dos exemplos da especificação, que só existe dentro daquele documento e não pode ser citado de fora.

A mesma especificação define a referência de nó: um objeto que contém apenas o @id e aponta para um nó descrito em outro lugar. É esse mecanismo que deixa um BlogPosting dizer que o autor é {"@id": "https://lucasferraz.com/#person"} sem repetir nome, foto e perfis. Para a entidade ter um único endereço, o identificador precisa ser estável e igual em todo lugar em que ela aparece.

A mesma especificação define a referência de nó: um objeto que contém apenas o @id e aponta para um nó descrito em outro lugar.

Lucas Ferraz, especialista em SEO

A armadilha da IRI relativa

Uma IRI relativa no @id muda de valor a cada página em que aparece. A especificação resolve referências relativas contra a IRI base do documento, que normalmente é a URL da própria página. O exemplo de ProfilePage da documentação do Google usa "#main-author", o que funciona dentro de uma página só. Colado em outra URL, o mesmo "#main-author" vira outro identificador.

Para ligar a mesma entidade entre páginas, e mais ainda entre domínios, o @id precisa ser absoluto.

Página-casa e stub

A página-casa é a única URL que carrega o nó completo de uma entidade, e as outras páginas levam só um stub. A Schema App chama esse endereço de entity home e recomenda usar a URL canônica da entidade, ou um fragmento dela, como @id. Eu sigo a mesma lógica com uma regra extra: um @graph por página, nó completo só na casa, e em todas as outras um stub com quatro chaves.

{
  "@type": "Person",
  "@id": "https://lucasferraz.com/#person",
  "name": "Lucas Ferraz",
  "url": "https://lucasferraz.com/"
}

O stub resolve dois problemas. Cada página continua legível sozinha, com tipo e nome, mesmo para quem não segue o identificador. E os fatos que mudam, como sameAs, cargo e foto, ficam em um só lugar, o que elimina a divergência entre cópias.

A referência solta que vira nó fantasma

Uma referência solta é um @id citado no grafo sem nenhum nó que o descreva naquela página. Quem lê o grafo encontra só o identificador, sem tipo e sem nome, e passa a ter um nó fantasma que não diz o que é. O erro aparece quando um template aponta o author para um @id e esquece de incluir o stub, ou quando o identificador muda em um lugar e não no outro.

Entre as checagens do teste de deploy deste site, três tratam disso: nó sem @id, @id repetido dentro do mesmo grafo e referência solta. Referências para o domínio da agência e para DOI ficam liberadas, porque essas entidades têm casa fora daqui. Se o Googlebot visita a URL do @id para completar o grafo é algo que o Google não documenta. A Schema App relata ter observado esse rastreamento desde 2017, e trato isso como indício de fornecedor, sem base para depender dele.

Por que os dois domínios deixaram de dividir o @id?

A pessoa Lucas Ferraz tem, desde 24 de setembro de 2026, um @id em cada domínio, ligados por sameAs e url. Em 23 de setembro, a casa da pessoa passou a ser a Home deste site, marcada como ProfilePage, e o tema da agência trocou o identificador para https://lucasferraz.com/#person. No dia seguinte desfiz a troca. O Google processa o schema por página e usa o @id como cola interna do grafo, então dois domínios emitindo o mesmo identificador passam a reivindicar o mesmo nó, e qualquer diferença entre as duas cópias vira divergência.

A regra atual é uma entidade, um nó completo em cada site, com @id do próprio domínio. A agência identifica a pessoa por /autor-lucas-ferraz/#personLucasFerraz e este site por https://lucasferraz.com/#person, e os dois nós se apontam no sameAs, com os mesmos fatos. A exceção é o identificador neutro de registrador: o estudo com DOI usa o próprio DOI como @id nos dois domínios, porque nenhum dos dois é dono dele. É a parte do trabalho de entidade no Knowledge Graph que depende só do próprio código, e a mesma lógica vale para o knowsAbout ligado ao glossário.