# Como corrigir o schema do Rank Math que não le custom fields do ACF PRO no WordPress

O Rank Math schema ACF falha quando a variavel %customfield(field-name)% aponta para um nome que não casa com a meta key do ACF, ou quando o campo guarda um array ou objeto, fazendo a propriedade do JSON-LD sair vazia ou com dado errado.

## O que é schema do Rank Math sem custom fields do ACF?

O Rank Math schema ACF e a integração entre o Schema Generator do Rank Math e os campos personalizados do Advanced Custom Fields PRO. Em vez de digitar um valor fixo numa propriedade do schema (como preco, autor ou data de evento), você insere a variavel %customfield(nome-do-campo)% e o Rank Math busca esse valor no banco a cada carregamento da página, deixando o JSON-LD dinâmico e sempre atualizado por post.

O ponto que quase todo mundo erra e técnico: o ACF grava o valor de cada campo como um postmeta comum, onde a meta key e exatamente o nome do campo (field name), não o rotulo (label) que aparece no editor. A variavel %customfield(field-name)% do Rank Math le esse postmeta direto pela meta key. Quando o nome dentro da variavel não bate com a meta key real, ou quando o campo guarda um valor serializado (array, objeto, repeater), o Rank Math não consegue extrair um texto valido e a propriedade do schema sai vazia, derrubando a validação do Google.

## Como identificar

- No Schema Markup Validator ou no teste de Resultados Aprimorados do Google a propriedade preenchida com %customfield(...)% aparece vazia ou com o valor literal da variavel, em vez do dado do campo.
- O bloco de schema (Article, Product, Event) e gerado, mas o campo que deveria vir do ACF some do JSON-LD final visto no código-fonte da página.
- Mensagem 'Campo obrigatório ausente' ou 'Missing field' no Search Console para a propriedade ligada ao ACF, mesmo com o campo preenchido no editor.
- Em campos do tipo Repeater, Group ou Relationship a propriedade do schema sai com um valor quebrado como 'Array' ou um id numerico em vez do texto esperado.
- Ao trocar o nome do grupo de campos ou do field no ACF, o schema que antes funcionava passa a sair vazio sem nenhum aviso no editor.

**Antes de começar:** Antes de adicionar snippets ao functions.php ou de mexer no template de schema em producao, faça backup do site (arquivos e banco) ou teste em um ambiente de staging, para reverter caso o JSON-LD da página quebre.

## Como prevenir

- Padronize os field names do ACF em minusculas com underscore e documente cada um, para sempre usar o nome certo dentro de %customfield(field-name)% sem depender do rotulo.
- Antes de ligar um campo ao schema, confirme que ele guarda texto simples; para Repeater, Group, Relationship e Object, planeje um meta espelho desde o inicio.
- Evite renomear field names de campos já ligados ao schema; se precisar, atualize a variavel no Schema Generator no mesmo deploy para não deixar a propriedade vazia.
- Valide o JSON-LD no Schema Markup Validator a cada mudanca de campos ou de template de schema, antes de publicar, para pegar propriedade vazia cedo.

Erros relacionados

