Preparar JSON, tablas Markdown y texto HTML

Decide qué necesita el destino

Una misma exportación puede tener varias representaciones útiles. Un programa puede necesitar objetos JSON con claves conocidas. El README de un proyecto puede necesitar una tabla Markdown corta. Un ejemplo en HTML puede necesitar mostrar un ampersand (&) o unos corchetes angulares sin que el navegador los lea como marcado. Elige primero el destino. Una tabla que se ve bien en un navegador no es necesariamente un origen fiable para volver a importar registros en un programa.

Conserva un original con un delimitador conocido o una estructura documentada. Por ejemplo, un equipo pequeño puede tener un CSV con ticket_id, summary y status. Genera por separado el JSON legible por máquinas y la tabla de presentación a partir de ese CSV. No cojas la tabla renderizada, la copies de vuelta al portapapeles y la uses como siguiente fuente de verdad. En ese viaje de ida y vuelta es fácil perder valores vacíos, ceros a la izquierda y saltos de línea.

Decide qué debe quedar exacto. Si un identificador tiene cinco dígitos con sus ceros a la izquierda, anota que es texto aunque parezca un número. Si una nota puede incluir un salto de línea, consérvalo en el original y elige por separado cómo mostrarlo. Prueba con unos cuantos registros representativos antes de convertir el origen completo.

Comprueba la sintaxis JSON antes de leer los datos

El JSON válido usa comillas dobles para los nombres de propiedad y los valores de cadena. No admite comentarios, comas finales ni un marcador como undefined. Una lista empieza con un corchete; un objeto empieza con una llave. Pega solo los datos, no la valla de código Markdown que rodea un ejemplo ni una asignación como const config =. La notación de objetos de JavaScript y JSON se parecen, pero muchas cosas válidas en un archivo JavaScript no lo son en JSON.

{ "ticket_id": "00123", "open": true, "note": null }

Empieza con un ejemplo pequeño y válido para saber si el error está en tu origen o en cómo se copió. Si el formateador informa de un error de análisis, mira la zona indicada y el valor anterior. Unas comillas de cierre que faltan pueden hacer que el error se detecte más adelante del carácter que realmente tienes que corregir. Las comillas tipográficas que se pegan desde un documento son caracteres de texto, no delimitadores de cadena JSON.

Repara un error cada vez y vuelve a ejecutar la comprobación. Evita reemplazar las comillas en bloque: unas comillas dentro de una cadena correctamente escapada forman parte del valor y no deben cambiarse.

Abre el formateador JSON y comprueba la sintaxis

Elige entre un formato legible o una salida compacta

La sangría ayuda a una persona a ver dónde empieza y termina cada registro o valor anidado. Usa el formato con sangría cuando revises una muestra, compares dos versiones o pongas un objeto pequeño en la documentación. Elige dos o cuatro espacios según las convenciones del proyecto que lo recibe. Usa la minificación cuando necesites una representación compacta y quien la consuma vaya a interpretarla de todos modos. Minificar no es comprimir, cifrar ni una forma de ocultar datos.

El formateador valida el texto y después cambia los espacios que quedan fuera de los elementos del JSON. No recrea el resultado convirtiendo cada número en un número de JavaScript y volviéndolo a escribir. Por ejemplo, los caracteres de 9007199254740993, 1e-7 y -0 pueden quedar tal como estaban escritos. Un escape dentro de una cadena sigue siendo un escape en la salida. Es útil para dar formato a una exportación sin cambiar en silencio cómo se escribió un valor.

Esa conservación no hace que un sistema receptor sea capaz de almacenar cualquier número con exactitud. Si un identificador puede superar el rango de enteros seguros de un sistema, acordad antes de exportar representarlo como cadena. Inspecciona el valor realmente importado, sobre todo cuando otra aplicación pueda convertirlo en número.

Da formato legible a tu JSON o minifícalo

Separa las comprobaciones de sintaxis de las de esquema

Una comprobación de sintaxis confirma que un analizador JSON puede leer el texto. No confirma que una API o un importador lo vaya a aceptar. Por ejemplo, tanto {"ticket_id":"00123"} como {"ticket_id":123} son JSON válido. Solo la cadena conserva ese código exacto. Igualmente, un objeto y una lista de objetos pueden ser ambos válidos aunque un importador solo acepte una de esas estructuras.

