JSON Lines o array JSON: prepara registros para una API sin perder datos

JSON Lines y array JSON no son el mismo formato

JSON es un formato de texto para representar datos estructurados. JSON Lines, también llamado JSONL, organiza esos datos como registros: cada línea contiene un valor JSON independiente. La ayuda de Claris, por ejemplo, documenta la exportación de registros a un archivo de texto JSON Lines. Un array JSON, en cambio, es una única estructura que contiene una secuencia de valores entre corchetes. La diferencia importa porque un archivo puede ser válido como JSONL y no ser un único documento JSON válido para el consumidor que intenta leerlo.

Considera estas dos líneas: «{"id":1,"nombre":"Ana"}» y «{"id":2,"nombre":"Luis"}». Juntas representan dos registros en formato JSON Lines. El array equivalente es «[{"id":1,"nombre":"Ana"},{"id":2,"nombre":"Luis"}]». Los objetos y sus valores son los mismos; cambia la estructura que los agrupa. No basta con renombrar la extensión ni con pegar líneas una tras otra: primero hay que identificar qué formato se tiene y cuál se necesita.

• JSON Lines: un valor JSON por línea; el archivo puede contener varios registros independientes.
• Array JSON: un documento con corchetes que contiene cero o más valores separados por comas.

Confirma la estructura que exige el endpoint

Antes de transformar nada, consulta la documentación del endpoint concreto y, si existe, su especificación OpenAPI. Busca un ejemplo del cuerpo de la solicitud y comprueba si espera un array en la raíz, un objeto que contenga una propiedad de registros, un solo objeto o datos enviados de otra manera. No deduzcas la estructura por el nombre del endpoint ni por el hecho de que reciba varios registros: el contrato de esa operación es el que determina la forma admitida.

Anota también los requisitos del contrato para cada campo: nombres exactos, tipos de valor, propiedades obligatorias y comportamiento ante campos adicionales, nulos o vacíos. Un registro con el campo «id» como número no equivale necesariamente a otro que lo envía como texto. Si la documentación no aclara una regla, busca un ejemplo oficial o confirma la expectativa con el equipo responsable antes de preparar el lote completo. Cambiar la forma exterior del archivo no corrige incompatibilidades entre campos y contrato.

• Identifica el endpoint y el ejemplo de solicitud que corresponden a la operación real.
• Registra la forma de la raíz y los tipos esperados antes de modificar el archivo.
• Separa las reglas confirmadas de las dudas que requieren consulta.

Transforma una muestra sin alterar los registros

Trabaja primero con una copia pequeña que incluya registros representativos y, si existen, casos límite. Si el endpoint exige un array de objetos, la transformación conceptual consiste en colocar un corchete de apertura antes del primer objeto, separar los objetos con comas y cerrar el array después del último. No añadas comas después del último elemento. El resultado de dos registros sería: «[{"id":1,"nombre":"Ana"},{"id":2,"nombre":"Luis"}]». Esta es una ilustración de estructura, no una garantía de que ese endpoint concreto acepte esos campos.

Conserva cada nombre de propiedad, valor y tipo exactamente, salvo que el contrato indique una conversión necesaria. No conviertas «0012» en 12, no cambies un valor booleano por una cadena y no elimines propiedades porque parezcan repetidas. Si automatizas el armado, haz que el proceso lea cada línea como un valor JSON y construya una lista de valores; evita manipular el texto con reemplazos improvisados de saltos de línea o comas. Después, compara la muestra de entrada y salida campo por campo.

• Guarda el original sin cambios y transforma una copia.
• Prueba primero con pocos registros y conserva los tipos y valores originales.
• Genera la separación y los corchetes mediante una herramienta que entienda la estructura, no mediante sustituciones ciegas.

Detecta errores de sintaxis y registros inesperados

Un fallo frecuente es concatenar objetos sin convertirlos en un array: «{"id":1}{"id":2}». Aunque cada fragmento parezca un objeto, esa secuencia no tiene la estructura del array de ejemplo. También puede quedar una coma tras el último elemento, faltar un corchete o aparecer una comilla sin escapar dentro de una cadena. Examina el mensaje del analizador y la ubicación que indique; si el error señala una línea o posición, revisa el registro correspondiente y también el carácter inmediatamente anterior.

