FracturedJson

 (github.com/j-brooke)
6 pontos por GN⁺ 2026-01-03 | 1 comentários | Compartilhar no WhatsApp
  • Conjunto de utilitários de formatação que organiza dados JSON para facilitar a leitura humana enquanto mantém um formato compacto
  • Representa arrays e objetos em uma única linha sempre que possível e, quando a estrutura é semelhante, alinha em formato de tabela
  • Suporta preservação de comentários, mantendo junto comentários comuns em ambientes reais de uso, embora não façam parte do padrão JSON
  • Pode ser usado em vários ambientes, como biblioteca .NET, pacote JavaScript/TypeScript, extensão para VS Code e formatador no navegador
  • Uma ferramenta que melhora as limitações de legibilidade dos formatadores JSON existentes e aumenta a compreensão visual para desenvolvedores e analistas de dados

Visão geral do FracturedJson

  • FracturedJson é um conjunto de utilitários que gera um formato JSON compacto e, ao mesmo tempo, fácil de ler por humanos
    • Arrays e objetos são exibidos em uma única linha quando não são longos nem complexos demais
    • Várias linhas com estrutura semelhante são alinhadas por campo em formato de tabela
    • Arrays longos são distribuídos em várias linhas, com vários itens por linha
  • É possível controlar o formato de saída com várias configurações, e na maioria dos casos as definições padrão já produzem um resultado agradável de ler
  • Disponível como página de formatação no navegador, biblioteca .NET, pacote JavaScript/TypeScript e extensão para VS Code
  • Também há orientação separada para uma opção em Python

Motivação

  • A maioria das bibliotecas JSON oferece apenas dois formatos
    • Minified JSON: eficiente, mas difícil para humanos lerem
    • Beautified/Indented JSON: espalhado demais na tela, o que dificulta uma leitura rápida
  • O FracturedJson formata os dados como se tivessem sido escritos manualmente por uma pessoa
    • Mantém os contêineres em uma única linha quando não são complexos ou longos demais
    • Arrays ou objetos semelhantes são alinhados em formato de tabela

Como funciona (How It Works)

  • O FracturedJson usa quatro tipos de formatação
    1. Inlined: representa objetos ou arrays curtos e simples em uma única linha
      • A configuração MaxInlineComplexity controla o nível de aninhamento permitido
    2. Compact Multiline Array: coloca vários itens por linha, mas distribuídos em múltiplas linhas
      • MaxCompactArrayComplexity ajusta o nível de aninhamento permitido, e -1 pode desativar esse modo
    3. Table: alinha itens com estrutura semelhante em colunas
      • Se os contêineres internos forem complexos demais, apenas parte deles será reduzida
      • Pode ser controlado com MaxTableRowComplexity e TableCommaPlacement
    4. Expanded: quando nenhuma das condições acima se aplica, exibe cada item em múltiplas linhas com indentação

Tratamento de comentários

  • O padrão JSON não permite comentários, mas o FracturedJson oferece preservação de comentários
    • Os comentários são mantidos junto dos elementos relacionados, e tanto comentários de múltiplas linhas quanto comentários inline podem ser processados

Discussions

  • Há um espaço no GitHub Discussions para perguntas de usuários, feedback e sugestões
  • É possível discutir o projeto e propor melhorias

Leituras relacionadas

