JSON-LD explicado para sites pessoais

 (hawksley.dev)
2 pontos por GN⁺ 8 시간 전 | 1 comentários | Compartilhar no WhatsApp
  • Mesmo sites pessoais podem melhorar a forma como rastreadores entendem a relação entre páginas, pessoas e textos ao incluir dados estruturados, o que pode aprimorar prévias de links e a qualidade da exibição nos resultados de busca
  • A implementação consiste em definir @context como Schema.org dentro de <script type="application/ld+json"> no <head> e organizar nós como WebSite, Person e BlogPosting em @graph
  • Ao usar o mesmo @id, rastreadores da web podem mesclar propriedades de nós entre várias páginas, mas scrapers ou LLMs que leem apenas uma página não fazem essa mesclagem
  • Na página raiz, o básico é usar WebSite, ProfilePage e Person; em páginas de blog, projetos ou listas, adicionam-se Blog, BlogPosting, SoftwareApplication, CollectionPage e BreadcrumbList conforme o caso
  • Os campos sameAs de Person, breadcrumb da página e image, license e datas do texto são usados diretamente para identificação da pessoa, caminho exibido nos resultados, prévia do conteúdo, condições de uso e avaliação de atualidade

Função do JSON-LD e estrutura básica

  • JSON-LD é a sigla de JSON Linked Data, um formato para adicionar dados estruturados a páginas da web
  • Ele ajuda rastreadores a entender a estrutura semântica do site e pode contribuir para prévias de links mais ricas e uma possível melhora no ranqueamento em buscas
  • Para adicioná-lo a uma página, insere-se no <head> um script no seguinte formato
    • <script type="application/ld+json"> declara o tipo MIME como application/ld+json
    • Quando esse tipo é especificado, o mecanismo JavaScript do navegador não o executa
    • Rastreadores especializados, como o Googlebot, localizam esse elemento e fazem o parsing do conteúdo

@context, @graph e IDs de nós

  • @context define o contexto seguido pelos dados JSON-LD, e os rastreadores da web usam Schema.org como padrão
  • O Schema.org define pares chave-valor válidos que podem ser usados no JSON
  • Um documento JSON-LD pode ser visto como um grafo direcionado com rótulos, e os dados ficam armazenados em @graph
  • O grafo pode conter vários nós, conectados entre si por ligações direcionadas
  • Cada nó é composto pelos seguintes elementos
    • @type: indica o que o nó representa. Ex.: WebSite, SoftwareApplication
    • @id: identificador do nó, normalmente uma URL com um hash exclusivo no final
    • propriedades: pares chave-valor que descrevem as características do nó
  • Rastreadores da web podem mesclar, entre várias páginas, as propriedades de nós que compartilham o mesmo @id
  • Já scrapers ou LLMs que leem apenas uma página não mesclam propriedades, então essa diferença deve ser considerada ao reutilizar JSON-LD em várias páginas
  • Para @id, recomenda-se usar um hash ao final da URL para identificar o nó de forma única, como #website

Nós para descrever o site e as páginas

  • WebSite

    • WebSite guarda os metadados do site e oferece pistas para que rastreadores decidam como ele deve ser exibido
    • Na página raiz, é possível usar uma versão detalhada com propriedades como url, name, alternateName, description, inLanguage, publisher e image
    • Não é necessário colocar o nó WebSite completo em todas as páginas
    • A página raiz do domínio pode ser detalhada, enquanto nas demais basta uma versão resumida com @type, @id, url e name
    • Essa versão resumida fornece o contexto necessário para que rastreadores que leem apenas uma página identifiquem corretamente o nome do site

  • WebPage

    • WebPage representa a própria página atual, ou seja, a página física em HTML
    • Deve ser diferenciado de tipos de conteúdo como BlogPosting; WebPage se refere à página que contém esse conteúdo
    • Entre as propriedades de exemplo estão url, isPartOf, name, inLanguage e breadcrumb
    • ProfilePage e CollectionPage são subtipos mais específicos de WebPage
    • Subtipos menos comuns podem ser consultados na definição de WebPage do Schema.org

