YAML to JSON: 언제 변환하고, 어떻게 작동하며, 무엇이 사라지는가

몇 년 전 저는 팀의 CI/CD 파이프라인을 한 플랫폼에서 다른 플랫폼으로 마이그레이션하는 것을 돕고 있었습니다. 이전 시스템은 파이프라인 정의에 JSON을 사용했습니다. 새 시스템은 YAML을 사용했습니다. 이론적으로는 큰 문제가 아니었습니다. 두 형식 모두 동일한 계층적 데이터를 표현하니까요.

실제로는 중괄호를 들여쓰기로, 키에서 따옴표를 제거하고, JSON의 null이 파서에 따라 YAML의 ~가 되는지 그냥 null이 되는지를 기억하면서 수작업으로 포맷을 변환하는 데 창피할 만큼 많은 시간을 보냈습니다. 지루하고 오류가 발생하기 쉬운 작업이었습니다. 결국 누군가 변환 도구를 알려줬고, 처음부터 사용하지 않은 자신이 정말 어리석게 느껴졌습니다.

그 경험은 꽤 흔합니다. YAML과 JSON은 현대 개발 어디에나 있습니다. CI 설정, Docker Compose, Kubernetes 매니페스트, API 응답, 패키지 메타데이터. 둘이 충분히 겹치기 때문에 결국 데이터를 두 형식 사이에서 이동해야 할 일이 생깁니다. 각 형식이 실제로 무엇인지, 언제 어떤 것을 사용하는지, 변환할 때 어떤 일이 발생하는지 이해하면 전체 과정이 훨씬 덜 고통스럽습니다.

YAML과 JSON이 실제로 무엇인가

YAML도 JSON도 프로그래밍 언어가 아닙니다. 데이터 직렬화 형식입니다. 구조화된 데이터를 텍스트로 표현해 서로 다른 시스템이 읽고 쓸 수 있게 하는 방법입니다.

JSON(JavaScript Object Notation)은 2000년대 초 웹 클라이언트와 서버 사이에서 데이터를 전송하기 위한 XML의 가벼운 대안으로 설계됐습니다. 엄격하고, 최소화되어 있으며, 명시적입니다. 모든 문자열은 따옴표로 감싸고, 모든 객체는 중괄호로, 모든 배열은 대괄호로 감쌉니다. 정확히 여섯 가지 값 유형(문자열, 숫자, 객체, 배열, 불리언, null)이 있습니다. JSON에는 주석, 이스케이프 없는 다중 행 문자열, 앞서 정의한 값을 참조하는 방법이 없습니다. 표현력이 부족한 대신 단순함으로 보완합니다. 세계의 거의 모든 언어가 서드파티 라이브러리 없이 JSON을 파싱할 수 있습니다.

