Validador de Docker Compose

Qué hace esta herramienta

Pegas el contenido de tu compose.yaml y te dice si cumple el esquema oficial de Compose, señalando cada problema con su línea, la ruta dentro del archivo y una explicación en castellano. No hace falta tener Docker instalado ni que el archivo esté en tu disco.

La diferencia práctica frente a docker compose config es el contexto. Ese comando resuelve variables de entorno, rutas de build y archivos .env, así que falla por motivos que nada tienen que ver con la estructura del documento: te dirá que no encuentra un directorio antes de decirte que escribiste mal una clave. Aquí se valida el documento tal cual, que es justo lo que necesitas cuando alguien te pasa un archivo, cuando lo estás escribiendo a medias o cuando quieres entender qué le pasa antes de levantar nada.

Cómo usarla

1. Pega el archivo en el cuadro de texto.
2. Lee la lista de problemas. Cada uno lleva el número de línea, la ruta (services › web › ports) y qué se esperaba.
3. Pulsa sobre el número de línea para saltar a esa parte del archivo.

Si el archivo es correcto, verás cuántos servicios define. No hay botón de validar: se comprueba mientras escribes.

Los errores que más aparecen en un compose.yaml

Una errata en el nombre de una clave

Es, con diferencia, el más frecuente y el peor explicado por las herramientas de línea de comandos. Escribes imagee en lugar de image, o enviroment en vez de environment, y lo que obtienes es un escueto additional property is not allowed, que técnicamente es cierto pero no te dice dónde mirar.

El esquema declara additionalProperties: false en casi todos los bloques, así que cualquier clave que no reconozca es un error. Esta herramienta aprovecha eso: cuando encuentra una clave desconocida, la compara con las claves válidas en ese punto concreto del esquema y te propone la más parecida. No es una lista genérica de palabras de Compose, es lo que de verdad se admite dentro de ese servicio, esa red o ese volumen.

Un valor donde tenía que ir una lista

ports, volumes, depends_on y networks admiten forma de lista. Escribir ports: "8080:80" en lugar de

ports:
  - "8080:80"

es un despiste habitual cuando solo hay un elemento. El error que verás es que debe ser una lista, con la línea señalada.

El caso simétrico también existe: environment admite las dos formas, mapa (CLAVE: valor) y lista (- CLAVE=valor), pero no se pueden mezclar dentro del mismo bloque.

Indentación

Si el YAML ni siquiera se puede leer, no hay esquema que valga: la herramienta lo reporta como error de sintaxis, no de estructura. Los dos culpables casi siempre son un nivel de indentación que no cuadra con sus hermanos y unos dos puntos sin espacio detrás. YAML no admite tabulaciones para indentar; si tu editor las inserta, conviértelas a espacios.

version: al principio del archivo

Sigue apareciendo en tutoriales y en respuestas antiguas, pero está obsoleto. El propio esquema lo marca como declarado por compatibilidad e ignorado. No provoca un error, pero puedes borrarlo: Compose v2 no lo usa para nada.

Puertos sin comillas

ports: - 8080:80 sin comillas es válido para el esquema, pero YAML interpreta algunos pares como sexagesimales y te cambia el número. Es la razón por la que la documentación recomienda entrecomillar siempre los puertos. Aquí no aparecerá como error, pero merece la pena saberlo.

Qué no valida esta herramienta

Conviene ser claro con el alcance, porque un validador que promete de más es peor que ninguno:

• No comprueba que las imágenes existan ni que se puedan descargar.
• No resuelve variables de entorno ni archivos .env, así que un ${MI_VARIABLE} se acepta como texto.
• No verifica rutas de build ni que los archivos referenciados estén en tu disco.
• No detecta problemas lógicos como un depends_on que apunta a un servicio inexistente, dos servicios peleándose por el mismo puerto o un volumen declarado y nunca usado.

Lo que sí garantiza es que la estructura del archivo es la que Compose espera: claves reconocidas, tipos correctos y anidamiento válido. Ese es el filtro que atrapa la mayoría de los archivos rotos antes de llegar al docker compose up.

Por qué se ejecuta en tu navegador

El esquema oficial viene precompilado dentro de la propia página y la validación entera ocurre en tu equipo. No hay ninguna petición de red al validar, y puedes comprobarlo tú mismo abriendo la pestaña de red de las herramientas de desarrollo.

Importa más de lo que parece. Un compose.yaml real describe la topología interna de un proyecto: nombres de servicios, puertos, rutas de volúmenes y, con más frecuencia de la que a nadie le gustaría admitir, contraseñas de base de datos de desarrollo. Pegarlo en una herramienta que lo sube a un servidor ajeno es filtrar un mapa de tu infraestructura a cambio de una comprobación de sintaxis.

Sobre el esquema

Se valida contra compose-spec, la especificación abierta que mantienen Docker y el resto de implementaciones, publicada bajo licencia Apache 2.0. Es la misma que consume Docker Compose v2, así que lo que aquí pasa, pasa también en tu máquina.