1 comentários

 
GN⁺ 2026-01-03
Comentários do Hacker News

  • Atualmente, este projeto tem duas implementações mantidas
    uma é a versão em C# (FracturedJson .NET Library) e a outra é a versão em TypeScript/JavaScript (FracturedJsonJs)
    antigamente também havia uma versão pura em Python, mas ela não é mais mantida e foi substituída por um wrapper em Python para o código em C# (fractured-json)
    essa versão em Python informa que exige o runtime do .NET, então a desvantagem é que ela não é fácil de instalar apenas com pip install
    acho que isso é uma boa oportunidade para criar uma conformance suite independente de linguagem — ou seja, um conjunto de testes orientados a dados capaz de verificar se várias implementações se comportam da mesma forma
    por sinal, a antiga versão em Python já usava testes nesse formato (dados de teste do compact-json)

    • Acabei de portar para Rust e pretendo fazer a manutenção daqui para frente
      talvez valha a pena adicionar isso ao comentário original
      mais detalhes em fracturedjson-rs GitHub e no pacote no crates.io
      há um comentário explicando isso aqui
    • É uma boa ideia, mas acho difícil ir além dos casos de teste e chegar a uma garantia de equivalência entre programas
    • Isso é quase uma função pura, então é muito fácil escrever um test harness
    • Testes orientados a dados são muito eficazes para construir confiança em uma biblioteca
      html5lib-tests e também o xss-bench que eu fiz são exemplos disso

  • Fiz uma versão portada para Rust, e com a ferramenta de CLI dá para formatar JSON nesse estilo
    pode ser instalado via fracturedjson-rs e pacote no crates.io (cargo install fracturedjson)
    oferece várias opções e permite controle fino sobre forma de comentar, estilo de indentação e limite de largura de linha, entre outros

    • A versão portada também é uma obra derivada, então é preciso manter a atribuição de copyright do autor original

  • Este projeto é realmente muito legal
    gosto da proposta de tornar o JSON mais fácil para humanos lerem
    eu estou fazendo o oposto com o bonjson, deixando o JSON mais amigável para máquinas
    ele tem exatamente os mesmos recursos e limitações do JSON, mas consegue ler e gravar 35 vezes mais rápido
    não há novos tipos nem recursos, ele apenas faz exatamente o que o JSON consegue fazer

    • JSON é uma notação simples, então acho que seria necessário um modelo de dados estruturado
      por exemplo, ele não especifica largura em bits para números nem distingue inteiro de ponto flutuante
      com esse modelo, seria possível ter um mapeamento 1:1 entre representações
      estou escrevendo este texto sobre esse tema
    • Interessante, mas diante da afirmação de que “ele pode fazer tudo que o JSON faz”, essas restrições de segurança parecem um pouco inesperadas
      por exemplo, uma string como "a\u0000b" é um JSON válido, e se isso não puder ser serializado, então essa afirmação não se sustenta por completo
    • Tenho curiosidade sobre o que levou você a criar isso
      eu já fiz um serializer que salva/carrega JSON e arquivos binários por meio de uma interface comum
      na minha experiência, JSON era um formato com muitas limitações e poucas vantagens
      então eu o substituí por um formato mais flexível, em que vírgulas, dois-pontos e aspas podem ser omitidos, e strings multilinha e comentários são permitidos
      já passou da hora de parar de fingir que JSON é sempre um formato “bom para humanos lerem”
      precisamos de uma alternativa padrão para ambientes que não são centrados em JSON
    • Isso me lembrou o Lite3, que apareceu recentemente
    • Fiquei curioso sobre a taxa de compressão

  • Surpreendente
    eu também implementei algo parecido em Python com cerca de 200 linhas, mas não sabia que já existia uma biblioteca assim

  • Fico pensando se existe uma opção para receber entrada por pipe, como no jq

    • Pelo código da CLI em C# no repositório, dá para especificar entrada/saída padrão ou arquivos
      a versão em JavaScript e o wrapper em Python também oferecem a mesma ferramenta de CLI
    • O RCL faz pretty-print por padrão
      com rcl e você vê no formato RCL, e com rcl je vê a saída em JSON
      ele não faz alinhamento em tabela como o FracturedJson, mas usa o algoritmo A Prettier Printer, de Philip Wadler, para quebrar linhas automaticamente de acordo com a largura
    • Também dá para criar um arquivo temporário com substituição de processo <()
    • Na maioria dos casos, se você passar - como nome do arquivo de entrada, ele vai ler do stdin

  • Eu criei um formatador de JSON chamado Virtuous, e isso foi tão impressionante que quase me deu vontade de abandonar o meu formatador
    é um trabalho realmente excelente

  • Eu fiz um script em Groovy chamado “mommyjson”
    em vez de preservar a formatação do JSON, ele mostra em uma linha a relação com os elementos pais (índice no array, nome do objeto etc.), para que seja mais intuitivo localizar os dados
    Ver código
    como Groovy não é popular, seria bom se surgisse um port para Python

    • Boa ideia! O fato de existirem várias ferramentas assim mostra que é claramente uma funcionalidade que as pessoas precisam
      alguns exemplos são o gron e o jstream, que eu fiz
      talvez fique mais fácil de entender se você adicionar uma saída de exemplo de uso
    • Fiquei curioso se há um exemplo da saída

  • Tenho dúvidas se JSON realmente é um formato que precisa ser melhorado para leitura humana
    há maneiras muito melhores de mostrar dados ao usuário, e acho que JSON deve ser usado para transmissão de dados entre sistemas

    • Normalmente usa-se esse tipo de ferramenta quando não há um esquema claro nem ferramentas de visualização
      é útil em situações de depuração em que você precisa entender rapidamente dados complexos e aninhados
      isso acontece com frequência principalmente ao trabalhar em código de integração com sistemas externos
    • Eu também costumo usar jq ou python -m json.tool para ler dados em JSON
      se uma ferramenta como essa mostrar melhor do que eles, já tem bastante valor
    • Se você abandonar o aspecto legível para humanos, JSON vira uma codificação ineficiente
      no fim, a principal vantagem do JSON é ser legível tanto para humanos quanto para máquinas, então ele ainda faz sentido para depuração

  • Gostei muito desta ideia
    o motivo de a adoção ser lenta hoje é principalmente a falta de suporte na maioria das linguagens e em gerenciadores de pacotes (como o homebrew)
    se a biblioteca .NET fosse compilada como uma biblioteca compartilhada compatível com C, seria fácil usá-la em várias linguagens

  • É uma abordagem interessante
    seria bom se formatadores de código também funcionassem assim
    os formatadores atuais são rígidos demais e dificultam entender a estrutura

    • Eu fiz um formatador de C++ que usa apenas dois tipos de objeto: tabelas com alinhamento por tabs e blocos de linha única
      os comentários são alinhados à direita para ficarem organizados
      graças a essa estrutura, também é fácil alinhar em 2D blocos switch-case e tabelas de macros
      codifiquei a camada básica em uma hora e agora estou projetando a detecção automática de blocos combinando LSP com observação de código
    • Já tive a experiência de criar meu próprio formatador de XML para fazê-lo parecer tabular
      o ideal teria sido abandonar o XML, mas por restrições de legado não havia como evitar isso