Validación HTML: Valor incorrecto X para el atributo "src" en el elemento "iframe": Carácter ilegal en la consulta: "[" no está permitido.

Acerca de este problema HTML

Cuando el validador HTML W3C reporta “Valor incorrecto X para el atributo src en el elemento iframe: Carácter ilegal en la consulta: [ no está permitido”, significa que tu URL contiene corchetes no codificados en la porción de consulta (todo lo que viene después del ?). Aunque la mayoría de los navegadores modernos manejarán silenciosamente estos caracteres y cargarán el recurso de todos modos, la URL no se ajusta a la sintaxis URI definida en RFC 3986, que la especificación HTML requiere.

Según RFC 3986, los corchetes son caracteres reservados que tienen un propósito específico: solo están permitidos en el componente host de una URI para denotar direcciones IPv6 (p. ej., http://[::1]/). En cualquier otro lugar de la URI — incluida la cadena de consulta — deben estar codificados por porcentaje. El estándar viviente HTML (WHATWG) requiere que las URLs en atributos como src, href, y action sean URLs válidas, lo que significa que deben seguir estas reglas de codificación.

Por qué esto importa

Cumplimiento de estándares: Las URLs inválidas causan fallos en la validación W3C, lo que puede indicar problemas más profundos en tu marcado.
Interoperabilidad: Aunque los navegadores principales son permisivos, algunos clientes HTTP, proxies, CDNs o firewalls de aplicaciones web pueden rechazar o alterar URLs con corchetes no codificados.
Comportamiento consistente: La codificación por porcentaje de caracteres reservados garantiza que la URL sea interpretada de la misma manera en todas partes — en navegadores, registros de servidor, verificadores de enlaces y herramientas automatizadas.
Confiabilidad de copiar y pegar: Cuando los usuarios o herramientas copian una URL de tu código HTML fuente, una URL ya codificada tiene menos probabilidades de romperse durante la transmisión a través de clientes de email, aplicaciones de mensajería u otros sistemas.

Cómo solucionarlo

Reemplaza cada aparición de [ con %5B y ] con %5D dentro de la cadena de consulta de la URL. Si estás generando URLs del lado del servidor o en JavaScript, usa las funciones de codificación de URL integradas del lenguaje en lugar de hacer buscar y reemplazar manual:

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

Estas funciones codificarán automáticamente los corchetes y cualquier otro carácter reservado.

Ejemplos

❌ Inválido — corchetes no codificados en la cadena de consulta

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

El validador marca [ y ] como caracteres ilegales en el componente de consulta.

✅ Válido — corchetes codificados por porcentaje

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

Reemplazar [ con %5B y ] con %5D resuelve el error. El servidor recibe exactamente los mismos valores de parámetro — la mayoría de los frameworks del lado del servidor (PHP, Rails, etc.) decodifican automáticamente los caracteres codificados por porcentaje antes de procesarlos.

❌ Inválido — corchetes en un parámetro de marca de tiempo

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

✅ Válido — parámetro de marca de tiempo codificado correctamente

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

Generando URLs codificadas en JavaScript

Si estás configurando el src dinámicamente, deja que el navegador maneje la codificación por ti:

<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>

La API URLSearchParams codifica automáticamente los corchetes por porcentaje, produciendo una URL válida en el atributo src.

Una nota sobre otros elementos

Esta misma regla se aplica a cualquier atributo HTML que acepte una URL — incluido href en elementos <a>, action en elementos <form>, y src en elementos <script> o <img>. Siempre que coloques una URL en HTML, asegúrate de que todos los caracteres reservados en la cadena de consulta estén codificados correctamente por porcentaje.