Inspecciona las líneas vacías y los valores que no sean objetos. No decidas por intuición que una línea vacía es un registro descartable: define esa regla de acuerdo con la fuente y el proceso receptor, y deja constancia de los descartes. Del mismo modo, «null», una cadena o un array pueden ser valores JSON, pero no son objetos de registro. Si el contrato espera objetos, identifícalos antes del envío en vez de forzar su aceptación o eliminarlos silenciosamente.

• Revisa corchetes, comas, comillas y escapes cuando no se pueda interpretar el resultado.
• Cuenta y clasifica líneas vacías o valores que no sean objetos.
• No ocultes errores descartando registros sin una regla acordada.

Valida registros, caracteres y resultado completo

Antes de enviar, compara el número de registros de origen con el número de elementos del array resultante. Si hay excepciones documentadas, registra cuántas líneas se omitieron y por qué; si no las hay, cualquier diferencia requiere investigación. Comprueba el primer y el último registro y revisa además una muestra intermedia. Estas comprobaciones ayudan a encontrar truncamientos al principio o al final, así como errores que afectan solo a una parte del archivo.

Valida que el resultado pueda interpretarse como un único JSON y que la raíz tenga la forma exigida. Revisa nombres de campos, tipos, valores nulos, cadenas vacías y caracteres especiales en casos representativos: comillas, barras invertidas, saltos de línea o caracteres acentuados. Confirma también la codificación que espera la herramienta o el endpoint; no la cambies sin comprobar el requisito. Si la validación falla, conserva el archivo original, corrige la causa y vuelve a ejecutar las comprobaciones sobre el resultado entero.

• Compara cantidades y explica cualquier diferencia.
• Comprueba primer registro, último registro y muestras intermedias.
• Valida sintaxis, raíz, campos, tipos, caracteres y codificación esperada.

Decide cuándo conservar JSON Lines

Convertir no siempre es mejor. Si el consumidor admite JSON Lines y el flujo se procesa registro por registro, conservar ese formato puede evitar crear un único array grande y permite trabajar con la organización original por líneas. La decisión depende de lo que acepte el proceso receptor y de cómo se vayan a manejar los errores. No presupongas que un endpoint admite JSONL porque acepte JSON, ni que aceptar un array implique admitir registros independientes.

El array puede ser necesario cuando el contrato pide una lista única dentro del cuerpo de una solicitud. En ese caso, evalúa también el tamaño del lote y la estrategia para informar fallos parciales, si la documentación lo especifica. Si no está claro si conviene enviar todo junto o en varios grupos, prueba con una muestra controlada y verifica la respuesta antes de ampliar el volumen. Mantén separados los datos originales, los transformados y los resultados de la prueba.

• Conserva JSON Lines si el consumidor lo admite y el procesamiento por registro resulta adecuado.
• Usa un array cuando esa sea la estructura exigida por el contrato.
• Comprueba tamaño y tratamiento de errores antes de enviar un lote completo.

Lista de comprobación y herramientas

Antes de cerrar la preparación, verifica que has identificado el formato de origen, confirmado el contrato y conservado una copia intacta. Prueba una muestra con más de un registro, valida la estructura resultante y compara campos y cantidades. Anota cómo trataste líneas vacías, registros mal formados y valores no esperados. Si la muestra pasa, aplica el mismo procedimiento al archivo completo y repite la validación; no des por seguro que el lote final es correcto solo porque una muestra pequeña lo fuera.

Si valoras un conversor, comprueba por separado sus formatos de entrada y salida, si distingue JSON Lines de JSON convencional, qué hace ante líneas vacías y registros inválidos, y cómo informa de errores. Prueba con casos que incluyan caracteres especiales y valores de tipos distintos. Apification ofrece integración de Cloud y servicios mediante REST API, OpenAPI, webhooks, iframe y JavaScript, y un asistente guiado para procesar datos y otros archivos. Esa descripción no confirma una conversión específica de JSON Lines: verifica que el formato requerido esté admitido antes de depender de una función concreta.

• Contrato confirmado y archivo original preservado.
• Muestra validada y recuentos comparados.
• Errores, líneas vacías y caracteres especiales revisados.
• Capacidades concretas del conversor verificadas antes de usarlo.

Preguntas frecuentes