JSON Toolkit

JSON 복구 가이드:깨진 LLM 출력 구출과 신뢰 경계

핵심 요약: markdown 펜스로 감싸이고 후행 쉼표와 Python 리터럴이 섞인 LLM 출력은 엄격한 파서가 전부 거부합니다. 복구기가 실제로 고칠 수 있는 9가지 오류와 고칠 수 없는 4가지 경계를 정리하고, 상태 머신과 정규식 두 구현 진영의 차이를 설명합니다. jsonrepair와 json-repair 이중 스택 연결 순서와 복구 결과를 스키마 검증으로 담보하는 방법까지 다룹니다.

중급약 6분 소요2026-11-08 발행2026-11-08 업데이트
JSON 복구 파이프라인 다이어그램: 펜스 제거, 따옴표 정규화, 괄호 균형 맞추기부터 최종 검증까지

엄격한 파서는 깨진 입력에 전혀 관대하지 않습니다. 오류 메시지 한 줄과 줄 번호 하나만 줄 뿐, 데이터는 단 한 바이트도 돌려주지 않습니다. 복구기가 존재하는 이유는 "완전한 실패"를 "일단 돌아가는 상태"로 바꾸는 것입니다. 다만 복구가 채워 넣은 것은 언제나 의도에 대한 최선의 추측일 뿐, 정확성의 보증이 아닙니다.

1. 깨진 JSON은 어디서 오는가: 세 가지 발생원

