입력 (.proto 스키마)

출력 (JSON 샘플)

이 도구가 하는 일

Protocol Buffers 스키마가 있고, 그중 한 메시지가 어떤 JSON 모양인지 예시가 필요할 때 — 테스트 픽스처용, OpenAPI 예시용, gRPC 스텁 응답용 등 무엇이든 말이죠. 긴 .proto 파일을 보고 JSON 모양을 손으로 치는 건 지루하고 실수가 쉽습니다. 이 변환기는 스키마를 읽고 마지막에 선언된 message(보통의 "바깥쪽" 타입)를 골라 필드 단위로 그에 맞는 JSON 객체를 출력합니다.

출력은 공식 proto3 기본값을 사용합니다: string과 bytes는 빈 문자열, 숫자 타입은 0, bool은 false, repeated는 [], map은 {}, enum 필드는 0번 enum 상수. 중첩 메시지는 재귀적으로 펼쳐집니다. 64비트 정수는 proto3 JSON 매핑 사양에 맞춰 JSON 문자열로 나옵니다 — JS Number에 int64를 넣으면 정밀도를 잃기 때문입니다.

모든 작업은 브라우저에서 로컬로 일어납니다 — .proto 업로드 없음, 서버로 스키마 전송 없음, AI 추론 호출 없음. syntax/package/import 지시어, 주석(라인·블록), 중첩된 message와 enum 블록, oneof, map<K, V>, repeated, optional, 필드 옵션(읽지만 무시)을 처리하는 손수 만든 파서가 돌 뿐입니다. protobufjs 같은 풀 런타임이 필요하다면 그건 다른 문제이지만, "이 스키마에서 JSON 모양만 줘"가 목적이라면 이게 더 빠릅니다.

사용 방법

세 단계입니다. 출력 JSON은 픽스처, 예시 블록, 요청 본문에 그대로 붙여넣을 수 있습니다.

.proto 스키마 붙여넣기

왼쪽 에디터에 스키마를 넣으세요. 맨 위의 syntax = "proto3";는 있어도 되고 없어도 됩니다 — 파서는 신경 쓰지 않습니다. 주석, package 선언, import 문은 모두 깔끔하게 건너뜁니다. 메시지가 여러 개라면 파서는 최상위 마지막 message(전형적인 바깥쪽/복합 타입)를 루트로 사용합니다.

다른 메시지를 변환하고 싶나요? 원하는 메시지를 파일의 맨 아래로 옮기세요. 스키마에는 중첩 타입, enum, oneof 블록이 들어가도 모두 해결됩니다.

Convert 누르기

초록색 Convert 버튼을 클릭합니다. 파서가 스키마를 토큰화하고 메시지 트리를 만든 뒤, 루트 메시지를 따라가며 각 필드에 proto3 기본값을 출력합니다. 중첩 메시지는 인라인으로 펼쳐집니다. repeated 필드는 요소 모양을 알려주는 한 개짜리 배열을 만듭니다 — 빈 배열이면 구조가 안 보이기 때문입니다.

JSON 사용하기

결과를 테스트 픽스처, OpenAPI 예시 블록, gRPC-Web 목, 또는 요청/응답 모양이 필요한 어디에든 복사하세요. 키는 .proto의 필드 이름과 정확히 일치합니다 — 코드젠이 camelCase를 쓴다면 나중에 바꾸세요.

실제로 시간을 아껴주는 순간

테스트용 gRPC 응답 스텁 만들기

서비스 핸들러가 Protobuf 응답을 반환합니다. 단위 테스트는 메시지 모양에 맞는 JSON 픽스처가 필요합니다. <code>.proto</code>를 붙여넣고, JSON을 가져와 픽스처 폴더에 떨어뜨리세요. 30개 필드를 손으로 치다가 하나 빠뜨리는 일은 끝.

gRPC-gateway용 OpenAPI 예시

Protobuf 서비스를 REST로 노출하려고 grpc-gateway 같은 걸 돌리고 있나요? 각 오퍼레이션마다 JSON 예시가 필요합니다. .proto 메시지를 JSON 스켈레톤으로 변환해 spec의 example 키 아래에 붙여넣으세요.

JSON Schema 시작점 만들기

<code>.proto</code> 계약에 맞는 JSON 요청을 검증하고 싶을 때. 먼저 JSON 샘플로 변환한 뒤 JSON-Schema-from-sample 도구에 넘기면 몇 초 안에 출발점 스키마를 얻습니다.

API 클라이언트에서 요청 본문 채우기

HTTP로 트랜스코딩된 gRPC API를 Postman이나 curl로 테스트 중인가요? .proto를 붙여넣고, JSON 스켈레톤을 요청 본문에 복사한 뒤, 실제로 보낼 값만 채우세요.

자주 묻는 질문

제 .proto 스키마가 어딘가로 전송되나요?

아니요. 파싱은 전적으로 브라우저에서 JavaScript로 이뤄집니다. 메시지 이름, 필드 이름, package 경로 등 스키마의 어떤 것도 기기를 떠나지 않습니다. DevTools를 열고 Network 탭을 본 채로 Convert를 눌러 보세요. 요청은 0건입니다.

proto2도 proto3만큼 처리하나요?

대부분요. 파서는 required나 optional 같은 proto2 구문 토큰을 처리하지만, 출력 값은 proto3 기본값을 사용합니다(이는 proto3 JSON 매핑이 명시한 동작입니다). proto2 파일에서 [default = ...]로 명시한 기본값이 있더라도, 그 기본값은 출력에 반영되지 않습니다.

어느 메시지를 변환할지 어떻게 고르나요?

파일 안에 선언된 최상위 message 중 마지막 것을 사용합니다. 실제 스키마에서는 바깥쪽/복합 타입이 의존성 뒤에 선언되는 게 보통이라, 보통 원하는 것과 일치합니다. 잘못된 게 선택되면 원하는 메시지가 마지막이 되도록 파일을 재정렬하세요.

왜 int64 값이 출력에서 문자열인가요?

JSON은 IEEE-754 double만 가지고 있어 2^53을 넘으면 정밀도를 잃기 때문입니다. 공식 proto3 JSON 매핑은 int64, uint64, fixed64, sfixed64, sint64를 JSON 문자열로 인코딩하도록 명시합니다. 저희는 그 관례를 따릅니다.

oneof, map, repeated는 어떻게 되나요?

셋 다 동작합니다. oneof 필드는 일반 필드처럼 파싱됩니다(JSON 객체에는 하나만 고르지 않고 전부 포함됩니다 — 보통 원치 않는 걸 지웁니다). map<K, V>는 빈 {} 객체를 출력합니다. repeated는 요소 모양을 보여주는 한 개짜리 배열을 출력합니다 — 실제 데이터에 맞춰 복제하거나 지우세요.

import는 따라가나요?

아니요. import 문은 인식하지만 건너뜁니다. 파일 간 메시지 타입은 출력에서 null로 해결됩니다. 파일 간 해결이 필요하다면, 임포트된 파일에서 해당 메시지를 같은 입력에 붙여넣으세요.

얼마나 큰 스키마까지 처리할 수 있나요?

수만 줄이라도 문제없습니다. 모든 처리가 로컬이라 업로드, 레이트 리밋, 네트워크 지연이 없습니다.

Protobuf to JSON 변환기