Convertir TOML a JSON y JSON a TOML: cómo cambia la sintaxis

PublicadoHerramientaConversor TOML ↔ JSON

Contenido
  1. Cuando la configuración está en TOML y la herramienta solo acepta JSON
  2. Cómo mapear la sintaxis paso a paso sin herramientas
  3. Los puntos que confunden al leer el resultado
  4. En resumen
  5. Preguntas frecuentes

Cuando conviertes TOML a JSON, lo que te confunde no es la dificultad del cálculo, sino no tener en la cabeza la tabla de correspondencias entre cada construcción y la forma que adopta. Para ir directo al grano: la correspondencia es simple. [table] se convierte en un objeto anidado, [[table]] en un array de objetos, y tanto las claves unidas con punto (.) como las tablas inline { } acaban siendo objetos.

Este artículo está pensado para quien traslada archivos de configuración entre TOML y JSON, y repasa con entradas y salidas qué resultado produce realmente cada elemento de la sintaxis.

Resumen ① [table] pasa a ser un objeto anidado, [[table]] un array de objetos, y las claves con punto (.) y las tablas inline { } se convierten en objetos. ② En el sentido contrario, JSON → TOML, el nivel superior tiene que ser obligatoriamente un objeto, y las claves cuyo valor es null desaparecen por completo, porque TOML no tiene null. ③ Los valores que parecen fechas se quedan como cadenas de texto, y los números con guiones bajos como 1_000_000 se convierten en 1000000, sin el guion.

Cuando la configuración está en TOML y la herramienta solo acepta JSON

TOML se usa mucho como formato de archivo de configuración. Los ejemplos más habituales son Cargo.toml en Rust, pyproject.toml en Python y config.toml en varios generadores de sitios estáticos.

El problema aparece cuando tienes que pasar esa configuración a otra herramienta o script que solo acepta JSON. Por ejemplo, cuando metes parte de la configuración de pyproject.toml en una herramienta de validación basada en JSON o, al revés, cuando trasladas una configuración que gestionabas en JSON a una herramienta que usa TOML.

Si lo haces a mano, es fácil que la estructura se descuadre: no acabas de ver hasta dónde llega un objeto en una tabla anidada como [tool.black], ni si los dobles corchetes de [[tool.poetry.source]] son un array o un objeto. El formato en sí es sencillo; los errores aparecen justo cuando no conoces las reglas de correspondencia.

Cómo mapear la sintaxis paso a paso sin herramientas

Primero, el principio. TOML se diseñó para corresponderse exactamente con una tabla hash (un conjunto de pares clave-valor, es decir, un diccionario). Por eso encaja tan bien con los objetos de JSON y las reglas de correspondencia se reducen a unas pocas.

Son cinco reglas.

  • 키 = 값 → el par pasa tal cual a "clave": valor.
  • Las líneas que van debajo de [owner] → se agrupan en un objeto anidado "owner": { ... }.
  • Una clave unida con punto (.) como owner.name = "홍길동" → produce exactamente lo mismo que escribir [owner]: "owner": { "name": "홍길동" }.
  • Si [[posts]] se repite → se convierte en un array de objetos: "posts": [ {...}, {...} ]. El doble corchete es la señal de "array".
  • Una tabla inline { x = 1, y = 2 } → se convierte en el objeto { "x": 1, "y": 2 }.

Por ejemplo, este TOML:

title = "블로그 설정"
version = 2
tags = ["seo", "auto", "blog"]

[database]
host = "127.0.0.1"
port = 5432

[[posts]]
title = "첫 글"
views = 120

[[posts]]
title = "둘째 글"
views = 45

se convierte en esto:

{
  "title": "블로그 설정",
  "version": 2,
  "tags": [
    "seo",
    "auto",
    "blog"
  ],
  "database": {
    "host": "127.0.0.1",
    "port": 5432
  },
  "posts": [
    {
      "title": "첫 글",
      "views": 120
    },
    {
      "title": "둘째 글",
      "views": 45
    }
  ]
}

Se ve a simple vista cómo [database] se pliega en el objeto "database" y [[posts]] en el array "posts".

Si quieres comprobar que el resultado de tu conversión manual es correcto, puedes pasarlo por un analizador sintáctico estándar. Desde Python 3.11, la biblioteca estándar incluye tomllib, un analizador de TOML de solo lectura, así que puedes obtener la misma conversión sin instalar nada con esta única línea:

python3 -c "import tomllib,json; print(json.dumps(tomllib.load(open('config.toml','rb')), indent=2, ensure_ascii=False))"

La ventaja de este método es que se trata de un analizador oficial, así que si hay un error de sintaxis te lo indica como error. Lo incómodo es tener que crear el archivo y escribir el comando cada vez; además, en el sentido contrario (JSON → TOML) la biblioteca estándar no incluye una herramienta de escritura, así que hay que instalar una biblioteca aparte.

Compruébalo con nuestra herramienta gratuita.

Conversor TOML ↔ JSON

Pega tu contenido y convierte TOML↔JSON en ambos sentidos directamente en el navegador. Es gratis, sin instalación ni registro, y lo que escribes no se envía a ningún servidor.

Los puntos que confunden al leer el resultado

Si conoces las correspondencias, el sentido TOML → JSON casi no da lugar a dudas. Los malentendidos surgen sobre todo en el sentido contrario y en el tratamiento de ciertos valores. Estos son los casos más frecuentes.