복구는 만능이 아니므로 먼저 입력이 무엇인지 봐야 합니다. 실무에서 비표준 JSON이 생기는 곳은 세 곳으로 집중됩니다.

  1. LLM 출력. 언어 모델은 토큰 단위로 텍스트를 생성할 뿐 JSON 직렬화기를 실행하지 않습니다. "JSON만 출력해"라고 요청해도 모델은 ```json 펜스로 감싸거나, "네, 데이터입니다"라는 말을 앞에 붙이거나, 후행 쉼표를 남기거나, 토큰 한도에 걸려 객체 한가운데서 멈춥니다.
  2. 다른 언어에서 복사한 텍스트. console.log로 찍은 JavaScript 객체는 작은따옴표와 따옴표 없는 키를 달고 나오고, Python 딕셔너리는 True/False/None으로 출력됩니다. 이런 "JSON처럼 생긴" 텍스트는 JSON.parse를 만나는 순간 폭발합니다.
  3. JSON5/JSONC 설정 파일. tsconfig 같은 파일은 주석과 후행 쉼표를 합법적으로 허용합니다. 이것을 엄격한 파서에 그대로 넘기면 마찬가지로 거부됩니다.

세 발생원마다 고치는 방법은 다르지만, 복구기는 전부 커버할 수 있습니다. 조건은 하나, 오류가 복구기가 선언한 "복구 가능 목록" 안에 있어야 한다는 것입니다.

2. 복구 가능한 9가지: 복구기의 진짜 강점

jsonrepair 라이브러리 문서와 여러 도구 업체가 공개한 능력 목록을 종합하면, 자동 복구가 가능한 오류는 9가지로 분류됩니다.

분류 깨진 입력 복구 결과
후행 쉼표 [1, 2, 3,] [1, 2, 3]
작은따옴표/곧은 따옴표 {'a': 'b'}、{"a": "b"} {"a": "b"}
따옴표 없는 키 {name: 'Ada'} {"name": "Ada"}
주석 {"a": 1 /* 설명 */} {"a": 1}
Python 리터럴 {"ok": True, "v": None} {"ok": true, "v": null}
markdown 펜스 ```json {...} ``` {...}
쉼표 누락 [1 2] [1, 2]
괄호/따옴표 미닫힘 {"a": [1, 2 {"a": [1, 2]}
JSONP/문자열 연결 cb({...})、"x" + "y" {...}、"xy"

이 9가지의 공통점은 데이터는 전부 있고 문법만 깨져 있다는 것입니다. 복구기는 구두점과 포장을 조정할 뿐 값에는 손대지 않습니다. 다음 세부 사항은 따로 기억해 둘 가치가 있습니다.

  • 앞자리 0이 붙은 숫자는 문자열로 변환됩니다: 007은 7이 아니라 "007"로 복구됩니다. 자릿수를 잃지 않기 위해서입니다. 필드가 본래 텍스트 코드라면 올바른 동작이지만, 진짜 숫자라면 직접 판단해야 합니다.
  • 맨단어는 문자열이 됩니다: NaN은 숫자로 복구되지 않으며, 구현에 따라 "NaN"이 되기도 하고 null이 되기도 합니다. 라이브러리마다 동작이 다르므로 파이프라인에 넣기 전에 한 번 시험하세요.
  • 입력이 이미 올바른 JSON이면 그대로 돌려줍니다: 복구기에는 엄격 파스의 빠른 경로가 내장되어 있어 올바른 입력은 복구 로직을 통과하지 않습니다. "고치다가 더 망가지는" 일은 없습니다.

3. 복구 불가능한 4가지: 신뢰 경계의 반대편

복구기의 능력 한계 역시 똑같이 명확합니다. 다음 네 가지는 기대하지 마세요.

  1. HTML 오류 페이지나 순수 산문. 입력 안에 JSON 구조가 아예 없으며, 어떤 도구도 데이터를 허공에서 만들어낼 수 없습니다.
  2. 문법은 맞지만 데이터가 틀린 경우. 키 철자 오류, 값이 잘못된 자리, 숫자를 문자열로 저장한 것——이것들은 의미론적 문제이고 문법 차원에서 완전히 합법이기 때문에 어떤 복구기도 그냥 통과시킵니다.
  3. 절단으로 잃어버린 데이터. 완성 기능은 {"items": [{"id": 1}, {"na를 올바른 JSON으로 고칠 수 있지만, name 필드의 값은 다시 돌아오지 않습니다. 복구 결과는 "올바르지만 불완전한" 객체입니다. 프로덕션에서는 보완할지 재시도할지 정하기 전에 반드시 stopReason === "max_tokens"를 확인하세요.
  4. 중복 키와 모호한 구조. 같은 이름의 키가 두 개일 때 어느 쪽이 이기는지는 파서 구현에 달려 있습니다. 책임 있는 복구기는 strict 모드를 제공해 조용히 하나를 고르는 대신 오류를 던집니다.

신뢰 경계를 한 문장으로 요약하면 복구는 "최선의 추측"이지 "정확성의 보증"이 아니다입니다. 검증 없이 복구 결과를 하류로 흘려보내는 것은 요란한 문법 위험을 더 숨은 데이터 위험으로 바꾸는 것과 같습니다.

4. 구현의 두 진영: URL 하나로 차이를 시험할 수 있다

시중 복구기에는 두 가지 구현 진영이 있으며, 능력 차이는 특정 입력에서 즉시 드러납니다.

정규식 치환 진영은 깨진 패턴을 전역 검색·치환합니다. 다음 입력을 보세요.

{"url": "http://example.com", 'note': 'fine'}

"작은따옴표를 큰따옴표로 바꾸는" 정규식은 URL 안까지 건드리고, "모든 //를 지우는" 주석 제거 정규식은 http://를 둘로 자릅니다. 문자열 안쪽과 구조 바깥쪽은 생김새가 똑같아서 정규식은 구분할 수 없습니다.

한 글자씩 상태 머신 진영은 파스 상태를 추적합니다. 지금 큰따옴표 문자열 안인지, 작은따옴표 문자열 안인지, 행 주석 안인지, 블록 주석 안인지, 값을 기다리는 상태인지. '를 봤을 때 먼저 "지금 문자열 안에 있는가"를 판단한 뒤 따옴표를 바꿀지 건너뛸지 결정합니다. http://example.com은 큰따옴표 문자열 안에 있으므로 상태 머신은 그 안의 //가 주석이 아니라 데이터임을 알고 그대로 보존합니다. jsonrepair와 json-healer 같은 라이브러리가 이 진영이며, 커뮤니티 해설에서 거듭 강조하는 "복구기는 찾아 바꾸기가 아니다"라는 말이 바로 이것입니다.

복구 파이프라인의 완전한 순서(devkits가 공개한 구현 흐름)도 볼 가치가 있습니다. 펜스 제거 → 곧은 따옴표 정규화 → 첫 균형 블록 추출 → 주석 제거 → 키 따옴표 부여 → 후행 쉼표 제거 → 리터럴 변환 → 마지막으로 JSON.stringify 재직렬화. 마지막 재직렬화가 핵심입니다. 앞 단계에서 무엇을 했든 출력은 파스 결과에서 다시 생성되므로, 하류의 어떤 엄격한 파서도 받아들입니다.

5. 코드에서 연결하는 법: 순서화된 파스 체인

코드에 복구를 붙일 때는 라이브러리 선택보다 순서가 더 중요합니다. json2toon과 aijsonmedic이 공개한 패턴을 따라 정리하면 순서는 이렇습니다. 절단 검사 → JSON 구간 추출 → 엄격 파스 → 복구 폴백 → 스키마 검증.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // 절단된 출력을 복구해도 데이터는 여전히 빠져 있다. 재시도한다
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // JSON 구간 추출: LLM은 앞뒤에 인사말을 붙일 수 있다
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // 올바른 입력은 빠른 경로로
  } catch {
    return JSON.parse(jsonrepair(candidate));  // 복구 폴백
  }
}

Python 쪽에서는 json-repair 패키지(스타 4,700개 이상)의 loads()가 객체를 바로 돌려줍니다.

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

실무 디테일 두 가지가 더 있습니다.

  • 스택 정합. 프런트와 백엔드 양쪽에서 복구한다면 의미가 같은 원천의 구현을 고릅니다(Python json-repair와 그 TS 포트 @yarmu/json-repair, 또는 동일한 일관성 코퍼스 485건을 양쪽 다 통과한 jsonmend). 그렇지 않으면 같은 출력이 프런트에서는 A로, 백엔드에서는 B로 복구되어 문제 추적이 더 어려워집니다.
  • 복구 로그 활성화. @yarmu/json-repair는 logging: true로 매 복구 연산의 배열을 돌려줍니다. 프로덕션 복구율이 갑자기 올라가면 보통 프롬프트나 모델 버전이 바뀐 신호입니다. 오류 보고서보다 빠른 신호입니다.

복구 뒤에 생략할 수 없는 단계가 하나 더 있습니다. 스키마 검증입니다. 문법을 고쳤다고 데이터가 쓸모 있다는 뜻은 아닙니다. 빠진 필드, 틀린 타입, 남는 키는 모두 스키마가 잡습니다. 계약 테스트의 사고방식이 여기에 그대로 적용됩니다. "JSON Schema 계약 테스트 하는 법"을 참고하세요.

6. 예방 체크리스트: 고칠 일 자체를 줄이는 것이 최선

복구는 어디까지나 폴백입니다. 원천에서 깨진 JSON을 줄이는 것이 본질적인 승리입니다. 우선순위 순으로 정리합니다.

  1. Structured Outputs(json_schema 모드): 디코딩 단계에서 스키마가 구속하기 때문에 후행 쉼표는 애초에 생성되지 않습니다. OpenAI strict 모드의 실패율은 약 0.1%이지만 additionalProperties: false 같은 강한 요구가 대가입니다.
  2. JSON 모드(json_object): 문법의 올바름만 보장하고 모양은 보장하지 않습니다. 토큰 한도로 인한 절단도 여전히 발생합니다.
  3. 명시적 지시: JSON 모드가 없는 엔드포인트에서는 "펜스 금지·주석 금지·후행 쉼표 금지·객체만 출력"이라고 명시하는 것만으로 오류율을 70~80% 줄일 수 있습니다.
  4. temperature 낮추고 토큰 한도 올리기: 전자는 산문으로 흘러갈 확률을 줄이고 후자는 절단을 줄입니다.
  5. 오류를 붙여 재시도: 검증이 실패하면 깨진 출력과 "JSON path + 오류 메시지"를 대화에 덧붙여 다시 요청합니다. 모델은 정확한 오류만 있으면 대개 스스로 고칩니다.

실무에서는 "structured outputs + 복구 폴백 + 스키마 검증" 세 층을 겹쳐 쓰면 복구로도 처리 못 하는 시나리오는 거의 없습니다.

7. 온라인 도구의 역할 분담: 방언 변환은 복구가 아니다

이 사이트의 도구 상자에는 이 파이프라인에 대응하는 두 지점이 있고, 각자 맡는 구간이 다릅니다.

  • **방언류 문제(주석, 작은따옴표, 후행 쉼표)**는 JSON5 변환에 바로 넘깁니다. JSON5와 표준 JSON의 상호 변환은 정확히 이 세 가지를 커버하며 변환 의미가 명확하고 추측이 없습니다. 입력 전체가 JSONC/JSON5 파일이라면 "복구"보다 변환이 더 예측 가능합니다. 방언 자체의 선택은 "JSON5와 JSONC 가이드"를 참고하세요.
  • 복구 후에는 JSON 파서 도구로 검증·정형하고, 오류를 행과 열로 특정해 복구 결과가 정말로 엄격한 파서에게 받아들여지는지 확인합니다.
  • **라이브러리류 문제(Python 리터럴, 절단 완성, JSONP 포장, markdown 펜스)**는 현재로선 코드 쪽 jsonrepair / json-repair에 의존해야 합니다. 브라우저 쪽에는 동등한 원클릭 복구가 없습니다. 이 두 종류의 복구는 "의도 추론"을 수반하므로 범용 변환 도구에 넣는 것보다 로컬 라이브러리가 더 안전합니다.

손에 든 것이 깨진 데이터가 아니라 오류 메시지라면, 먼저 "JSON 파스 오류 고치기"에서 오류를 좌표로 번역한 뒤 손으로 고칠지 복구할지 판단하세요.

자주 묻는 질문

JSON 복구가 데이터를 망가뜨리지 않나요?

복구 가능한 9가지는 구두점과 포장만 고치고 값은 건드리지 않습니다. 문자열 안의 //, 쉼표, 중괄호는 상태 머신이 식별해 그대로 보존합니다. 다만 절단 완성으로 얻은 객체는 데이터가 빠져 있고, 앞자리 0 숫자는 문자열이 되며, NaN 처리는 라이브러리마다 다릅니다. 복구 후 핵심 필드 확인은 필수 작업입니다.

복구와 검증은 어떤 관계인가요?

검증은 "어디가 불법인지"만 알려주고, 복구는 "합법적인 문서"를 직접 줍니다. 믿을 수 있는 방법은 둘 다 하는 것입니다. 먼저 복구하고 다음에 검증합니다. 스키마 검증으로 타입과 필수 필드를 잡고, 문법 검증으로 파서가 받아들이는지 확인합니다. 검증 없이 복구만 하는 것은 요란한 문법 오류를 더 숨은 데이터 오류로 바꾸는 것과 같습니다.

LLM 출력이 늘 ```json 펜스로 감싸이는데 어떻게 하나요?

단기적으로는 추출로 대응합니다. 첫 { 또는 [부터 마지막 } 또는 ]까지의 내용을 잘라 파스합니다. 펜스 제거를 지원하는 복구기라면 출력 전체를 그대로 처리할 수도 있습니다. 장기적으로는 structured outputs나 "markdown 펜스 금지" 명시 지시에 맡겨 생성 단계부터 펜스를 만들지 않는 것입니다.

jsonrepair와 json-repair 중 무엇을 고를까요?

JavaScript 스택은 npm의 jsonrepair(스트리밍 transform 지원), Python 스택은 PyPI의 json-repair를 씁니다. 양쪽에서 복구한다면 의미가 같은 원천 조합, 예컨대 json-repair와 그 TS 포트를 골라 같은 입력에 대해 양쪽 복구 결과가 일치함을 보장합니다.

복구기가 한국어와 곧은 따옴표를 처리할 수 있나요?

가능합니다. 한글 입력기가 만든 타이포그래픽 따옴표(" ")와 전각 공백, 파일 머리의 BOM은 모두 흔한 복구 목록에 들어 있고, 곧은 따옴표는 일반 따옴표로 정규화됩니다. 복구 후 검증기를 한 번 돌리면 확인됩니다.