Como adicionar Dados Estruturados com JSON-LD

JSON-LD (JavaScript Object Notation for Linked Data) é um formato de marcação de dados estruturado que contém os dados vinculados dentro de um bloco de script (<script> </script>). As informações inseridas no script são ocultas aos visitantes e usadas apenas por crawlers de motores de busca.

Essa é uma grande mudança para mecanismos de pesquisa como o Google, que sugeriram inicialmente a marcação direto no HTML da página usando microdados ou RDFa. A marcação direta em elementos visuais do HTML pode causar erros de formatação e outros problemas, sendo o principal deles, a manutenção do código.

Vantagens de usar o JSON-LD:

O HTML não precisa ser alterado.
Pode ser incorporado em qualquer lugar da página.
Suportado pelos maiores motores de busca.
Formato recomendado do Google.
Fácil de manter.

Implementando código JSON-LD

Chamando o script JSON-LD

JSON-LD não é tão complicado quanto parece. Abaixo está o esquema básico que sempre será usado. Seu código deve ser colocado entre chaves ou não será implementado corretamente.

<script type="application/ld+json">
{
Seu código aqui...
}
</script>

Context

Em seguida, precisamos informar aos mecanismos de pesquisa que estamos usando a documentação do Schema.org. Ela permite que os motores de busca acessem mais informações sobre aquela página.

É importante observar que uma vírgula é usada após cada propriedade, exceto a última. Isso informa os motores de busca que existe mais dados sobre aquela propriedade.

"@context": "http://schema.org",

Type

@Type define a entidade que você está fazendo referência. Por exemplo, vamos usar um restaurante.

"@type": "Restaurant",

Para ver a documentação, visite o schema.org e, na barra de pesquisa, digite “local business”. Clique em “LocalBusiness - schema.org”. Essas são todas as propriedades disponíveis para LocalBusiness.

Schema.org “Localbusiness”

LocalBusiness - schema.org

Vá até a parte inferior e clique na guia JSON-LD, você poderá ver exemplos em JSON-LD.

JSON-LD exemplo para LocalBusiness

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Restaurant",
  "address": {
    "@type": "PostalAddress",
    "addressLocality": "Sunnyvale",
    "addressRegion": "CA",
    "postalCode": "94086",
    "streetAddress": "1901 Lemur Ave"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4",
    "reviewCount": "250"
  },
  "name": "GreatFood",
  "openingHours": [
    "Mo-Sa 11:00-14:30",
    "Mo-Th 17:00-21:30",
    "Fr-Sa 17:00-22:00"
  ],
  "priceRange": "$$",
  "servesCuisine": [
    "Middle Eastern",
    "Mediterranean"
  ],
  "telephone": "(408) 714-1489",
  "url": "http://www.greatfood.com"
}
</script>

Propriedades

Agora, aplicamos propriedades que se aplicam ao @type (restaurant) que estamos usando. Essas propriedades possuem informações que você esperaria ver em restaurante, como o nome, endereço e horário de funcionamento.

Para definir as propriedades, usamos aspas ao redor da mesma, seguidas de dois pontos, espaço e aspas ao redor do conteúdo.

 "name": "TheZone",

Então, como sabemos quais propriedades incluir? Vamos juntar o código que definimos até agora.

<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "Restaurant"
}
</script>

Agora vamos para a Ferramenta para testes de dados estruturados do Google. Clique em “SNIPPET DE CÓDIGO”, cole o código na caixa e pressione “REALIZAR TESTE”. Lembre-se de remover a última vírgula do código após Restaurant ou você receberá um erro.

Ferramenta para testes de dados estruturados do Google

Agora podemos ver os campos obrigatórios (vermelho) e recomendados (laranja) diretamente do Google.

Resposta de error para o schema de Restaurant

É um ótimo lugar para aprender, mas lembre-se de que você pode inserir outras informações. Por exemplo, se você tiver comentários, poderá incluí-los.

Então, vamos adicionar uma imagem e um nome.

"Image": "https://exemplo.com/imagem.jpg",
"name": "Dona Benta",

