Misma configuración: API en JSON, K8 en YAML, ida y vuelta en CI: el formato incorrecto provoca errores de análisis, pérdida de comentarios o implementaciones en el entorno incorrecto.
Dirigido a ingenieros de DevOps y full-stack, este artículo compara la sintaxis y los criterios de selección de JSON y YAML, describe un flujo de trabajo de conversión seguro de 5 pasos y obstáculos como anclajes, alias y booleanos implícitos. Después de eso, puede convertir y validar localmente en el navegador utilizando la conversión JSON ↔ YAML de JSON Toolbox.
Por qué es importante comprender JSON y YAML
JSON es el estándar de facto para las API; YAML el lenguaje de facto para la configuración de operaciones. Si cambia entre los dos sin conocer las diferencias, corre el riesgo de: "El YAML se ejecuta localmente, pero después de la conversión JSON, los tipos de claves han cambiado".
Ejemplo Docker Compose: puertos: "8080:8080" versus puertos numéricos en JSON, o sí/no en K8 se manifiesta como booleano en YAML: comportamiento inconsistente del cliente después de la conversión a JSON.
¿Qué son JSON y YAML?
JSON (Notación de objetos JavaScript) es un formato de intercambio estricto basado en texto: claves entre comillas dobles, sin comentarios, compatible con el analizador. YAML (YAML Ain't Markup Language) utiliza sangría para la jerarquía, permite comentarios y varias notaciones escalares, mejor para configuraciones grandes mantenidas manualmente.
Conexión
En YAML 1.2, JSON es un subconjunto: la mayoría de los documentos JSON válidos se pueden analizar directamente como YAML. Las características específicas de YAML (ancla &, alias *, multilínea |) se pierden durante la conversión a JSON o deben resolverse.
Diferencias fundamentales en comparación
| Dimensión de comparación | JSON | YAML |
|---|---|---|
| Comentarios | ❌ No compatible | ✅ # Comentario de línea |
| Comillas para claves | ✅ Obligatorio (doble) | ⚠️ Mayormente opcional |
| jerarquía | Corchetes rizados/cuadrados | Sangría (espacio) |
| Transporte API | ✅ Recomendado | ⚠️ Raro |
| Grandes configuraciones a mano | ⚠️ Muchos corchetes | ✅ Recomendado |
| Rigor | Alto: error de análisis inmediatamente | Relativamente flexible: tipos implícitos |
¿Qué formato para quién?
| Rol/Escenario | Formato recomendado | Razón |
|---|---|---|
| API REST/GraphQL | JSON | Ecosistema unificado, claramente |
| Kubernetes/timón | YAML | Convención comunitaria, comentable. |
| Composición acoplable | YAML | Ejemplos y documentación oficiales. |
| paquete.json/tsconfig | JSON | Soporte nativo de cadena de herramientas |
| Carga útil de la cola de mensajes | JSON | Análisis compacto y rápido |
Escenarios típicos: guía de selección
- Contrato API frontend/backend: JSON
- Acciones de GitHub/GitLab CI (pasos parciales): YAML
- Configuración estática antes de las variables de entorno: dependiendo del equipo - YAML con comentarios
- Estructura a validar estrictamente por máquina: esquema JSON + JSON
Práctica: 5 pasos para una conversión segura
- Establecer dirección: JSON → YAML (legible/editable) o YAML → JSON (API/programas)
- Guardar original: conservar copia antes de la conversión
- Inserte contenido de origen en la página de conversión, elija la dirección
- Resultado de la comprobación: JSON con validador; YAML presta atención a la sangría y los tipos.
- Prueba de humo en el entorno objetivo: implementar o llamar una vez: comportamiento como antes
Ejemplo: la misma configuración en dos notaciones
JSON:
{
"service": "api-gateway",
"replicas": 3,
"debug": false,
"ports": [8080, 8443]
}YAML:
service: api-gateway
replicas: 3
debug: false
ports:
- 8080
- 8443Errores típicos al realizar una conversión
Tipos YAML implícitos
- sí / no / activado / desactivado se puede analizar como booleano
- Cadenas de números puros entre comillas, p.e. B. versión: "01"
- nulo y ~ en YAML significan vacío; en JSON se vuelve nulo
Tamaño por JSON → YAML
YAML suele ser más legible, pero no siempre más corto. La compresión JSON + todavía se recomienda en producción solo para transporte.
Ancla y alias
YAML &anchor y *alias se resuelven para duplicar objetos durante la conversión JSON; verifique si esto es lo que desea.
Cadenas de herramientas: JSON frente a YAML
| Requisito | cadena de herramientas JSON | cadena de herramientas YAML |
|---|---|---|
| Conversión en el navegador | caja de herramientas JSON | caja de herramientas JSON |
| Validación CLI | jq | yamlint/yq |
| Aplicar K8 | Primer YAML o CRD JSON | kubectl aplicar -f |
| Restricciones de esquema | Esquema JSON establecido | Estándares menos uniformes |
Preguntas frecuentes (FAQ)
¿Se puede convertir cualquier JSON a YAML?
JSON estándar sí, semánticamente equivalente. El orden de las claves y el estilo de sangría pueden diferir del YAML escrito a mano; la semántica sigue siendo la misma.
¿Los comentarios YAML persisten en JSON?
No. JSON no tiene comentarios; se pierden en la conversión. Registre información importante en la documentación o README.
¿Los recursos de K8 también vienen en formato JSON?
Sí. kubectl admite manifiestos JSON; Community y Helm utilizan principalmente YAML: acuerdan un formato para el equipo.
¿Razones más comunes de errores de conversión?
JSON: coma final, comillas simples. YAML: tabulación y espacio mezclados, falta espacio después de dos puntos.
¿Se cargan los datos a un servidor?
No. La caja de herramientas JSON convierte localmente en el navegador, incluso para configuraciones internas (pero aún elimina valores confidenciales).
¿Validar nuevamente después de la conversión?
Sí, recomendado. Al menos verifique la sintaxis JSON y pruebe en la preparación si la configuración funciona.
Conclusión y próximos pasos
JSON se centra en el rigor y la interoperabilidad, YAML en la legibilidad y la facilidad de operación. Regla general: API y programa a programa → JSON; grandes configuraciones estáticas a mano → YAML; Siempre valide y pruebe con humo al realizar la conversión.
Determine en el repositorio qué tipos de archivos necesitan qué formato y el formato de compilación se verifica en CI; de esta manera evitará incidentes de producción debido a tipos YAML implícitos.