Comprueba los nombres de campo, los tipos y los campos obligatorios que espera la aplicación receptora. Presta atención a null, a una cadena vacía y a una propiedad ausente: pueden significar cosas distintas. Si la aplicación tiene un ejemplo de importación, empieza con esa estructura. Después añade un valor representativo de tus datos y pruébalo. Siempre que sea posible, usa un entorno de pruebas o la vista previa de importación de la aplicación antes de modificar registros reales.

Busca claves repetidas dentro de un objeto. Un formateador que conserva los elementos originales no las deduplica, y los sistemas pueden discrepar sobre qué valor usar. Si la misma propiedad aparece dos veces, corrige el origen para expresar el valor deseado una sola vez. Un resultado bien formateado y sin errores de sintaxis sigue sin ser prueba de que se hayan superado las reglas de negocio ni las restricciones de unicidad.

Comprueba el JSON después de corregir el origen

Convierte una muestra pequeña de CSV antes de la exportación completa

Abre el convertidor CSV y JSON con un encabezado y dos o tres filas. Comprueba si la primera fila debe aportar las claves de los objetos. Sin encabezado, una matriz de campos puede ser una representación mejor. Si dos encabezados se repiten, renómbralos de forma deliberada en lugar de esperar que dos propiedades de objeto con el mismo nombre identifiquen dos columnas distintas. Guarda una correspondencia si la importación exige nombres de campo estandarizados.

ticket_id,summary,status
00123,"Cable, soporte & base",abierto
00124,"La etiqueta dice <listo>",cerrado

Las comillas protegen la coma del primer resumen. El ampersand y los corchetes angulares son contenido literal del CSV. No necesitan entidades HTML en la versión CSV ni JSON solo porque alguien pueda verlos después en una página web. Aplica el escape HTML únicamente cuando generes una versión para ese contexto. Comprueba que el JSON sigue conteniendo exactamente los mismos resúmenes y que los ID de ticket son cadenas con sus ceros iniciales.

Para una tabla con campos de varias líneas o delimitada por punto y coma, sigue la guía de listas y tablas para comprobar la interpretación. Un campo no debería cambiar de columna solo porque contenga un signo de puntuación o un salto de línea.

Haz una tabla aparte para la documentación

Cuando la gente solo necesite ver unos cuantos registros, genera una tabla Markdown directamente desde el CSV. Elige el delimitador correcto, confirma el ajuste del encabezado y previsualiza el resultado en el destino real. Si el resumen incluye una barra vertical, el conversor la escapa para que se quede dentro de la celda en lugar de actuar como límite de columna. Si la entrada incluye corchetes angulares literales, la tabla generada los representa como texto en lugar de incrustar como marcado el valor que parece una etiqueta.

Limita un ejemplo de documentación a las columnas que importan. Si muestras una convención de nombres, puede que necesites el identificador del ticket y el resumen, pero no una nota interna extensa. Usa ejemplos sintéticos cuando el origen contenga información personal o confidencial. La utilidad funciona en local, pero copiar un resultado en una incidencia o un repositorio públicos es otra acción, con otro público.

El renderizado de las tablas Markdown no es idéntico en todas partes. Previsualiza una fila con una barra vertical escapada, una celda que contenga un salto de línea y un valor muy largo. Algunos renderizadores no admiten tablas o pueden suprimir los saltos incrustados. Si ocurre, usa una lista corta o un archivo aparte en lugar de dar por hecho que el código de la tabla en bruto siempre se verá bien.

Genera una tabla Markdown a partir de tu muestra

Escapa el texto para HTML en el contexto adecuado

HTML usa los corchetes angulares para marcar las etiquetas y el ampersand para iniciar las referencias de caracteres. Si escribes código fuente HTML y quieres mostrar el texto literal Bolsa & caja <lista>, escapa esos caracteres para un nodo de texto. Así el navegador muestra el texto en lugar de tratar <lista> como marcado. Un ampersand que ya forma parte de una entidad no debe codificarse por segunda vez por accidente, salvo que quieras mostrar la propia referencia.

Entrada: Bolsa & caja <lista>
Salida:  Bolsa &amp; caja &lt;lista&gt;

Usa la herramienta con el valor literal, no con una página completa que quieras mantener funcional. Escapar una página entera convierte las etiquetas en texto visible. Para una plantilla o una aplicación, prefiere su propio escapado según el contexto o un enlace de datos solo de texto. Un valor insertado en un nodo de texto HTML, en una URL, en un atributo o en un script no usa necesariamente las mismas reglas.

