Verificação HTML: Valor inválido para o atributo "src" no elemento "iframe": Carácter ilegal na consulta: "[" não é permitido.

Sobre este problema HTML

Os parênteses retos ([ e ]) são caracteres reservados segundo o RFC 3986, o padrão que define a sintaxe URI. Eles são apenas permitidos no componente host de um URL (especificamente para endereços IPv6) e são ilegais noutros locais, incluindo a string de consulta. Embora a maioria dos browsers seja tolerante e carregue um <iframe> mesmo quando o src contém parênteses retos não codificados, o W3C HTML Validator corretamente sinaliza isto como um valor de URL inválido.

Este padrão surge frequentemente quando se trabalha com frameworks ou APIs que usam notação de parênteses para representar arrays ou objetos aninhados em parâmetros de consulta — por exemplo, filters[category]=news ou items[0]=apple. Estes URLs funcionam na barra de endereços de um browser porque os browsers silenciosamente corrigem URLs mal formados, mas o HTML bruto em si é tecnicamente não-conforme.

Porque é importante

Conformidade com padrões: Um documento HTML válido requer que todos os valores de atributos que esperam URLs contenham URIs devidamente codificados. Parênteses retos não codificados violam este requisito.
Interoperabilidade: Embora os browsers principais lidem com isto graciosamente, outros consumidores de HTML — como leitores de ecrã, web scrapers, componentes webview incorporados ou clientes de email — podem não ser tão tolerantes.
Manutenibilidade: URLs devidamente codificados são inequívocos e reduzem o risco de bugs de parsing subtis, especialmente quando os URLs são construídos dinamicamente ou passados através de múltiplas camadas de processamento.

Como corrigir

Há duas abordagens principais:

Codificar os parênteses com percent-encoding. Substitua cada [ por %5B e cada ] por %5D no URL. O servidor descodificá-los-á de volta para parênteses automaticamente, portanto a funcionalidade é preservada.
Use nomeação de parâmetros alternativa. Se você controla o servidor, mude para uma convenção de nomeação que evite parênteses completamente, como notação de ponto (filters.category) ou underscores (filters_category). Isto mantém o URL válido sem qualquer codificação.

Se você está a gerar o URL dinamicamente em JavaScript, pode usar encodeURIComponent() em chaves e valores de parâmetros individuais, ou usar as APIs URL e URLSearchParams, que lidam com a codificação automaticamente.

Exemplos

Incorreto — parênteses retos não codificados na string de consulta

<iframe src="https://example.com/embed?filters[category]=news&filters[tags]=web"></iframe>

Os caracteres [ e ] na string de consulta tornam este um valor de URL inválido, acionando o erro do validador.

Corrigido — parênteses codificados com percent-encoding

<iframe src="https://example.com/embed?filters%5Bcategory%5D=news&filters%5Btags%5D=web"></iframe>

Substituir [ por %5B e ] por %5D produz um URL válido. O servidor recebe os mesmos nomes de parâmetros após descodificação.

Corrigido — nomeação de parâmetros alternativa

<iframe src="https://example.com/embed?filters.category=news&filters.tags=web"></iframe>

Se o servidor o suporta, usar notação de ponto elimina completamente a necessidade de parênteses, mantendo o URL limpo e válido.

Gerar URLs codificados em JavaScript

<iframe id="content-frame"></iframe>
<script>
  const url = new URL("https://example.com/embed");
  url.searchParams.set("filters[category]", "news");
  url.searchParams.set("filters[tags]", "web");
  document.getElementById("content-frame").src = url.href;
  // Resultado: https://example.com/embed?filters%5Bcategory%5D=news&filters%5Btags%5D=web
</script>

A API URLSearchParams automaticamente codifica com percent-encoding os caracteres reservados, portanto você pode escrever os nomes dos parâmetros naturalmente e deixar o browser produzir um URL válido.