Identificação pessoal e página de perfil

  • Person

    • Recomenda-se incluir um nó Person em todas as páginas de um site pessoal
    • Person indica quem é o dono do site e é usado como parte de alguns sinais de qualidade de conteúdo do Google
    • Rastreadores de LLM também estão usando cada vez mais informações de Person para decidir quem citar nas respostas
    • Ao contrário de WebSite, Person é um contexto importante o suficiente para estar presente em todas as páginas
    • As propriedades mais importantes são as seguintes
      • url: aponta para a página raiz e ancora o nó
      • name, givenName, familyName: deixam o nome claramente definido
      • image: sempre que possível, use uma foto da pessoa ou um logotipo relacionado para vincular uma imagem oficial
      • sameAs: informa aos rastreadores outros perfis, ajudando na identificação da pessoa
    • sameAs é especialmente útil para distinguir homônimos quando o nome é comum, e também serve para construir uma representação em grafo de conhecimento distribuída por várias páginas
    • Outras propriedades de Person ajudam a adicionar detalhes, mas não são obrigatórias, e reduzi-las tende a ter pouco impacto

  • ProfilePage

    • ProfilePage representa uma página do site sobre uma pessoa específica
    • Se a página inicial apresenta você, ela pode ser usada ali; se houver uma página separada de about, pode ser mais apropriado colocá-lo nela
    • É importante conectá-la ao nó mais amplo WebSite por meio de isPartOf
    • mainEntity informa aos rastreadores de quem aquela página trata
    • dateCreated e dateModified são úteis como sinais de atualidade para rastreadores, mas não há grande motivo para se preocupar se o site não os fornecer facilmente

Projetos e indicação de caminho

  • SoftwareApplication

    • Se uma página apresenta um software, vale a pena usar um nó SoftwareApplication para registrar os metadados desse software
    • Tipos mais específicos incluem MobileApplication, WebApplication e VideoGame
    • A propriedade url deve apontar para onde o projeto está publicado
    • Um exemplo seria uma página de distribuição como o crates.io
    • sameAs é usado para outras páginas ligadas ao projeto, como um repositório de código-fonte
    • Valores válidos para applicationCategory podem ser consultados na definição de SoftwareApplication do Google
    • Mesmo em projetos FOSS, é preciso incluir offers e definir o preço como 0

  • BreadcrumbList

    • BreadcrumbList é amplamente útil em todas as páginas, exceto a página raiz
    • Ele representa o caminho de classificação da página, que não precisa ser igual ao caminho real da URL
    • Pode ser usado para controlar como mecanismos de busca exibem o caminho de uma determinada página
    • Se a estrutura de caminhos do site já for curta, o ganho desse nó é pequeno e ele pode ser omitido
    • Em sites com caminhos longos, BreadcrumbList é útil para encurtar o caminho mostrado nos resultados de busca

Páginas de lista, blog e posts

  • CollectionPage

    • CollectionPage é um subtipo de WebPage usado principalmente em páginas que reúnem listas
    • Exemplos incluem uma página /elsewhere/ que reúne outros perfis ou uma página /blog/ com a lista de posts do blog
    • about pode ser usado para conectar o nó Person relacionado
    • breadcrumb deve necessariamente apontar para o BreadcrumbList correto da página atual

  • Blog

    • O nó Blog é adicionado à página de índice ou à home do blog
    • Ele atua como um nó intermediário entre WebSite e cada BlogPosting
    • dateModified é útil como sinal de atualidade, mas pode ser omitido se não for fácil fornecê-lo
    • license informa aos rastreadores em que condições os textos podem ser usados
    • Em sites pessoais, publisher pode ser definido como Person em vez de Organization
    • A documentação do Google agora também aceita Person como valor válido, o que pode ser mais preciso para sites pessoais

  • BlogPosting

    • BlogPosting deve ser incluído em todos os posts de blog publicados
    • Ele fornece informações adicionais para que rastreadores representem o texto com mais precisão
    • Pode ser usado para posicionamento mais preciso e detalhes mais ricos nos resultados de busca
    • Em um site pessoal, não há problema em author e publisher apontarem para o mesmo nó Person
    • É recomendável alinhar a propriedade image com a imagem OG já usada na prévia de links do post
    • license pode ser usada para indicar as condições de uso do texto

Implementação mínima e critérios de adoção

  • O JSON-LD necessário para um site pessoal pode ser montado seletivamente de acordo com o tipo de página
  • Mesmo em um site estático sem etapa de build, já é possível obter benefícios adicionando pelo menos os seguintes nós à página raiz
    • WebSite
    • ProfilePage
    • Person
  • Se houver um blog, podem ser adicionados Blog e BlogPosting, e em páginas de lista de posts ou de perfis externos pode-se usar CollectionPage
  • Em páginas de apresentação de projetos, pode-se usar SoftwareApplication, e em páginas que não sejam a raiz vale considerar BreadcrumbList

Leituras relacionadas