El codificador no es un sanitizador de HTML. No hace seguro una plantilla, un enlace ni un script cualquiera. Si solo quieres mostrar texto sin formato en un editor, normalmente no necesitas codificarlo. Usa el escapado porque el destino lo exige, no porque el original contenga signos de puntuación.

Codifica para HTML una muestra de texto literal

Decodifica una capa y comprueba qué ha cambiado

A veces una nota llega como Bolsa & caja aunque necesites mostrarla como texto normal. Elige decodificar e inspecciona el resultado antes de aplicarlo a la entrada. Una pasada convierte una referencia reconocida en un carácter; no decodifica una y otra vez hasta que el resultado deja de cambiar. Ese comportamiento importa cuando una referencia aparece en un ejemplo didáctico y debe verse en lugar de interpretarse.

Por ejemplo, una cadena que contiene < se convierte en la referencia literal < tras una decodificación, y en un signo de menor que tras otra. Decide qué representación espera el siguiente programa antes de hacer una segunda pasada. Si el origen es HTML, pregúntate si necesitas el texto visible de la página o solo el código fuente decodificado. Decodificar referencias no quita las etiquetas ni extrae el texto de una maquetación.

Las referencias HTML y la codificación de URL sirven para cosas distintas. Los caracteres %26 codifican un ampersand en un componente de URL; & lo representa en código fuente HTML. Si estás investigando un parámetro de URL copiado, usa el decodificador de componentes de URL con el valor en lugar de aplicar la decodificación HTML a cada signo de porcentaje.

Decodifica una capa de referencias HTML

Recorre un traspaso realista de dos filas

Coge los dos tickets anteriores y guarda el CSV sin cambios. Para una importación automática, convierte el encabezado y las filas en objetos JSON. Dale formato con sangría al resultado para poder inspeccionar las claves y los dos identificadores. Compara el resumen del primer ticket con el CSV: la coma y el ampersand deben seguir ahí. Revisa el segundo resumen y confirma que los corchetes angulares siguen siendo parte de la cadena y no una etiqueta de una plantilla. Usa la vista previa de importación para confirmar lo que ve el sistema receptor.

Para el ticket de revisión, genera una tabla Markdown directamente desde el mismo CSV y renderízala en el destino. La salida está pensada para que alguien la lea, así que quita las columnas innecesarias solo en esa copia de presentación. Si además necesitas un ejemplo de código HTML que muestre un resumen, codifica para HTML solo el valor de muestra. No sustituyas el resumen almacenado por la versión codificada.

Cuando un compañero pregunte qué versión reutilizar, señala el origen sin cambios o la exportación acordada legible por máquinas. Etiqueta aparte la copia de presentación. Esta pequeña distinción evita que la tabla copiada de una página de documentación se convierta en la siguiente importación de datos sin que nadie se dé cuenta de que perdió campos.

Crea una tabla aparte para el ticket de revisión

Verifica cada salida en la aplicación que la recibe

Antes de compartir, comprueba el primer y el último registro y un valor complicado del medio. Con JSON, valida la sintaxis y comprueba después los campos esperados y los tipos de valor en el importador. Con Markdown, previsualiza la página real e inspecciona el encabezado, la alineación y cualquier signo de puntuación que se parezca a sintaxis. Con HTML, comprueba tanto el código fuente como lo que aparece en el navegador. Son comprobaciones distintas; un resultado correcto en un formato dice poco sobre los demás.

Si una versión falla, vuelve al origen guardado y aísla el registro más pequeño que reproduzca el problema. Después decide si el origen está mal formado, si el ajuste de conversión es incorrecto o si el destino interpreta el resultado de forma distinta a la esperada. Evita convertir una y otra vez el archivo completo cambiando varios ajustes a la vez: así es difícil saber qué cambio arregló el problema, y puede ocultar una pérdida de datos distinta.

Guarda una entrada en miniatura y el resultado esperado como referencia para la próxima exportación. Incluye un identificador con ceros a la izquierda, un campo vacío y algunos signos de puntuación. Un buen ejemplo de tres filas facilita actualizar más adelante un proceso sin tener que adivinar qué debía pasar con las filas raras.

Haz la última comprobación de sintaxis JSON antes de exportar