Cuando tienes un array JSON de objetos y quieres obtener una tabla Markdown a partir de él, la vía más fiable es pasar primero por CSV y luego procesarlo con CSV a Markdown. Existen herramientas que convierten JSON directamente en una tabla, pero en cuanto aparecen valores anidados o claves ausentes, la salida tiende a romperse de formas difíciles de depurar. Pasar por CSV pone las columnas y las filas delante de ti, así que el resultado se mantiene predecible.
Este artículo recorre el proceso de principio a fin: revisar la estructura del JSON, convertirlo a CSV, generar la tabla Markdown y resolver los casos más complicados como las respuestas de API y el JSON anidado. Todo se ejecuta en el navegador, así que pegar una respuesta de API o datos internos nunca los envía a un servidor.
La respuesta corta: pasa el JSON por CSV
Aquí tienes todo el flujo de un vistazo.
- Formatea el JSON con el Formateador de JSON y confirma que es un array de objetos
- Convierte ese array a CSV — las claves de cada objeto se convierten en encabezados de columna y cada elemento se convierte en una fila
- Pega el CSV en CSV a Markdown para generar la tabla
FormatArc no tiene un botón de un solo clic para pasar de JSON a tabla. En su lugar, combinar el formateador con el convertidor de CSV te da una tabla compatible con GFM que se renderiza igual en todas partes. Usar CSV como paso intermedio es justamente la clave: puedes detectar una columna desalineada o un valor ausente antes de que acabe en la tabla.
Qué tipo de JSON se traduce a una tabla Markdown
Una tabla Markdown es una cuadrícula bidimensional: una fila de encabezado más filas de datos. Por eso el JSON que se traduce limpiamente es un array de objetos que comparten la misma forma.
[
{ "name": "Mika", "role": "admin", "active": true },
{ "name": "Noah", "role": "viewer", "active": false }
]
Las claves de cada objeto (name / role / active) se convierten en los encabezados de columna, y cada elemento del array se convierte en una fila. El JSON anterior corresponde a esta tabla:
| name | role | active |
| --- | --- | --- |
| Mika | admin | true |
| Noah | viewer | false |
Un objeto suelto que no está envuelto en un array no se convierte en una fila por sí mismo. O bien lo transformas en una tabla de dos columnas (clave/valor), o bien lo envuelves como [ { ... } ] antes de convertir.
Pasos: convertir JSON en una tabla Markdown
Paso 1: formatea el JSON y revisa la estructura
El JSON que viene de una respuesta de API o de un log suele estar en una sola línea sin saltos. Pégalo primero en el Formateador de JSON y luego confirma que realmente es un array de objetos y que todos los elementos comparten las mismas claves.
Un error de sintaxis hará tropezar todo lo que venga después, así que si el formateo falla aquí, consulta Cómo corregir errores de parseo de JSON. Si el contenido incluye comentarios //, revisa Cómo manejar los comentarios en JSON.
Paso 2: convierte el array a CSV
Una vez que la estructura está confirmada, reorganiza el array en CSV. Solo hay dos cosas que hacer.
- Pon las claves en la primera línea, separadas por comas, como encabezado
- Escribe los valores de cada objeto en el mismo orden, separados por comas, una fila a la vez
Para el JSON anterior, eso da como resultado:
name,role,active
Mika,admin,true
Noah,viewer,false
Si un valor contiene una coma o un salto de línea, envuelve ese valor entre comillas dobles "...". Para los conceptos básicos de CSV, consulta Qué es CSV. Para ir en la dirección contraria y convertir CSV de vuelta a JSON, consulta la guía de CSV a JSON.
Paso 3: genera la tabla con CSV a Markdown
Con el CSV listo, pégalo en CSV a Markdown y ejecútalo.
A la derecha aparece una tabla Markdown compatible con GFM. La fila separadora y los anchos de columna se alinean automáticamente, así que puedes copiarla directamente en un README, una issue o tu documentación. Para más detalles sobre cómo funciona la conversión y sus casos límite, consulta Cómo convertir CSV en una tabla Markdown.
Convertir una respuesta de API en una tabla
A veces quieres compartir una respuesta de curl como una tabla. El flujo es el mismo que el anterior: formatea la salida de curl y luego pásala por CSV.
curl -s https://api.example.com/users | jq .
Si la respuesta es un array de objetos, pégala en el Formateador de JSON y continúa desde el paso 2. Si la respuesta envuelve el array dentro de algo como { "data": [ ... ] }, extrae solo el array que quieres tabular (el contenido de data). Con jq, jq '.data' extrae el array por sí solo.
Para formatear respuestas de curl en general, consulta Cómo formatear (pretty-print) JSON desde curl, que compara jq, Python, la CLI y el navegador.
Cómo manejar JSON anidado
Las respuestas de API reales suelen llevar objetos o arrays dentro de sus valores.
[
{ "name": "Mika", "address": { "city": "Tokyo", "zip": "100-0001" } }
]
Una tabla Markdown es una cuadrícula plana, así que una estructura anidada no puede colocarse directamente en una celda. Hay dos formas de resolverlo.
Aplánalo primero
Expande las claves anidadas a notación de punto como address.city, aplanando la estructura antes de construir el CSV.
name,address.city,address.zip
Mika,Tokyo,100-0001
Puedes aplanar a mano, pero para cargas más grandes una función lo hace de forma fiable: to_entries de jq, o pandas.json_normalize() en Python. Después de aplanar, pasa el resultado por CSV hacia CSV a Markdown igual que antes.
Mantén el valor anidado como una cadena en la celda
En lugar de aplanar, puedes mantener una rama anidada como una sola cadena en una celda. Coloca el valor de address en una columna como una cadena JSON, por ejemplo {"city":"Tokyo","zip":"100-0001"}. En ese caso, los caracteres de barra vertical | o los saltos de línea dentro de la cadena romperían la tabla, así que envuelve el valor entre comillas dobles en la etapa del CSV. CSV a Markdown escapa automáticamente las barras verticales dentro de las celdas y reemplaza los saltos de línea por espacios, así que no tienes que ocuparte de eso tú mismo.
Configurar la alineación de columnas
Las tablas GFM permiten controlar la alineación por columna añadiendo : a la fila separadora.
| name | count |
| :--- | ---: |
| Mika | 12 |
| Noah | 340 |
:--- alinea a la izquierda, :---: centra y ---: alinea a la derecha. Alinear a la derecha una columna numérica mantiene los dígitos alineados. Ten en cuenta que si la alineación se renderiza o no depende del renderizador de Markdown del lado de la visualización. Funciona correctamente en GitHub, pero no se verá idéntica en todos los entornos. Para la sintaxis completa, incluyendo alineación y escapado, consulta Sintaxis de tablas Markdown.
Errores comunes
Las claves difieren de un elemento a otro
Cuando los elementos llevan claves distintas, el resultado depende de qué columnas emitas. Tomar la unión de todas las claves deja celdas vacías allí donde falta un valor. Usar solo las claves del primer elemento descarta cualquier clave que aparezca únicamente más adelante. Decide cómo alinear las columnas mientras construyes el CSV para que la salida se mantenga estable.
Booleanos, null y números
true / false / null y los números se escriben como texto plano en el CSV y se muestran como cadenas en la tabla Markdown, así que su significado se lee bien. Un valor vacío se convierte en una celda vacía.
Saltos de línea y barras verticales dentro de las celdas
Un valor que contiene un salto de línea o un carácter de barra vertical chocará con el separador de columna y romperá la tabla. Envuelve esos valores entre comillas dobles en la etapa del CSV y CSV a Markdown manejará los saltos de línea y las barras verticales de forma segura.
Preguntas frecuentes
¿Tengo que subir el JSON?
No. Todas las conversiones de FormatArc se ejecutan dentro de tu navegador. Pegar una respuesta de API o datos internos nunca los envía a un servidor.
¿Por qué pasar por CSV?
Usar CSV como paso intermedio hace visible la correspondencia entre los encabezados de columna y las filas. Convertir JSON directamente en una tabla dificulta encontrar la causa cuando los valores anidados o las claves ausentes rompen la salida, pero con una etapa de CSV en medio puedes corregir una columna desalineada al instante.
¿Puede el JSON anidado pasar directamente a una tabla?
No tal cual. Aplánalo con notación de punto como address.city, o mantén la rama anidada como una cadena JSON en una sola celda. Los pasos están en la sección "Cómo manejar JSON anidado" más arriba.
Para terminar
El atajo para obtener una tabla Markdown limpia a partir de JSON es pasarlo por CSV. Revisa la estructura con el Formateador de JSON, reorganiza el array en CSV, pégalo en CSV a Markdown y obtienes una tabla compatible con GFM lista para copiar. Incluso los casos incómodos como los datos anidados o las respuestas de API encajan en el mismo flujo en cuanto añades un paso de aplanado.
Si vas a alimentar la tabla Markdown resultante a un LLM como contexto, Markdown supera a HTML en eficiencia de tokens y precisión de extracción. Para una comparación medida, consulta Markdown vs HTML para LLMs. Para profundizar en la conversión desde CSV, consulta Cómo convertir CSV en una tabla Markdown.