1 comentários

 
GN⁺ 8 시간 전
Comentários no Hacker News

  • Fazendo uma analogia, parece lutar a guerra passada de novo
    Do ponto de vista do meu site na WWW, o Google agora mostra lá em cima um resumo longo gerado por LLM e misturado com erros, em vez de mandar as pessoas para o meu texto de verdade
    Conseguir um nome de exibição bonitinho em vez de um “breadcrumb” ou do domínio não resolve a realidade de que o Google está rebaixando a prioridade de mandar bem ou mal esses elementos
    No fim, estamos gastando esforço demais em algo que quem visita o site diretamente nunca vai ver, e que para quem usa o Google fica difícil de achar, empurrado para baixo por uma versão cada vez mais moldada por LLM do próprio Google

    • Se queremos um mundo em que esse tipo de dado tenha significado, primeiro é preciso plantar a semente
      Mesmo que o Google não use, se a internet como um todo adotar esse tipo de metadado, isso cria um terreno fértil para concorrentes oferecerem alternativas sem depender de raspagem por LLM
      Ceder ao Google só fortalece o domínio dele, aumenta a barreira de entrada para concorrentes e empurra todos eles a usar a mesma tecnologia
    • É exatamente isso. Nossa empresa agora aparece assim na busca do Google:
      empresa de TI sediada em $STATE, especializada em criar fluxos de trabalho práticos de IA e soluções de gestão da informação para empresas do meio-oeste. Opera com um modelo ágil de contratos de preço fixo, evitando o inchaço típico de empresas enterprise e focando em entregar resultados concretos
      Eu nem sabia que agora oferecíamos fluxos de trabalho práticos de IA
      E ainda mistura o nome de um concorrente com nome parecido, mas claramente diferente, e me coloca como executivo. A única sorte é que o concorrente esconde os contatos atrás de um formulário de “agendar consulta”, então só os nossos contatos aparecem
    • Agora eu também não permito mais que o Google rastreie e indexe meu site
    • Agora o Google também entrou na lista de quem recebe um zipbomb de 10GB quando um bot entra no site
      Neste momento ele não agrega mais nenhum valor e só cria mais problemas
    • Exato. Passei anos enchendo o site de tags e atributos de microdata na esperança de trazer tráfego
      No fim, isso só serviu para treinar a IA do Google e manter as pessoas sem sair do Google

  • Se você tem uma postura pragmática, eu recomendaria ler sobre JSON-LD na documentação do Google para sites
    https://developers.google.com/search/docs/appearance/structu...
    Você também vai notar que muita coisa ali só se aplica a alguns sites. Rotten Tomatoes pode publicar notas de críticos de filmes em JSON-LD, mas mesmo que eu escreva resenhas de filmes, isso não é muito relevante para mim
    JSON-LD é fácil e os mecanismos de busca realmente usam, então tudo bem. Ele pode duplicar informações que já estão na página, mas eu vejo esse sonho de anotar tudo perfeitamente para que a informação apareça exatamente uma vez no documento como uma idealização tipo vaca esférica e corda sem massa
    Criar uma página web exige trabalho humano, e ter um pouco de duplicação no resultado final não tem problema

    • Dá para usar JSON-LD em resenhas de filmes mesmo sem ser um site grande
      No meu site eu uso em resenhas de livros, jogos e filmes, e parece que a maioria dos mecanismos de busca mostra coisas como a nota em estrelas
    • 403. That’s an error.
      Diz que o cliente não tem permissão para buscar a URL /search/docs/appearance/structured-data/intro-structured-data neste servidor
    • Mas duplicar dados vai aumentar o consumo de água. /s

  • Para prévias ricas de links, OpenGraph tem suporte com muito mais frequência do que JSON-LD
    Se o objetivo é otimização para mecanismos de busca, os tipos de JSON-LD suportados pelos buscadores são muito específicos e limitados. É muito melhor olhar a documentação do buscador de destino, ou seja, Google[1] ou Bing[2], e seguir aquilo ao pé da letra; fora isso, é quase perda de tempo
    Fora do contexto de mecanismos de busca, se não houver um objetivo específico, JSON-LD em geral não serve para muita coisa. Se você tiver uma necessidade concreta que peça JSON-LD, vale colocar os dados que forem úteis para isso; colocar outros dados além disso é quase como gritar no vazio
    O IndieWeb[3] usa dados estruturados, mas considera JSON-LD uma violação de DRY e usa Microformats[4] no lugar
    0: https://ogp.me
    1: https://developers.google.com/search/docs/appearance/structu...
    2: https://www.bing.com/webmasters/help/marking-up-your-site-wi...
    3: https://indieweb.org/
    4: https://microformats.org/

  • O que você realmente quer implementar em qualquer site são dados estruturados usando o vocabulário do Schema.org
    JSON-LD é uma das formas de fazer isso, e também existem RDFa e Microdata
    Quando comecei a aprender, usei este texto como referência e vale a recomendação: https://neilpatel.com/blog/get-started-using-schema/
    Você pode ver que tipo de dados adicionar com esta ferramenta: https://technicalseo.com/tools/schema-markup-generator/
    A lista completa pode ser vista no site do schema.org: https://schema.org/docs/schemas.html

  • Alguns anos atrás descobri que todos aqueles recursos sofisticados de e-mail como passagem aérea embutida ou informações de rastreamento de entrega sendo exibidas são implementados com JSON-LD dentro do e-mail
    Mas, pelo que eu sei, só o Gmail oferece suporte
    Mais informações: https://www.emailonacid.com/blog/article/email-development/s...

    • Outlook e iCloud também oferecem suporte a alguns recursos, como bilhetes ou reservas

  • Fico me perguntando se essas propriedades realmente ajudam na visibilidade na busca, ou se só facilitam para os mecanismos de busca manterem o usuário preso na página de resultados

    • Depois que adicionei JSON-LD, o Google passou a mostrar links internos para dentro do meu site. Isso foi legal
    • Se for um site comercial, o JSON-LD pode ser usado para fornecer dados a plataformas de mapas
      Coisas como endereço, horário de funcionamento, telefone e cardápio

  • Já existe HTML semântico, mas por algum motivo ainda precisamos expressar de novo o significado do site em um JSON esquisito e customizado dentro de uma tag script, que o navegador nem processa

    • Já usei JSON-LD no meu site e vejo que ele atende a uma necessidade separada do HTML semântico
      HTML semântico define o que o navegador processa, como títulos e cabeçalhos. Os dados em JSON-LD são metadados, como data de criação, data de modificação, tags e autor
      Essas coisas também podem ser expressas como microdata dentro do HTML, mas JSON-LD é mais fácil, então parei de usar microdata
      Eu preencho o JSON-LD a partir dos mesmos dados usados para gerar o site, e com esses metadados também crio páginas de índice, como uma lista de posts do blog de 2024 ou todos os posts sobre o tema X. O principal consumidor do JSON-LD são os mecanismos de busca
      Se quiser ficar ainda mais irritado, pense que eu também incluo metadados OpenGraph na mesma página. Ou seja, há dois formatos diferentes de metadados na mesma página
    • Também existe Microdata e, se não me engano, ele suporta o mesmo vocabulário do JSON-LD. schema.org é uma boa referência
      Mas o JSON-LD vem sendo o padrão de fato há algum tempo, meio como fomos largando REST e indo para RPC. Não sei se os parsers importantes ainda suportam microdata de forma ampla, e especialmente ao criar sites para clientes, como e-commerce que quer destaque na busca do Google, normalmente usei LD por padrão
      Também há um ponto importante na comparação com HTML semântico. HTML semântico ajuda a definir a estrutura da marcação, mas não chega a expressar contexto do mundo real, como “isto é um produto à venda” ou “isto é uma tabela de horários de trem”
    • Acho que você não entendeu o texto por completo
      Dá para usar ontologias como Schema.org/FOAF/WikiData dentro do HTML sem JSON-LD nem tag script
    • Num mundo ideal, servidores e navegadores poderiam fazer negociação de conteúdo, e o navegador primeiro pediria só o JSON-LD do site, usando depois seu próprio formato interno de renderização
    • HTML semântico não cobre o mesmo escopo que JSON-LD e outros microformatos
      Só pelos exemplos do texto, já dá para perguntar quais seriam os elementos semânticos para representar pessoas, trilha de navegação, aplicativos de software, blogs e posts de blog
      HTML semântico serve para ajudar quem usa leitor de tela a navegar por elementos gerais como “navegação” ou “artigo”

  • Isso não é simplesmente OpenGraph escrito em JSON? Qual é a vantagem?

  • Desde 2024, o tráfego das nossas páginas de marketing baseadas em conteúdo caiu cerca de 85%
    O que não entendo é: com o aumento das páginas de resultados sem clique, o Google também não deveria ter sido bastante afetado?
    A receita de anúncios da página de resultados, que é baseada em clique, também deveria ter despencado de forma parecida, mas não encontrei números públicos para refutar ou confirmar essa hipótese

  • Existe um equilíbrio delicado em que, depois de certo ponto, simbiose vira exploração
    A relação em que sites ganhavam visibilidade com a ajuda dos mecanismos de busca era, em boa parte, mutuamente benéfica
    Mas agora isso está indo totalmente para um lado em que o dono do site não recebe nada pelo trabalho suado que produziu