- [Como corrigir schema markup quebrado no WordPress](https://full.services/wp-fixer/corrigir-schema-markup-quebrado-wordpress/)
- [Como corrigir o erro de Schema Markup no Astra Pro](https://full.services/wp-fixer/corrigir-schema-markup-astra-pro/)
- [Como corrigir o erro de schema markup no SEOPress](https://full.services/wp-fixer/corrigir-schema-markup-seopress/)

## Causa

- A variavel usa o rotulo (label) do campo em vez do field name real do ACF: o Rank Math le a meta key, que corresponde ao field name, entao %customfield(Preco do Produto)% falha enquanto %customfield(preco_produto)% funciona.
- O campo ACF guarda um valor serializado (Repeater, Group, Relationship, ou Select múltiplo): o %customfield% le o postmeta cru e devolve um array serializado, que não vira texto valido na propriedade do schema.
- O field tem Return Format definido como Object ou Array (comum em Image, Post Object e Taxonomy): o postmeta guarda apenas o id, entao a variavel retorna um número em vez do valor legivel esperado pelo schema.
- O grupo de campos do ACF não casa com o post sendo renderizado por regra de localizacao, ou o campo esta vazio naquele post específico, fazendo o postmeta não existir e a variavel retornar string vazia.
- O campo pertence a uma options page do ACF (acf_add_options_page), cujos valores ficam em option e não em postmeta do post, fora do alcance da variavel %customfield% que so le meta keys do post atual.

## Como resolver

1. Descubra o field name real do campo no ACF: Abra o grupo de campos no ACF e copie o valor do campo Nome (Field Name), não o Rotulo (Label). E esse nome, em minusculas com underscore, que vira a meta key no banco e que o Rank Math precisa receber dentro da variavel.

```
Painel WP -> ACF -> Grupos de Campos -> abra o grupo
Clique no campo e anote o valor do campo 'Nome do Campo' (Field Name)
```

2. Use a variavel customfield com o field name correto no Schema Generator: No editor do post, abra a aba Schema do Rank Math, edite o template e na propriedade desejada insira a variavel com o field name exato. Conforme a documentação do Rank Math, a sintaxe e %customfield(field-name)%, trocando field-name pelo nome real do campo.

```
Editor do post -> Rank Math -> Schema -> Editar o schema
Na propriedade (ex.: author, price), insira: %customfield(field_name)%
Substitua field_name pelo nome anotado no passo 1
```

3. Confirme o valor cru gravado no postmeta: Para ter certeza de que a meta key existe e guarda texto simples, confira o valor cru do campo no post. Se o retorno for um array serializado (comeca com a:), o campo não serve direto para o schema e precisa ser exposto por um campo auxiliar.

```
Painel WP -> Ferramentas -> via plugin de inspecao de postmeta, busque a meta key do passo 1
Confirme que o valor e um texto simples, não algo iniciado por 'a:1:{' (array serializado)
```

4. Para campos serializados, exponha um meta espelho em texto: Repeater, Group, Relationship e campos com Return Format Object não saem como texto pela variavel. Crie um postmeta auxiliar simples com o valor já formatado via hook acf/save_post e aponte o %customfield% para essa meta key espelho.

```
Adicione o snippet PHP da seção de código ao functions.php do tema filho ou a um plugin próprio
Salve o post para gerar a meta key espelho
No Schema Generator, aponte a propriedade para %customfield(meta_espelho)%
```

5. Valide o JSON-LD no Schema Markup Validator: Depois do ajuste, rode a URL do post no validador para confirmar que a propriedade saiu preenchida com o dado do ACF. O próprio Rank Math recomenda validar o resultado antes de considerar o schema correto.

```
Abra o Schema Markup Validator (validator.schema.org) e cole a URL do post
Confirme que a propriedade ligada ao ACF mostra o valor do campo, não a variavel literal
```


## Código

```php
<?php
// Espelha um campo ACF serializado (Repeater/Group/Object) em um postmeta de texto
// simples, para o Rank Math ler via %customfield(rm_autor_nome)% no Schema Generator.
add_action( 'acf/save_post', 'full_acf_espelho_schema', 20 );
function full_acf_espelho_schema( $post_id ) {
    if ( ! function_exists( 'get_field' ) ) {
        return;
    }
    // 'autor' = field name do ACF; ajuste para o seu campo.
    $valor = get_field( 'autor', $post_id );

    // Se for array/objeto (Post Object, Relationship), extrai um texto legivel.
    if ( is_array( $valor ) ) {
        $valor = isset( $valor['post_title'] ) ? $valor['post_title'] : reset( $valor );
    } elseif ( is_object( $valor ) && isset( $valor->post_title ) ) {
        $valor = $valor->post_title;
    }

    // Grava a meta key espelho que o Rank Math vai consumir.
    update_post_meta( $post_id, 'rm_autor_nome', sanitize_text_field( (string) $valor ) );
}
```

## Perguntas frequentes

### Qual a sintaxe da variavel para puxar um campo ACF no schema do Rank Math

Conforme a documentação do Rank Math, a sintaxe e %customfield(field-name)%, trocando field-name pelo nome real do campo. Como o ACF grava o valor como postmeta usando o field name como meta key, a variavel le esse valor direto quando os nomes batem.

### Por que a propriedade do schema sai vazia mesmo com o campo ACF preenchido

Quase sempre porque a variavel aponta para o rotulo do campo em vez do field name real, ou porque o campo guarda um array serializado. O Rank Math le a meta key exata, entao confira o Field Name no ACF e use exatamente esse valor na variavel.

### O Rank Math le campos Repeater ou Group do ACF no schema

Não de forma direta. Esses campos gravam um valor serializado no postmeta e a variavel %customfield% devolve esse array cru, que não vira texto valido. A saida e criar um postmeta espelho em texto via hook acf/save_post e apontar a variavel para ele.

### Preciso editar código para usar custom fields do ACF no schema

Para campos de texto simples não: basta inserir %customfield(field-name)% no Schema Generator. So precisa de código quando o campo e serializado ou tem Return Format Object, situacao em que você cria um meta espelho em PHP com o valor já formatado.

### Por que um campo de imagem ou Post Object do ACF retorna um número no schema

Porque o postmeta desses campos guarda apenas o id do anexo ou do post, não a URL ou o título. A variavel le esse id cru. Para o schema, exponha a URL ou o texto final num meta auxiliar e aponte a variavel para essa meta key.

### A variavel customfield le campos de uma options page do ACF

Não. Campos de options page são salvos na tabela de options, não no postmeta do post atual, e a variavel %customfield% so enxerga meta keys do post sendo renderizado. Para valores globais, use outra variavel ou um hook que escreva no postmeta do post.

### Devo validar o schema depois de ligar um campo ACF

Sim. O Rank Math recomenda validar o resultado no Schema Markup Validator. Cole a URL do post e confirme que a propriedade mostra o valor do campo, e não a variavel literal, antes de considerar o schema correto.

**Fonte:** [Rank Math - How to Use Variables (Custom Field)](https://rankmath.com/kb/variables/)