FracturedJson

• Un conjunto de utilidades de formateo que ordena los datos JSON para que sean fáciles de leer sin dejar de mantener una forma compacta
• Expresa arreglos y objetos en una sola línea siempre que sea posible y, cuando la estructura es similar, los alinea en formato de tabla
• Compatible con preservación de comentarios, manteniendo comentarios que no existen en el estándar JSON pero que son comunes en entornos reales
• Se puede usar en distintos entornos como biblioteca de .NET, paquete de JavaScript/TypeScript, extensión de VS Code y formateador para navegador
• Una herramienta que mejora la comprensión visual para desarrolladores y analistas de datos, superando las limitaciones de legibilidad de los formateadores JSON existentes

---

Resumen de FracturedJson

• FracturedJson es un conjunto de utilidades que genera un formato JSON compacto pero fácil de leer para personas
  • Los arreglos y objetos se muestran en una sola línea si no son demasiado largos ni complejos
  • Varias líneas con estructura similar se alinean por campos y se muestran en forma de tabla
  • Los arreglos largos se muestran en varias líneas, colocando varios elementos por línea
• El formato de salida puede controlarse con varias opciones y, en la mayoría de los casos, la configuración predeterminada ya produce resultados agradables de ver
• Se ofrece como página de formateo basada en navegador, biblioteca de .NET, paquete de JavaScript/TypeScript y extensión de VS Code
• También se indica por separado una opción para Python

Motivation

• La mayoría de las bibliotecas JSON solo ofrecen dos formatos
  • Minified JSON: eficiente, pero difícil de leer para personas
  • Beautified/Indented JSON: demasiado expandido, lo que dificulta una comprensión rápida
• FracturedJson formatea los datos como si una persona los hubiera escrito directamente
  • Mantiene los contenedores en una sola línea salvo cuando son demasiado complejos o largos
  • Los arreglos u objetos similares se alinean en formato de tabla

Cómo funciona (How It Works)

• FracturedJson usa cuatro tipos de formateo
  1. Inlined: representa en una sola línea objetos o arreglos cortos y simples
     • La opción MaxInlineComplexity controla el nivel de anidación permitido
  2. Compact Multiline Array: coloca varios elementos por línea, pero los muestra distribuidos en varias líneas
     • MaxCompactArrayComplexity ajusta la complejidad permitida de anidación y puede desactivarse con -1
  3. Table: alinea elementos con estructura similar en formato de columnas
     • Si los contenedores internos son demasiado complejos, solo una parte se reduce
     • Puede controlarse con MaxTableRowComplexity y TableCommaPlacement
  4. Expanded: si no se cumple ninguna de las condiciones anteriores, muestra cada elemento en varias líneas con sangría

Manejo de comentarios

• Aunque el estándar JSON no permite comentarios, FracturedJson es compatible con preservación de comentarios
  • Los comentarios se mantienen junto con los elementos relacionados, y se admiten tanto comentarios multilínea como comentarios en línea

Discussions

• Ofrece un espacio de GitHub Discussions para preguntas de usuarios, comentarios y sugerencias
• Permite debatir sobre el proyecto y proponer mejoras

[GN⁺]

Comentarios en Hacker News

• Actualmente este proyecto tiene dos implementaciones mantenidas.
  Una es la versión en C# (FracturedJson .NET Library) y la otra es la versión en TypeScript/JavaScript (FracturedJsonJs).
  Antes también había una versión pura en Python, pero ya no se mantiene y fue reemplazada por un wrapper de Python que envuelve el código en C# (fractured-json).
  Se indica que esta versión de Python requiere el runtime de .NET, así que la desventaja es que no se instala fácilmente solo con pip install.
  Creo que esta situación es una buena oportunidad para crear una conformance suite independiente del lenguaje: un conjunto de pruebas basado en datos que permita verificar si varias implementaciones se comportan igual.
  Como referencia, la antigua versión en Python ya usaba pruebas de este tipo (datos de prueba de compact-json).

  • Acabo de portarlo a Rust y planeo darle mantenimiento en adelante.
    Tal vez valdría la pena añadirlo al comentario original.
    Más detalles en fracturedjson-rs GitHub y en el paquete de crates.io.
    El comentario relacionado con la explicación está aquí.
  • Es una buena idea, pero creo que es difícil ir más allá de los casos de prueba hasta llegar a una garantía de equivalencia de programas.
  • Esto está muy cerca de ser una función pura, así que es muy fácil escribir un harness de pruebas.
  • Las pruebas basadas en datos son muy efectivas para generar confianza en una librería.
    html5lib-tests o xss-bench, que yo hice, son ejemplos de eso.

• Hice una versión portada a Rust, y con la herramienta CLI se puede formatear JSON con este formato.
  Se puede instalar desde fracturedjson-rs y el paquete de crates.io (cargo install fracturedjson).
  Ofrece varias opciones y permite un control detallado de cosas como el estilo de comentarios, el estilo de indentación y el límite de ancho de línea.

  • La versión portada también es una obra derivada, así que debe conservarse la atribución de copyright del autor original.

