POP — Implementação e homologação de JSON-LD

Finalidade

Este POP define o procedimento para planejar, implementar, homologar, publicar e operar dados estruturados em JSON-LD de forma coerente com o conteúdo visível, com o vocabulário Schema.org, com os consumidores-alvo e com os objetivos do projeto.

O resultado esperado é uma marcação auditável, sincronizada com fontes de verdade, com critérios de aceite explícitos, evidências de homologação e plano de rollback. Este documento não promete posicionamento, rich result, citação em interfaces generativas nem entrada automática em Knowledge Graph.

Escopo e aplicação

Aplica-se a sites WordPress (e stacks equivalentes) nos quais JSON-LD é publicado por tema, plugin (incluindo Yoast), código customizado, JavaScript ou GTM.

Deve ser aplicado quando:

• houver entidade principal clara na página (organização, artigo, produto, serviço, evento, etc.);
• existir consumidor-alvo identificado (Google, Bing ou outro) ou finalidade semântica documentada;
• os valores puderem ser mantidos atualizados a partir de uma fonte de verdade.

Não deve ser aplicado quando:

• o tipo não corresponder ao conteúdo visível;
• não houver fonte de verdade para propriedades críticas (preço, disponibilidade, datas, autoria);
• a recomendação for apenas hipótese experimental sem plano de teste;
• a implementação criaria nó concorrente ou contraditório em relação a um grafo já existente (ex.: segundo Organization com outro @id).

Contexto teórico, arquitetura de entidades e fundamentação de SEO/GEO/AEO permanecem no guia JSON-LD como infraestrutura de dados para SEO, GEO e AEO. Este POP é o procedimento operacional.

Entradas obrigatórias

• lista de templates no escopo;
• URLs de amostra por template;
• objetivos de negócio e métrica esperada;
• consumidores-alvo;
• inventário do markup já existente (tema, plugins, GTM, custom);
• fontes de verdade por propriedade crítica;
• responsáveis (RACI mínimo);
• documentação oficial atual do consumidor;
• ambiente de staging;
• plano de mensuração;
• plano de rollback.

Orientação técnica

Papéis (RACI mínimo)

• Editorial / conteúdo: verdade factual do texto visível, autoria, datas editoriais.
• Tecnologia: geração segura, IDs, deploy, inspeção renderizada, rollback.
• SEO / busca: priorização por consumidor, elegibilidade, monitoramento de search appearance.
• Aprovador: aceite formal contra os critérios deste POP.

Gate de classificação

Antes de implementar, classifique a recomendação:

• Documentada — há documentação primária do consumidor → pode entrar no escopo com critério de aceite.
• Inferência técnica — benefício arquitetural sem garantia do consumidor → justificar como decisão de engenharia.
• Hipótese experimental — exige plano de teste, prazo, métrica e possibilidade explícita de resultado nulo.

Fase 1 — Descoberta

• Identificar a entidade principal de cada template.
• Inspecionar HTML original e renderizado.
• Inventariar plugins, tema, GTM e código customizado.
• Registrar tipos, propriedades e @id já existentes.
• Identificar duplicações e conflitos.
• Mapear a fonte de cada valor crítico.
• Confirmar que os dados podem ser publicados (privacidade/LGPD).
• Verificar suporte atual do consumidor.
• Classificar como documentada, inferência ou hipótese.
• Definir resultado e métrica.

Fase 2 — Projeto

• Desenhar nós e relações.
• Definir padrão de @id estável (evitar IDs por página para entidades globais).
• Separar entidades globais e específicas da página.
• Definir propriedades obrigatórias e recomendadas do consumidor.
• Remover campos sem fonte de verdade.
• Definir método de geração (preferir server-side / API do grafo existente).
• Definir allowlist de publicação.
• Criar casos de teste e critérios de aceite.
• Definir rollback antes do deploy.

Fase 3 — Implementação

• Trabalhar em ambiente controlado.
• Usar serialização segura (wp_json_encode ou equivalente); nunca concatenar JSON manualmente.
• Preservar IDs de grafos existentes (estender Yoast em vez de competir com ele, quando aplicável).
• Evitar segundo nó para a mesma entidade.
• Manter markup e conteúdo visível sincronizados.
• Usar URLs absolutas, canônicas e rastreáveis.
• Incluir fuso horário nas datas relevantes (ISO 8601).
• Validar moeda, país, preço e disponibilidade quando existirem.
• Testar caracteres especiais e campos vazios.
• Registrar versão da alteração.