Nosso código vai ficar assim:

<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "Restaurant",
"image": "https://exemplo.com/imagem.jpg",
"name": "Dona Benta"
}
</script>

Lembre-se de que Restaurant agora terá uma vírgula sinalizando que existem mais propriedades a seguir e a última propriedade image não terá vírgula.

Teste o novo código e você verá que o erro foi substituído pelas informações corretas.

Restaurant schema JSON-LD

Entidades agrupadas

Algumas propriedades como address têm suas próprias propriedades. Para agrupar as propriedades dentro de uma propriedade pai, usamos chaves.

“address”: {
	"@type": "PostalAddress",
   	        "addressLocality": "Pedro Leopoldo",
    	        "addressRegion": "MG",
    	        "postalCode": "33500-000",
    	        "streetAddress": "Rodovia MG-424, Km13"
			 }

Aqui está como nosso código ficaria com a propriedade address e name adicionada ao nosso exemplo.

<script type="application/ld+json">
{
 "@context": "http://schema.org",
 "@type": "Restaurant",
 "Image": "http://example.com/image.jpg",
 "name": "Dona Benta",
 “address”: {
	"@type": "PostalAddress",
   	        "addressLocality": "Pedro Leopoldo",
    	        "addressRegion": "MG",
    	        "postalCode": "33500-000",
    	        "streetAddress": "Rodovia MG-424, Km13"
	       }
 }
 </script>

Estrutura de um array

Às vezes será necessário adicionar vários dados em uma única propriedade como OpeningHours, na qual você pode abrir em horas e dias diferentes. Para fazer isso, usamos o que é chamado de “array”.

Um array usa colchetes em vez das chaves e cada dado deve estar em uma linha diferente.

“openingHours”: [
	“Mo-Th 9:00-17:00”,
	“Fri 9:00-12:00
],

As abreviações para os dias da semana são Mo, Tu, Nós, Th, Fr, Sa, Su. Vários dias podem ser listados com vírgulas separando cada dia (Mo, Tu, We, Th) ou você pode usar um hífen para declarar intervalos (Mo-Th). Os horários são escritos usando o relógio de 24 horas.

Esquema com OpeningHours incluído.

<script type="application/ld+json">
 {
 "@context": "http://schema.org",
 "@type": "Restaurant",
 "Image": "http://example.com/image.jpg",
 "name": "Dona Benta",
 “address”: {
	"@type": "PostalAddress",
   	        "addressLocality": "Pedro Leopoldo",
    	        "addressRegion": "MG",
    	        "postalCode": "33500-000",
    	        "streetAddress": "Rodovia MG-424, Km13"
	       },
  "openingHours": [
    "Mo-Th 17:00-21:30",
    "Fr-Sa 17:00-22:00"
  ]
  }
 </script>

Dicas de marcação de dados estruturados para evitar erros

Sempre verifique se você preencheu, no mínimo, os campos obrigatórios para cada tipo. Você pode verificar usando a Ferramenta de dados estruturados do Google.
Tipos e propriedades diferenciam maiúsculas de minúsculas.
Não se esqueça de separar cada propriedade com uma vírgula ou você receberá um erro.
Não use programas como o Google Doc ou Word para escrever seu JSON-LD, pois isso causará erros de formatação. Eu recomendo usar a ferramenta do Google ou o próprio Playground do JSON-LD.org.

Algumas dicas

Evite problemas e não adicione um esquema sobre um tipo conteúdo que não existe no seu site. Só porque o esquema não precisa estar incluído em um elemento visível não significa que somos livres para incluir o que quisermos. Com muito poucas exceções, nunca marque nada que não esteja visível na sua página e sempre verifique se os campos obrigatórios estão completos.

Na medida em que souber implementar o código tecnicamente, você pode colocar o JSON-LD em qualquer lugar da sua página. Eu costumo colocar o meu no topo do <body>, mas essa é apenas a minha preferência.

E aí, gostou? Deixe suas dúvidas e comentários abaixo.

Dados Estruturados com JSON-LD

Adicionar dados estruturados não é tão difícil quanto parece