YAML(YAML Ain't Markup Language — 네, 재귀적)은 조금 나중에 나왔으며 명시적으로 사람 가독성을 위해 설계됐습니다. 들여쓰기로 중첩을 표현하고, 대부분의 경우 따옴표 없는 문자열을 허용하며, #으로 주석을 지원하고, 한 번 정의한 값을 여러 번 참조할 수 있는 앵커와 별칭이 있습니다. JSON보다 훨씬 풍부한 타입 시스템도 있습니다. 타임스탬프, 이진 데이터, 집합, 순서 있는 맵. 그리고 YAML 1.2는 자신을 JSON의 상위 집합으로 정의하므로 유효한 JSON 문서는 유효한 YAML이기도 합니다.

실제로 JSON은 API와 통신하고 신뢰할 수 있는 기계 간 통신이 필요할 때 사용하는 형식입니다. YAML은 사람이 설정을 작성하고 유지할 때 사용하는 형식입니다. 들여쓰기가 괄호보다 더 빠르게 스캔되고, 설정 파일에서 주석이 매우 유용하기 때문입니다.

실제로 변환이 필요한 경우

필요한 경우가 생각보다 자주 발생합니다.

CI/CD 플랫폼 마이그레이션. 플랫폼마다 선호하는 형식이 다릅니다. GitHub Actions는 YAML을 사용합니다. 일부 오래된 Jenkins 설정은 JSON이나 XML을 사용합니다. 플랫폼 사이를 이동한다면 파이프라인 정의를 변환해야 합니다.

Kubernetes와 REST API. kubectl은 YAML을 받습니다. Kubernetes API 자체는 JSON으로 작동합니다. API에 직접 스크립팅한다면(curl 등으로) JSON이 필요합니다. 사람이 읽고 git에 커밋하는 매니페스트를 작성한다면 YAML이 필요합니다. 두 형식 사이의 변환이 일상적입니다.

설정 파일을 애플리케이션 기본값으로. 많은 애플리케이션이 기본 설정을 JSON으로 제공하지만(기계가 생성하기 때문에) YAML로 문서화합니다(사람이 문서를 읽기 때문에). 문서에서 프로그래밍 방식 설정 파일로 설정을 복사한다면 변환이 필요합니다.

다른 사람의 설정 읽기. 때로는 JSON을 기대하는 라이브러리에 전달해야 하는 YAML 파일을 물려받거나, 그 반대 상황이 생깁니다. 변환 자체가 전체 작업입니다.

API 응답 디버깅. API는 JSON을 반환합니다. 응답을 검사하고, 편집하고, 다시 실행하고 싶을 수 있습니다. YAML에서 하는 것이 읽기 더 쉬운 경우가 있습니다. 변환해서 편집하고, 다시 변환합니다.

YAML-to-JSON 변환기가 실제로 하는 일

내부적으로 변환은 두 단계입니다. YAML을 메모리 내 데이터 구조로 파싱하고, 그 구조를 JSON으로 직렬화합니다.

파싱 단계가 흥미롭고(때로는 짜증나는) 작업이 이루어지는 곳입니다.

YAML 앵커와 별칭이 해석됩니다. YAML은 &anchor로 값을 정의하고 *alias로 다른 곳에서 참조할 수 있게 합니다. 이것은 데이터베이스 설정을 한 번 정의하고 환경 전체에서 재사용하고 싶은 설정 파일에서 매우 유용합니다. JSON으로 변환하면 앵커가 사라지고 참조된 값이 사용된 모든 곳에 인라인으로 반복됩니다. 결과 JSON은 정확하지만 더 장황합니다.

타입 추론이 발생합니다. YAML은 암묵적 타이핑을 합니다. 단순한 true는 불리언이 됩니다. 42는 정수가 됩니다. 3.14는 부동소수점이 됩니다. 일부 파서에서 2026-04-21은 날짜가 됩니다. JSON에는 날짜가 없고 사양에서 정수와 부동소수점 구분도 없습니다. 그냥 "숫자"입니다. 좋은 변환기는 이 모든 것을 적절히 처리하지만 YAML 타입 시스템이 JSON보다 더 풍부하다는 것을 알아두면 좋습니다.

주석이 삭제됩니다. 이것이 가장 아프게 느껴지는 손실입니다. YAML 설정에 타임아웃이 30초로 설정된 이유나 불가사의한 플래그의 역할을 설명하는 유용한 주석이 있다면, 변환 후 그 주석들이 사라집니다. JSON에는 주석 문법이 없습니다. 이것을 피할 방법이 없습니다.

다중 행 문자열이 접힙니다. YAML에는 블록 스칼라가 있습니다. |(리터럴 블록)과 >(접힌 블록)를 사용해 다중 행 문자열을 작성하는 방법입니다. 이것들은 내부에 \n 줄바꿈이 있는 일반 JSON 문자열로 변환됩니다. 기술적으로는 맞지만 훨씬 읽기 어렵습니다.

까다로운 부분: YAML 1.1 vs 1.2 불리언 문제

이것은 충분히 많은 사람들을 괴롭혔기 때문에 별도 섹션이 필요합니다.

YAML 1.1(대부분의 파서가 수년간 사용했던)에서는 다음 값들이 모두 불리언으로 처리됩니다.

true, false, yes, no, on, off
TRUE, FALSE, YES, NO, ON, OFF
True, False, Yes, No, On, Off

이 말은 완전히 무해한 YAML 키인 enabled: yes가 JSON에서 "enabled": true가 된다는 것입니다. 그리고 country: NO — 아마도 노르웨이의 ISO 국가 코드일까요? — 는 "country": false가 됩니다.

2009년에 발표되고 2021년에 업데이트된 YAML 1.2는 불리언을 true와 false만으로 제한해 이것을 수정했습니다. 하지만 생태계가 그것들을 중심으로 구축되었기 때문에 놀랍게도 많은 YAML 파서가 여전히 1.1 규칙을 구현합니다.

안전한 규칙: 변환되거나 익숙하지 않은 도구로 파싱될 수 있는 YAML 파일에서는 불리언처럼 보이는 모든 문자열을 따옴표로 감싸세요. 문자열을 의미한다면 country: "NO"와 enabled: "yes"로 쓰세요. 이것은 추적하는 데 세 시간이 걸리고 수정하는 데 5초가 걸리는 버그를 일으키는 종류의 것입니다.

숫자 엣지 케이스도 있습니다. YAML 1.1은 선행 밑줄이 있는 숫자를 유효한 것으로 취급하지만 JSON에서는 그렇지 않습니다. 0755 같은 8진수 표기법은 YAML에서 유효하지만 JSON에서는 유효하지 않습니다. 좋은 변환기는 이것들을 처리하지만 이것도 라운드 트립이 놀랍게 만들 수 있는 영역입니다.

변환이 라운드 트립에 안전한가

짧은 답: 대부분 그렇지만 완벽하지는 않습니다.

YAML → JSON → YAML은 주석을 잃고, 앵커 정의를 잃으며(반복된 값을 대신 얻음), 원본 YAML에서 했던 형식 선택을 잃습니다. 결과 YAML은 유효하고 정확하지만 기계가 생성한 것처럼 보일 것입니다(실제로 그렇게 생성됐기 때문에).

JSON → YAML → JSON은 표준 JSON에 실제로 꽤 안전합니다. JSON은 YAML의 부분 집합이므로 라운드 트립이 모든 데이터를 보존합니다. 유일한 잠재적 이상함은 YAML 직렬라이저가 예상치 못한 타입 결정을 내리는 경우입니다. 예를 들어 숫자로 유지되어야 할 숫자를 따옴표로 감싸는 경우입니다.

실용적인 결론: 단방향 또는 동일 방향 작업에 변환을 사용하세요. YAML 설정을 JSON 표현과 함께 유지해야 한다면 하나를 진실의 원천으로 유지하고 다른 하나를 거기서 생성하세요. 변환 후 둘 다 수동으로 동기화하려고 하지 마세요.

ToolboxHubs의 YAML-to-JSON 도구 사용 방법

toolboxhubs.com의 YAML-to-JSON 변환기는 위의 모든 것을 처리합니다. 사용 방법은 다음과 같습니다.

1. YAML을 왼쪽 패널에 붙여넣습니다. 간단한 키-값 설정부터 깊게 중첩된 Kubernetes 매니페스트까지 모두 받습니다.
2. 오른쪽 패널에 JSON 출력이 즉시 나타납니다. 변환은 브라우저에서 실행됩니다. 서버로 아무것도 전송되지 않습니다.
3. 결과를 복사합니다. 복사 버튼을 누르면 완료됩니다.

도구는 앵커, 다중 행 문자열, 모든 불리언 타입, null 값, 중첩 구조를 처리합니다. 또한 입력하면서 YAML을 검증합니다. 들여쓰기 오류나 잘못된 문서가 있으면 자동으로 잘못된 출력 대신 오류 메시지가 표시됩니다.

한 가지 처리하지 않는 것: YAML 주석 보존. JSON에 주석을 넣을 방법이 없으므로 변환 시 삭제됩니다. 이것은 도구의 한계가 아니라 형식으로서의 JSON의 한계입니다.

반대 방향으로 가고 싶다면, JSON-to-YAML 변환기가 역방향 도구입니다. 동일한 원리, 반대 방향입니다.

잘 어울리는 관련 도구들

YAML 검증기 — 변환하기 전에 YAML이 실제로 유효한지 확인하면 도움이 됩니다. 붙여넣어 문법 오류를 즉시 확인하세요.

JSON 포매터 — 변환 후 JSON이 한 줄로 나올 수 있습니다. 포매터가 설정 가능한 들여쓰기로 보기 좋게 출력합니다.

JSON to YAML — 반대 방향으로 가려면 동일한 워크플로를 역으로 적용합니다.

YAML vs JSON 사용 기준 (직설적인 견해)

사람이 주요 작성자이자 독자인 경우 YAML을 사용하세요. 설정 파일, CI 파이프라인 정의, Kubernetes 매니페스트, Ansible 플레이북 — 이것들은 버전 관리에 저장되고 사람이 읽고, 검토하고, 디버그합니다. YAML의 가독성과 주석 지원이 실제로 중요합니다.

기계가 주요 생산자 또는 소비자인 경우 JSON을 사용하세요. API 응답, 데이터베이스 기록, 생성된 설정, 서비스 간 데이터 교환 — 이것들은 사람이 직접 작성하지 않기 때문에 사람 가독성에서 이점을 얻지 못합니다. JSON의 엄격함과 보편적인 지원이 중요합니다.

경계선에 있을 때 — API에서 JSON을 받지만 YAML 기반 시스템을 설정하거나 그 반대인 경우 — 변환은 워크플로의 도구일 뿐입니다. 중요한 것은 변환에서 무엇이 달라질 수 있는지 이해하고 무언가 잘못됐을 때 그것을 확인하는 것입니다.

toolboxhubs.com의 YAML-to-JSON 변환기가 기계적인 부분을 처리합니다. 무엇이 사라지는지에 대한 이해가 이 글의 목적이었습니다.

FAQ

YAML과 JSON의 주요 차이점은 무엇인가요? YAML은 들여쓰기, 주석, 유연한 타이핑을 통해 사람 가독성을 우선시합니다. JSON은 엄격한 구조와 보편적인 기계 파싱 가능성을 우선시합니다. YAML 1.2는 JSON의 상위 집합입니다. 유효한 JSON은 유효한 YAML입니다. 하지만 두 형식의 강점이 다르기 때문에 어디에 무엇을 쓸지가 결정됩니다.

YAML to JSON 변환 시 데이터가 손실되나요? 주석은 항상 손실됩니다. YAML 앵커는 해석됩니다(참조 대신 인라인으로 반복). 커스텀 YAML 태그는 명시적으로 처리되지 않으면 삭제됩니다. 일반 문자열, 숫자, 불리언, 목록, 맵이 있는 표준 설정 파일에서는 변환이 무손실입니다.

YAML 불리언 함정은 무엇인가요? YAML 1.1은 true 및 false와 함께 yes, no, on, off를 불리언으로 취급합니다. 따라서 country: NO는 JSON에서 "country": false로 변환됩니다. YAML 1.2는 불리언을 true와 false만으로 제한하지만 많은 파서가 여전히 1.1 규칙을 사용합니다. 안전을 위해 YAML에서 모호한 값을 따옴표로 감싸세요.

YAML을 JSON으로 변환하고 다시 되돌릴 수 있나요? 구조적으로는 가능하지만 주석, 앵커, 형식을 잃습니다. 데이터는 정확할 것입니다. 문서는 기계가 생성한 것처럼 보일 것입니다. 직접 유지하는 설정 파일에는 YAML을 진실의 원천으로 유지하고 JSON을 생성하세요. 변환 후 둘 다 동기화하려고 하지 마세요.

YAML은 JSON의 상위 집합인가요? YAML 1.2 사양에 따르면 그렇습니다. 실제로는 대부분의 현대 파서가 YAML에 포함된 JSON을 문제 없이 처리합니다. 엣지 케이스는 YAML 1.1 파서와 JSON이 거부하는 특정 숫자 형식에 있습니다.