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

Sobre este problema HTML

Quando o Validador HTML W3C reporta “Valor inválido X para o atributo src no elemento iframe: Caráter ilegal na consulta: [ não é permitido”, significa que o seu URL contém parênteses retos não codificados na porção de consulta (tudo após o ?). Embora a maioria dos navegadores modernos irá silenciosamente lidar com estes carateres e carregar o recurso de qualquer forma, o URL não está em conformidade com a sintaxe URI definida na RFC 3986, que a especificação HTML exige.

De acordo com a RFC 3986, os parênteses retos são carateres reservados que têm um propósito específico: são apenas permitidos no componente host de um URI para denotar endereços IPv6 (por exemplo, http://[::1]/). Em qualquer outro lugar no URI — incluindo a string de consulta — devem ser codificados por percentagem. O padrão HTML atual (WHATWG) exige que os URLs em atributos como src, href e action sejam URLs válidos, o que significa que devem seguir estas regras de codificação.

Por que isto é importante

Conformidade com padrões: URLs inválidos causam falhas de validação W3C, que podem indicar problemas mais profundos na sua marcação.
Interoperabilidade: Embora os navegadores principais sejam tolerantes, alguns clientes HTTP, proxies, CDNs ou firewalls de aplicações web podem rejeitar ou danificar URLs com parênteses retos não codificados.
Comportamento consistente: A codificação por percentagem de carateres reservados garante que o URL é interpretado da mesma forma em todo o lado — em navegadores, logs de servidor, verificadores de links e ferramentas automatizadas.
Fiabilidade de cópia-cola: Quando utilizadores ou ferramentas copiam um URL do seu código HTML, um URL já codificado tem menor probabilidade de quebrar durante a transmissão através de clientes de email, aplicações de mensagens ou outros sistemas.

Como corrigir

Substitua cada ocorrência de [ por %5B e ] por %5D dentro da string de consulta do URL. Se estiver a gerar URLs do lado do servidor ou em JavaScript, use as funções de codificação de URL integradas da linguagem em vez de fazer substituição manual:

JavaScript: encodeURIComponent() ou as APIs URL / URLSearchParams
PHP: urlencode() ou http_build_query()
Python: urllib.parse.urlencode() ou urllib.parse.quote()

Estas funções irão automaticamente codificar parênteses retos e quaisquer outros carateres reservados.

Exemplos

❌ Inválido — parênteses retos não codificados na string de consulta

<iframe src="https://example.com/embed?filter[status]=active&filter[type]=video"></iframe>

O validador sinaliza [ e ] como carateres ilegais no componente de consulta.

✅ Válido — parênteses retos codificados por percentagem

<iframe src="https://example.com/embed?filter%5Bstatus%5D=active&filter%5Btype%5D=video"></iframe>

Substituir [ por %5B e ] por %5D resolve o erro. O servidor recebe exatamente os mesmos valores de parâmetros — a maioria das frameworks do lado do servidor (PHP, Rails, etc.) descodifica automaticamente carateres codificados por percentagem antes de os processar.

❌ Inválido — parênteses retos num parâmetro de timestamp

<iframe src="https://example.com/report?time=[2024-01-01]"></iframe>

✅ Válido — parâmetro de timestamp devidamente codificado

<iframe src="https://example.com/report?time=%5B2024-01-01%5D"></iframe>

Gerar URLs codificados em JavaScript

Se estiver a definir o src dinamicamente, deixe o navegador lidar com a codificação para você:

<iframe id="report-frame"></iframe>
<script>
  const url = new URL("https://example.com/embed");
  url.searchParams.set("filter[status]", "active");
  url.searchParams.set("filter[type]", "video");
  document.getElementById("report-frame").src = url.toString();
</script>

A API URLSearchParams codifica automaticamente os parênteses por percentagem, produzindo um URL válido no atributo src.

Uma nota sobre outros elementos

Esta mesma regra aplica-se a qualquer atributo HTML que aceite um URL — incluindo href em elementos <a>, action em elementos <form>, e src em elementos <script> ou <img>. Sempre que colocar um URL em HTML, garanta que todos os carateres reservados na string de consulta estão devidamente codificados por percentagem.