SituaciónResultado
La raíz del JSON es un array, un número o una cadenaError "La raíz de TOML debe ser un objeto"
Una clave con valor nullComo TOML no tiene null, la clave se omite por completo
Una cadena de fecha como "2026-07-17"Se mantiene tal cual, como cadena entre comillas
Un número con guiones bajos, 1_000_000Pasa a ser el número 1000000, sin guiones
# comentario (fuera de comillas)Se elimina del resultado

La raíz tiene que ser siempre un objeto. En el sentido JSON → TOML, si el nivel superior es un array como [1, 2, 3] o simplemente un número o una cadena, el conversor avisa: "La raíz de TOML debe ser un objeto". La razón es que en TOML el archivo entero es un único conjunto de pares clave-valor, así que no puede haber un array sin nombre en el nivel más externo. Si lo envuelves una vez con una clave, como { "items": [1, 2, 3] }, sí se convierte.

Las claves con null desaparecen. TOML no tiene un valor null como tal. Por eso, si el JSON incluye "nickname": null, en el resultado TOML no aparecerá ninguna línea nickname. No es que el valor quede vacío: la clave entera se pierde, de modo que si vuelves a convertir el resultado a JSON, esa clave ya no estará.

Aunque parezca una fecha, es una cadena. TOML tiene tipos propios para fecha y hora, pero este conversor simplifica esa parte y guarda valores como 2026-07-17 como cadena, no como tipo fecha. Por eso en el resultado JSON aparecen entre comillas, como "2026-07-17". Lo que no ocurre es que se interpreten por error como números y el valor se estropee.

Los guiones bajos en los números separan grupos de dígitos. En TOML puedes usar guiones bajos para agrupar cifras y leerlas mejor, como en 1_000_000. El conversor los quita y lo convierte en el número 1000000. Como JSON no admite esa notación, el resultado es el esperado.

En resumen

  • [table] se convierte en un objeto anidado, [[table]] en un array de objetos, y las claves con punto (.) y las tablas inline { } pasan a ser objetos.
  • En JSON → TOML la raíz debe ser un objeto; si pones solo un array o un número, da error.
  • Las claves con valor null se caen del resultado, porque TOML no tiene null.
  • Los valores que parecen fechas se mantienen como cadenas, y los números con guiones bajos como 1_000_000 quedan sin ellos.
  • Puedes verificar tu conversión manual con un analizador estándar como tomllib de Python.
Conversor TOML ↔ JSON

Pega tu contenido y convierte TOML↔JSON en ambos sentidos directamente en el navegador. Es gratis, sin instalación ni registro, y lo que escribes no se envía a ningún servidor.

Preguntas frecuentes

¿En qué se convierten los dobles corchetes [[ ]] de TOML en JSON?

Cuando un bloque [[posts]] con el mismo nombre aparece varias veces, se convierte en un arreglo de objetos con ese nombre, es decir, "posts": [ { ... }, { ... } ]. Solo tienes que tener clara la diferencia: [posts], con un solo par de corchetes, es un objeto anidado, mientras que [[posts]], con dos pares, es un arreglo.

Convertí JSON a TOML y me da un error. ¿Por qué?

Pasa cuando el nivel superior del JSON no es un objeto. Si es un arreglo como [1, 2, 3], o solo un número o una cadena, aparece el error «el nivel superior de TOML debe ser un objeto». En TOML el archivo entero es un conjunto de pares clave-valor, así que basta con envolverlo una vez con una clave, por ejemplo { "items": [1, 2, 3] }, para que la conversión funcione.

Puse una fecha y me sale como una cadena entre comillas.

Es normal. Este conversor simplifica las fechas y horas y las trata como cadenas, así que 2026-07-17 aparece como "2026-07-17". El valor no cambia ni se rompe: solo se mantiene el tipo como cadena.

¿La configuración que introduzco se envía a un servidor?

No. Todas las conversiones se procesan dentro del navegador, y el TOML o JSON que introduces no se envía ni se guarda en ningún servidor.

Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano

Artículos relacionados

  1. Generador TOTP: cómo se calcula el código de 6 dígitosAsí se combinan la clave Base32 y el contador de 30 segundos con HMAC-SHA1 para obtener los 6 dígitos, y por qué el código no coincide.
  2. Conversión de escape Unicode: \uXXXX, U+ y entidades HTMLAprende a convertir texto a \uXXXX, U+ y entidades HTML y a deshacerlo, con ejemplos de hangul y emojis y el motivo por el que un emoji se parte en dos.
  3. Normalizar URL: quitar utm y obtener el enlace canónicoAprende qué reglas sigue la normalización de URL: cómo se eliminan los parámetros utm_, fbclid, gclid y ref, y cómo leer la lista de cambios aplicados.
  4. Codificación URL: por qué el espacio se convierte en %20Por qué el espacio se convierte en %20 y cada letra coreana en %EA%B0%80, cuándo usar encodeURI o encodeURIComponent y cómo evitar la doble codificación.
  5. Extraer segmentos de ruta de una URL y convertirlos en rutasAprende cómo se divide una URL en protocolo, host, segmentos y query, por qué solo las barras reciben índice y cuándo un segmento pasa a :param o [param].
  6. Codificación URL: qué es el percent encoding y sus reglasDescubre por qué la URL no admite espacios ni texto no ASCII, cómo funciona el percent encoding y en qué se diferencian encodeURI y encodeURIComponent.

Herramientas relacionadas