Fase 4 — Validação

• Validar sintaxe JSON.
• Validar Schema.org (Schema Markup Validator).
• Validar no Rich Results Test quando houver recurso compatível.
• Revisar políticas específicas do tipo.
• Comparar visualmente conteúdo e marcação (divergência factual).
• Testar a URL publicada, não somente o código.
• Inspecionar versão renderizada (crítico para JS/GTM).
• Verificar mobile e desktop quando o recurso diferir.
• Testar uma URL de cada template do escopo.
• Armazenar evidências.

Fase 5 — Deploy

• Publicar primeiro em amostra controlada.
• Confirmar ausência de regressão no frontend.
• Confirmar que não surgiram nós duplicados.
• Solicitar recrawl somente quando fizer sentido.
• Acompanhar Search Console e, quando aplicável, Bing Webmaster Tools.
• Confirmar que páginas continuam rastreáveis e indexáveis.
• Expandir após aceite da amostra.
• Registrar data e responsável pelo deploy.

Fase 6 — Operação

• Monitorar erros críticos por template.
• Auditar divergências factuais em amostragem.
• Revisar páginas com dados voláteis (preço, estoque, evento, vaga).
• Acompanhar search appearances quando o relatório existir.
• Registrar incidentes e tempo de correção.
• Revisar documentação oficial periodicamente.
• Reavaliar tipos descontinuados ou limitados.
• Atualizar este POP quando o processo mudar.
• Testar rollback ao modificar componentes críticos.
• Manter data formal para a próxima auditoria.

Rollback playbook

Definir antes do deploy uma das ações abaixo, testável em staging:

• desativar filtro/feature flag da marcação;
• reverter commit/template;
• restaurar versão do plugin;
• remover bloco/GTM tag responsável;
• republicar amostra conhecida como boa.

“Remover manualmente depois” não é plano de rollback.

Verificação e evidências

Critérios de aceite

A implementação é aprovada somente quando:

1. a entidade principal está correta;
2. tipos e propriedades são válidos para o vocabulário e para o consumidor-alvo;
3. o consumidor-alvo e o resultado esperado estão documentados;
4. o markup corresponde ao conteúdo visível;
5. não existem erros críticos no escopo suportado;
6. identificadores e relações são consistentes;
7. não há dados indevidos ou sensíveis;
8. a URL renderizada foi inspecionada;
9. existe evidência de homologação;
10. responsável, monitoramento e rollback estão definidos.

“O plugin mostrou uma luz verde” não é critério de aceite.

Artefatos mínimos a preservar

• inventário pré-implementação (nós, origem, @id);
• classificação documentada / inferência / hipótese;
• URL de amostra por template;
• saída do parser JSON e do Schema Markup Validator;
• Rich Results Test ou equivalente, quando houver recurso;
• inspeção da URL renderizada;
• registro de versão, data, responsável e aprovador;
• plano e teste de rollback.

KPIs operacionais

• Cobertura elegível: páginas com markup válido ÷ páginas que deveriam possuir o tipo.
• Erro crítico: itens inválidos ÷ itens detectados.
• Divergência factual: páginas com diferença markup × conteúdo ÷ páginas auditadas.
• Regressão por deploy: templates afetados após mudança.
• Tempo de correção: detecção → homologação da solução.
• Atualização dentro do SLA: mudanças refletidas no markup no prazo definido.
• Search appearance: impressões/cliques/CTR do recurso quando o relatório existir.

Gatilhos de nova versão deste POP

• retirada ou limitação relevante de rich result / recurso do consumidor;
• mudança material na API de schema do CMS/plugin (ex.: Yoast);
• inclusão de novo arquétipo de template no método padrão;
• incidente de divergência factual ou vazamento de campo;
• alteração de papéis, SLAs ou critérios de aceite.

Referências

Guia de fundamento: JSON-LD como infraestrutura de dados para SEO, GEO e AEO.

Fontes externas essenciais: Schema.org; W3C JSON-LD 1.1; Google Search Central (introdução, políticas, galeria, Organization, Article, ferramentas de teste); documentação da Schema API do Yoast; wp_json_encode no WordPress Developer Resources.