• Este proyecto está realmente genial.
  Me gusta la idea de hacer que JSON sea más legible para humanos.
  Yo estoy desarrollando bonjson, que va en la dirección opuesta y hace que JSON sea más amigable para máquinas.
  Tiene exactamente las mismas capacidades y restricciones que JSON, y puede leerse y escribirse 35 veces más rápido.
  No agrega tipos ni funciones nuevas; simplemente hace exactamente lo que JSON puede hacer.

  • JSON es una notación simple, así que creo que hace falta un modelo de datos estructurado.
    Por ejemplo, no especifica el ancho en bits de los números ni distingue explícitamente entre enteros y punto flotante.
    Si existiera ese modelo, sería posible un mapeo 1:1 entre representaciones.
    Estoy escribiendo este texto sobre ese tema.
  • Interesante, pero frente a la afirmación de que “puede hacer todo lo que JSON puede hacer”, las restricciones de seguridad resultan un poco inesperadas.
    Por ejemplo, una cadena como "a\u0000b" es JSON válido; si no puede serializarse, entonces esa afirmación no se sostiene del todo.
  • Me da curiosidad saber qué te llevó a crear esto.
    Yo una vez hice un serializador que guardaba/cargaba JSON y archivos binarios mediante una interfaz común.
    En mi experiencia, JSON era un formato con muchas limitaciones y pocas ventajas.
    Por eso lo cambié por un formato más flexible donde se pueden omitir comas, dos puntos y comillas, y que permite cadenas multilínea y comentarios.
    Ojalá ya dejemos de fingir que JSON siempre es un formato “fácil de leer para humanos”.
    Hace falta una alternativa estándar para entornos no centrados en JSON.
  • Me recordó a Lite3, que apareció hace poco.
  • Me pregunto cómo anda en compresión.

• Qué sorpresa.
  Yo también implementé algo parecido en Python en unas 200 líneas, pero no sabía que ya existía una librería así.

• Me pregunto si hay una opción para recibir entrada por pipe como jq.

  • Si ves el código del CLI en C# dentro del repositorio, se puede especificar entrada/salida estándar o archivos.
    La versión en JavaScript y el wrapper de Python también ofrecen la misma herramienta CLI.
  • RCL hace pretty-print por defecto.
    Con rcl e puedes ver el formato RCL y con rcl je la salida JSON.
    No tiene alineación en tablas como FracturedJson, pero se basa en el algoritmo A Prettier Printer de Philip Wadler, así que hace saltos de línea automáticos según el ancho disponible.
  • También podrías usar sustitución de procesos con <() para crear un archivo temporal y procesarlo.
  • En la mayoría de los casos, si indicas - como nombre del archivo de entrada, puede leer desde stdin.

• Hice un formateador JSON llamado Virtuous, y esto me impresionó tanto que hasta me dieron ganas de abandonar mi propio formateador.
  De verdad es un trabajo excelente.

• Yo hice un script de Groovy llamado “mommyjson”.
  En lugar de conservar el formato JSON, muestra en una sola línea la relación de parentesco de cada elemento (índice de arreglo, nombre de objeto, etc.) para que sea intuitivo ubicar los datos.
  Ver código
  Como Groovy no es popular, estaría bien que existiera un port a Python.

  • ¡Buena idea! Viendo que existen varias herramientas así, parece claro que es una funcionalidad que la gente realmente necesita.
    Algunos ejemplos son gron y jstream, que hice yo.
    Tal vez sería más fácil de entender si añadieras una salida de ejemplo de uso.
  • Me pregunto si hay algún ejemplo de salida.

• Me pregunto si JSON de verdad es un formato que necesite mejoras para hacerlo más legible para humanos.
  Hay muchas mejores formas de mostrar datos al usuario, y creo que JSON está más bien para transferir datos entre sistemas.

  • La razón para usar herramientas así normalmente es que no hay un esquema claro ni herramientas de visualización.
    Son útiles en situaciones de depuración donde necesitas entender rápidamente datos complejos y anidados.
    Eso pasa muy seguido, sobre todo cuando trabajas en código de integración con sistemas externos.
  • Yo también uso seguido jq o python -m json.tool para leer datos JSON.
    Si una herramienta como esta logra mostrarlos mejor, ya tiene suficiente valor.
  • Si se abandona el aspecto legible para humanos, JSON pasa a ser una codificación ineficiente.
    Al final, la ventaja de JSON es que pueden leerlo tanto humanos como máquinas, así que para depuración sigue teniendo sentido.

• Me gusta mucho esta idea.
  La razón principal por la que su adopción va lenta ahora mismo es la falta de soporte en la mayoría de los lenguajes y en gestores de paquetes (como homebrew).
  Si la librería de .NET se compilara como una biblioteca compartida compatible con C, podría usarse fácilmente desde muchos lenguajes.

• Es un enfoque interesante.
  Ojalá los formateadores de código también funcionaran así.
  Los formateadores actuales son demasiado rígidos, y eso hace difícil entender la estructura.

  • Yo hice un formateador de C++ que solo usa dos tipos de objetos: tablas alineadas por tabulaciones y bloques de una sola línea.
    Los comentarios se alinean a la derecha para que queden ordenados.
    Gracias a esa estructura, incluso bloques switch-case o tablas de macros pueden alinearse fácilmente en 2D.
    La capa base la programé en una hora, y ahora estoy diseñando la detección automática de bloques combinando LSP y observación del código.
  • Hace tiempo también hice mi propio formateador XML para que se viera como una tabla.
    En un mundo ideal habría abandonado XML, pero por restricciones heredadas no había opción.