Entrada (JSON)

Saída (esquema .proto)

O que esta ferramenta faz

Tem um payload JSON real — uma resposta de API de exemplo, um body de webhook, uma linha de um banco NoSQL — e quer modelar como uma mensagem Protocol Buffers? Digitar o esquema na mão é lento e fácil de errar, principalmente quando há objetos e arrays aninhados. Este conversor percorre o JSON, infere os tipos Protobuf de cada campo e devolve um esquema proto3 limpo, pronto para você colar no projeto.

A inferência de tipos segue o que você escreveria à mão: string para strings, bool para booleanos, int32 para inteiros que cabem em 32 bits, int64 para o resto, double para números não inteiros, repeated <T> para arrays de um tipo de elemento uniforme (uma única mensagem aninhada reutilizada para arrays de objetos) e blocos message aninhados para objetos aninhados. JSON não distingue uma struct de um map, então todos os objetos saem como mensagens aninhadas — troque por map<K, V> manualmente se seus dados forem de fato um map.

Nomes de campos são convertidos de camelCase ou kebab-case para o snake_case convencional do Protobuf. Os números de campo são atribuídos 1, 2, 3, … na ordem de declaração. A saída é proto3 válido — cole em um arquivo .proto, rode protoc ou buf, e você tem código gerado na linguagem que escolher. A conversão roda inteira no seu navegador — nem o JSON, nem nomes de campo, nem valores são enviados a lugar nenhum.

Como usar

Três passos. Funciona com qualquer objeto JSON bem formado — respostas de API, entradas de log, arquivos de fixture, o que for.

Cole seu JSON

Solte o JSON no editor da esquerda. A raiz precisa ser um objeto ({ ... }) — embrulhe um array em um objeto primeiro se seus dados começarem com array, p. ex. { "items": [...] }. Use dados realistas: quanto mais representativa for a amostra, melhor os tipos inferidos batem com o que você quer a longo prazo.

Se seu JSON tem chaves sem aspas, vírgulas finais ou outras esquisitices, passe primeiro pelo JSON Fixer — o Protobuf precisa de um objeto limpo para trabalhar.

Aperte Converter

Clique no botão verde Converter. O conversor percorre cada chave do JSON, escolhe um tipo Protobuf, monta blocos message aninhados para os objetos aninhados e emite o esquema com syntax = "proto3"; no topo. Os números de campo são atribuídos na ordem da fonte.

Use o .proto

Copie o esquema para um arquivo .proto no seu repositório. Revise os tipos inferidos — em campos onde a amostra JSON estava vazia (array vazio, null), você verá um comentário sinalizando que o tipo foi adivinhado. Ajuste o que for preciso e rode protoc ou buf generate para produzir código na sua linguagem.

Quando isto realmente economiza tempo

Modelar uma API de terceiros como Protobuf

Um fornecedor retorna JSON. Seu serviço armazena Protobuf. Pegue uma resposta real, cole aqui, ganhe um esquema de partida para o tipo e refine. Bem melhor do que ler a documentação e digitar 50 campos na mão.

Migrar um serviço baseado em JSON para gRPC

Você está migrando um microsserviço HTTP+JSON para gRPC. Cada formato de requisição e resposta precisa de um .proto. Converta cada payload capturado em esquema Protobuf, junte tudo num arquivo só e o contrato está esboçado.

Inicializar um módulo Buf

Montando um novo módulo Buf e precisa de esquemas realistas para começar? Converta suas fixtures JSON existentes e use a saída como semente para seus arquivos .proto — bem mais rápido do que digitar do zero.

Escrever fixtures de teste para código Protobuf

Sua equipe tem dados de teste em JSON. O código novo consome Protobuf. Gere o <code>.proto</code> a partir do JSON e deixe o codegen construir os tipos — fixtures e código ficam em sincronia.

Perguntas comuns

Meu JSON é enviado para algum lugar?

Não. O conversor roda inteiro no seu navegador como JavaScript. Seu JSON — chaves, valores, qualquer coisa sensível — nunca sai da sua máquina. Abra o DevTools e olhe a aba Network enquanto clica em Converter. Zero requisições.

Como ele escolhe entre int32, int64 e double?

Para valores inteiros, ele checa se o valor cabe num intervalo com sinal de 32 bits (-2^31 a 2^31-1). Se sim, int32. Senão, int64. Números não inteiros sempre viram double. Se você sabe que seus dados são sem sinal ou quer uma largura específica como fixed32, edite a saída — veja a tabela de tipos escalares para todos os tipos numéricos disponíveis e seus tradeoffs de codificação no fio.

Quando um objeto vira um map em vez de uma mensagem aninhada?

Sempre uma mensagem aninhada — nunca um map. JSON não distingue uma struct de um map, então adivinhar um ou outro erra metade das vezes. Se seus dados são de fato um map chave-valor (p. ex. metadados, headers, feature flags), abra a saída e troque message Foo { ... } por map<string, V> foo = N; na mão. O ajuste é mecânico e óbvio assim que você olha os dados.

E null e arrays vazios?

Os dois geram um comentário na saída sinalizando que o tipo foi adivinhado a partir de uma amostra degenerada. null cai em string com uma nota "nullable". Arrays vazios caem em repeated string com uma nota "empty array". Substitua esses tipos pelo que você realmente espera.

Por que arrays de tipos misturados saem como repeated string?

Protobuf não suporta listas heterogêneas direto. Se seu array JSON tem tipos misturados (algumas strings, alguns números), não há equivalente Protobuf limpo — você precisa de google.protobuf.Value, de um oneof, ou de refatorar o formato dos dados. O conversor sinaliza com um comentário para você decidir.

Lida com JSON profundamente aninhado?

Sim. Cada objeto aninhado vira uma message aninhada com um nome derivado em PascalCase. A profundidade de aninhamento só é limitada pela profundidade de pilha, não pelo conversor — mesmo respostas de API muito aninhadas são convertidas tranquilamente.

Posso fazer ida e volta JSON ↔ Protobuf com essas duas ferramentas?

Em grande parte. JSON para Protobuf te dá um esquema; Protobuf para JSON te dá uma amostra. Os formatos batem nos campos onde a amostra JSON tinha um valor representativo. Onde o JSON tinha null ou arrays vazios, o tipo Protobuf inferido é um chute, e a ida e volta só vai ser exata depois que você corrigir o tipo.

Ferramentas relacionadas

Se você está lidando com JSON e esquemas, estas combinam bem:

Conversor de JSON para Protobuf