FormatArc의 한국어 YAML to JSON 변환기 화면에 표시된 변환 결과FormatArc의 한국어 YAML to JSON 변환기 화면에 표시된 변환 결과
저자: FormatArc게시일: 2026-08-22갱신일: 2026-09-10

YAML JSON 변환 가이드 — 8가지 함정 피하기 (Python / yq / 브라우저)

TL;DR — 용도별 최적의 방법 10초 요약

  • 지금 바로 변환하고 싶고 설치가 필요 없을 때 → FormatArc YAML to JSON (브라우저 완결, 업로드 불필요, 줄 번호 포함 오류 표시)
  • CLI / 원라이너 → yq -o=json '.' file.yaml (DevOps의 사실상 표준)
  • Python 스크립트 및 파이프라인 → python3 -c 'import sys, yaml, json; json.dump(yaml.safe_load(sys.stdin), sys.stdout, indent=2)' < file.yaml
  • Node.js 애플리케이션 → js-yaml의 yaml.load + JSON.stringify
  • Go 서비스 → gopkg.in/yaml.v3 + encoding/json
  • Kubernetes 왕복 작업 → kubectl get ... -o json | yq -P '.' (YAML로 복원)
  • 멀티 다큐먼트 YAML (--- 구분 문서) → yq -o=json '.' file.yaml (yq는 기본 분할 처리) 또는 NDJSON 출력
방법환경 구성멀티 다큐먼트앵커주석스트리밍
FormatArc 브라우저없음첫 1개 문서만전개됨소실됨 (JSON 제약)없음
yq -o=jsonbrew install yq전체 (분할 또는 배열화)전개됨소실됨지원
Python yaml.safe_load + json.dumppip install pyyaml첫 1개(safe_load) / 전체(safe_load_all)전개됨소실됨직접 루프 작성
Node js-yaml yaml.loadnpm install js-yaml첫 1개(load) / 전체(loadAll)전개됨소실됨직접 작성
Go yaml.Unmarshalgo get gopkg.in/yaml.v3첫 1개 / 전체(Decoder 루프)전개됨소실됨지원

YAML을 JSON으로 변환하는 코드 자체는 1줄로 끝나는 경우가 많습니다. 까다로운 부분은 노르웨이 문제, 주석 소실, 멀티 다큐먼트 처리, yaml.load의 보안 위험, 정수 키의 문자열화, 앵커 전개, 1.0의 부동소수점 변환, 스키마별 타입 추론 등 8가지 함정입니다. 이 글에서는 각 함정을 before/after 예제와 함께 자세히 설명합니다.

왜 YAML을 JSON으로 변환하는가

실무에서 자주 마주치는 대표적인 상황은 다음과 같습니다.

  • Kubernetes API 호출: YAML 매니페스트를 Kubernetes API로 직접 POST 요청할 때, API 엔드포인트는 JSON으로 인코딩된 본문만 받습니다.
  • YAML 구조 디버깅: YAML의 들여쓰기 기반 중첩 구조는 시각적으로 혼동하기 쉽습니다. JSON으로 변환하면 중첩과 계층이 명확해져 - 누락이나 들여쓰기 실수를 한눈에 파악할 수 있습니다.
  • JSON 전용 도구 연동: 하류 시스템(다른 언어로 작성된 JSON 파서, JSON 필드를 저장하는 데이터베이스, JSON Schema 검증기가 달린 이벤트 버스 등)이 YAML 형식을 직접 받지 않는 경우입니다.
  • 설정 감사 및 보안 스캔: 저장소의 YAML 설정 파일을 JSON으로 변환하여 diff 분석을 수행하거나 JSON Schema 유효성 검사, 보안 스캐너 파이프라인에 입력합니다. 마크다운 기반 정적 블로그의 메타데이터 변환은 마크다운 프론트매터 YAML을 JSON으로 변환을 참고하세요.
  • LLM 컨텍스트 전달: LLM에 구조화된 설정을 전달할 때 들여쓰기 기반의 YAML보다 JSON이 객체 경계를 더 안정적으로 인식합니다. 자세한 내용은 LLM 입력 시 Markdown vs HTML 비교를 참고하세요.
  • jq로 OpenAPI/Swagger 스펙을 조회·편집할 때: jq는 JSON 전용 프로세서라 YAML을 직접 읽지 못하므로, YAML로 작성된 OpenAPI/Swagger 스펙을 jq 파이프라인으로 조회하거나 편집하려면 먼저 JSON으로 변환해야 합니다.

두 형식의 차이점과 상세 비교는 YAML과 JSON의 차이에서 자세히 다룹니다. 각 형식의 기본 개념은 YAML이란? 및 JSON이란? 글을 참고하세요.

방법 1: FormatArc 브라우저 도구 (업로드 불필요)

별도 설치 없이 빠르게 변환하고 싶다면 YAML to JSON 도구가 가장 빠릅니다. 모든 연산이 브라우저 내부에서 실행되며 데이터는 서버로 전송되지 않습니다.

  1. YAML to JSON 페이지를 엽니다.
  2. 왼쪽 에디터에 YAML 데이터를 붙여넣습니다.
  3. 변환 버튼을 누르면 오른쪽에 JSON 결과가 표시됩니다.

FormatArc YAML to JSON 변환기 화면FormatArc YAML to JSON 변환기 화면

이 도구는 변환 시 YAML 구문을 실시간으로 검증합니다. 들여쓰기 오류, 콜론 누락, 공백 자리에 탭을 쓴 경우 등 문법 오류를 줄 번호와 함께 보고하므로 YAML 디버깅 도구로도 활용할 수 있습니다. 올바른 YAML 작성 규칙과 문법 세부 사항은 YAML 문법 가이드를 참고하세요.

브라우저 내 처리는 보안이 중요한 데이터를 다룰 때 특히 안전합니다. Kubernetes Secret(base64로 인코딩되어 있어도 기밀 데이터임), Ansible vault에 저장된 클라우드 인증 정보, API 토큰이 포함된 CI 설정 등을 외부 유출 걱정 없이 다룰 수 있습니다.

이는 단순한 이론적 우려가 아닙니다. 2025년 11월 보안 기업 watchTowr의 보고에 따르면, 유명 온라인 포맷팅 사이트인 JSONFormatter와 CodeBeautify의 저장 기능 취약점으로 인해 인증 정보, 비밀 키, API 토큰을 포함한 5GB 이상의 사용자 입력 데이터가 외부에 공개된 사례가 있었습니다(watchTowr 조사 보고서). 브라우저 안에서만 완결되는 도구는 입력을 저장하거나 전송하지 않으므로 유출 위험 자체가 없습니다. 온라인 변환 도구의 안전성을 직접 확인하는 방법은 온라인 변환 사이트 보안 검증을 참고하세요.

브라우저 도구는 여러 줄 문자열(블록 스칼라 |, 폴드 스칼라 >), 앵커와 별칭(인라인 전개), 임의 깊이의 중첩 객체, 혼합 타입 배열, null·불리언·숫자 타입을 정확하게 처리합니다.

방법 2: yq (DevOps 사실상의 표준)

yq는 YAML용 jq에 해당하는 경량 커맨드라인 프로세서입니다. DevOps 파이프라인에서 YAML을 JSON으로 바꿀 때 가장 널리 쓰입니다.

# 기본 변환
yq -o=json '.' input.yaml

# stdin에서 파이프 입력
cat config.yaml | yq -o=json '.'

# 파일로 저장
yq -o=json '.' config.yaml > config.json

# 단일 행 압축(Compact) 출력
yq -o=json -I=0 '.' config.yaml

# 특정 하위 트리만 추출하여 변환
yq -o=json '.spec.template' deployment.yaml

# 필터링과 동시에 변환
yq -o=json '.items[] | select(.kind == "ConfigMap")' multi.yaml

설치 방법:

# macOS
brew install yq

# Linux (snap)
snap install yq

# Linux (바이너리 직접 다운로드)
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

# Go install
go install github.com/mikefarah/yq/v4@latest

참고: 이름이 동일한 yq 도구가 2종류 있습니다. 이 글에서 다루는 것은 Kubernetes 및 CNCF 생태계에서 널리 쓰이는 Mike Farah의 Go 버전 yq입니다. kislyuk의 Python 버전 yq는 문법 체계가 다릅니다. 2026년 현재 사실상의 표준은 Go 버전입니다.

yq로 멀티 다큐먼트 YAML 다루기

# 멀티 다큐먼트 YAML (---로 구분된 여러 문서)
yq -o=json '.' multi.yaml          # 입력 문서 1개당 JSON 1개씩 순차 출력
yq -o=json -I=0 '.' multi.yaml      # NDJSON 형식 (1행 1문서)
yq eval-all '[.]' -o=json multi.yaml  # 모든 문서를 단일 JSON 배열로 묶기

Kubernetes 매니페스트 모음을 하나의 JSON 배열로 변환할 때 가장 깔끔한 방법입니다.

방법 3: Python (가장 높은 유연성)

Python은 표준 라이브러리에 json 모듈을 내장하고 있으며, pyyaml 패키지도 대부분의 환경에서 쉽게 설치해 쓸 수 있습니다(pip install pyyaml).

Python 원라이너

python3 -c 'import sys, yaml, json; json.dump(yaml.safe_load(sys.stdin), sys.stdout, indent=2)' < input.yaml > output.json

stdin에서 YAML을 읽어 yaml.safe_load로 파싱한 뒤 읽기 쉬운 들여쓰기(indent=2)가 적용된 JSON으로 stdout에 출력합니다. 변환된 JSON을 보기 좋게 정렬하는 방법은 JSON 정렬 팁을 참고하세요.

Python 스크립트 (멀티 다큐먼트 및 오류 처리)

import sys
import yaml
import json

with open("config.yaml") as f:
    data = yaml.safe_load(f)  # 멀티 다큐먼트인 경우 safe_load_all() 사용

with open("config.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2, ensure_ascii=False)

여기서 반드시 yaml.safe_load를 사용해야 합니다. 기본 yaml.load 함수는 임의의 Python 객체 인스턴스화를 허용하므로 악성 YAML 파일로 인한 원격 코드 실행 취약점이 발생할 수 있습니다.

Python + ruamel.yaml (구조 최대한 보존)

따옴표 스타일, 키 순서, 주석 정보 등을 최대한 유지하고 싶다면 ruamel.yaml을 사용합니다(단, JSON 표준 자체에는 주석이 지원되지 않으므로 JSON 출력 시 주석은 제외됩니다).

from ruamel.yaml import YAML
import json
import sys

yaml_parser = YAML(typ="safe")
data = yaml_parser.load(open(sys.argv[1]))
json.dump(data, sys.stdout, indent=2, ensure_ascii=False)

대부분의 일반적인 용도에는 pyyaml.safe_load로 충분합니다. YAML 서식의 정밀한 왕복 보존이 필요한 경우에만 ruamel.yaml을 고려하세요.

방법 4: Node.js (js-yaml)

Node.js 환경에서는 js-yaml 패키지가 표준적으로 쓰입니다.

const fs = require("fs");
const yaml = require("js-yaml");

// 단일 문서
const doc = yaml.load(fs.readFileSync("config.yaml", "utf8"));
fs.writeFileSync("config.json", JSON.stringify(doc, null, 2));

// 멀티 다큐먼트
const docs = yaml.loadAll(fs.readFileSync("multi.yaml", "utf8"));
fs.writeFileSync("multi.json", JSON.stringify(docs, null, 2));

설치: npm install js-yaml 또는 yarn add js-yaml.

외부 사용자가 입력한 신뢰할 수 없는 YAML을 파싱할 때는 yaml.load(text, { schema: yaml.JSON_SCHEMA }) 옵션을 주어 JSON 호환 타입만 허용하도록 제한하는 것이 안전합니다. 기본 DEFAULT_SCHEMA에는 노르웨이 문제와 같은 YAML 1.1 특유의 동작이 포함되어 있습니다.

방법 5: Go (gopkg.in/yaml.v3)

package main

import (
    "encoding/json"
    "fmt"
    "os"

    "gopkg.in/yaml.v3"
)

func main() {
    data, _ := os.ReadFile("config.yaml")
    var obj interface{}
    yaml.Unmarshal(data, &obj)
    result, _ := json.MarshalIndent(obj, "", "  ")
    fmt.Println(string(result))
}

yaml.v3는 go-yaml 팀이 관리하며 Kubernetes 내부에서도 쓰이는 공식 라이브러리입니다. 주의할 점은 YAML의 정수 키(123: foo)가 JSON으로 변환될 때 문자열("123": "foo")로 캐스팅된다는 것입니다(JSON 객체의 키는 문자열만 허용되기 때문입니다).

대용량 멀티 다큐먼트 YAML을 스트리밍 처리하려면 yaml.NewDecoder 루프를 사용합니다:

dec := yaml.NewDecoder(file)
for {
    var doc interface{}
    if err := dec.Decode(&doc); err != nil {
        if err == io.EOF { break }
        log.Fatal(err)
    }
    out, _ := json.Marshal(doc)
    fmt.Println(string(out))   // NDJSON: 1문서 1행
}

메모리 사용량을 일정하게 유지하면서 임의 크기의 대용량 YAML 파일을 처리할 수 있습니다.

YAML 변환 시 주의할 8가지 함정

YAML과 JSON은 데이터 모델이 완전히 1:1로 일치하지 않습니다. 실무에서 가장 자주 겪는 8가지 문제를 정리합니다.

함정 1: 노르웨이 문제 (Norway problem: NO → false)

YAML 1.1 사양은 따옴표 없는 특정 문자열을 불리언 값으로 해석합니다.

country: NO

변환 결과:

{ "country": false }

NO, no, Off, OFF, n, N, False, f, F는 모두 false로 파싱됩니다. 반대로 YES, Y, On, True, T, t는 모두 true가 됩니다. 국가 코드 목록에 노르웨이 코드인 country: NO를 적었을 때 불리언으로 자동 변환되는 현상 때문에 "노르웨이 문제"로 널리 알려져 있습니다.

해결 방법: 혼동될 여지가 있는 문자열은 반드시 따옴표로 감쌉니다.

country: "NO"

YAML 1.2(Core 스키마)에서는 이 규칙이 제거되었지만, PyYAML의 safe_load나 구버전 yq를 비롯한 많은 도구가 여전히 YAML 1.1을 기본 동작으로 유지하고 있습니다. 2글자 국가 코드, 1.0과 같은 버전 문자열, 사용자 입력값은 항상 따옴표를 사용하는 습관이 안전합니다.

함정 2: 주석은 조용히 사라짐

YAML은 # 기호로 주석을 작성할 수 있지만 JSON은 사양상 주석을 지원하지 않습니다. 따라서 YAML의 주석은 변환 과정에서 완전히 버려집니다.

# 운영 DB 접속 정보 (수정 금지)
host: db.prod.internal
port: 5432  # PostgreSQL 표준 포트

변환 결과:

{ "host": "db.prod.internal", "port": 5432 }

어떤 변환기를 쓰더라도 표준 JSON 안에 YAML 주석을 그대로 남길 수는 없습니다. 주석 내용이 중요한 메타데이터라면 ruamel.yaml 같은 도구로 주석을 별도 추출하거나 별도 문서로 관리해야 합니다.

함정 3: 멀티 다큐먼트 YAML — 기본적으로 첫 번째 문서만 변환됨

YAML은 --- 구분자를 사용해 1개 파일 안에 여러 문서를 담을 수 있습니다.

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: v1
kind: Service
metadata:
  name: app-service

기본 변환 동작:

  • yaml.safe_load (Python): 경고 없이 첫 번째 문서만 반환
  • yaml.load (js-yaml): 동일하게 첫 번째 문서만 반환
  • yq -o=json '.': 여러 JSON 문서를 연속 출력(컴팩트 모드에서는 유효한 NDJSON)

모든 문서를 단일 JSON 배열로 받으려면 명시적인 옵션이 필요합니다:

yq eval-all '[.]' -o=json multi.yaml

Python:

import yaml, json
docs = list(yaml.safe_load_all(open("multi.yaml")))
json.dump(docs, open("multi.json", "w"), indent=2)

Node.js:

const docs = yaml.loadAll(fs.readFileSync("multi.yaml", "utf8"));
fs.writeFileSync("multi.json", JSON.stringify(docs, null, 2));

Kubernetes 매니페스트 파일은 대부분 멀티 다큐먼트 구조이므로 반드시 이 차이를 인지하고 처리해야 합니다.

함정 4: yaml.load는 위험, 반드시 safe_load 사용

Python PyYAML 라이브러리의 기본 yaml.load 함수는 임의의 Python 객체 생성을 허용합니다.

!!python/object/apply:os.system ["rm -rf /"]

악의적으로 작성된 YAML 파일을 yaml.load로 읽으면 시스템 명령어가 실행될 위험이 있습니다. 신뢰할 수 없는 입력을 다룰 때는 반드시 yaml.safe_load(멀티 다큐먼트는 yaml.safe_load_all)를 사용하세요.

Node.js의 js-yaml은 구버전의 safeLoad 대신 yaml.load를 기본 안전 함수로 전환했고 위험한 기능은 unsafeLoad로 분리했습니다. Python과 Node.js 간 함수 명명 규칙이 반대이므로 주의가 필요합니다.

yq는 Go의 yaml.v3를 사용하며 Python의 !!python/object에 대응하는 기능이 없으므로 안전합니다.

함정 5: 정수 키가 문자열로 변환됨

YAML은 정수형 키를 허용합니다.

123: first
456: second

JSON 객체의 키는 오직 문자열이어야 하므로 변환 시 자동으로 문자열 캐스팅이 일어납니다.

{ "123": "first", "456": "second" }

일반적으로는 문제가 없지만 하류 애플리케이션 코드가 정수 키로 직접 조회(obj[123])하도록 작성되어 있다면 문자열 키(obj["123"])와 일치하지 않아 조회가 실패할 수 있습니다. 애플리케이션 계층에서 정수 변환을 확인해야 합니다.

함정 6: 앵커와 별칭(Anchor & Alias)은 인라인으로 전개됨

YAML은 &anchor로 값을 정의하고 *alias로 이를 참조할 수 있습니다.

defaults: &defaults
  timeout: 30
  retries: 3

production:
  <<: *defaults
  host: prod.internal

staging:
  <<: *defaults
  host: stage.internal

JSON으로 변환하면 앵커가 인라인으로 전개되어 production과 staging 객체 모두에 기본값이 완전히 복사됩니다.

{
  "defaults": { "timeout": 30, "retries": 3 },
  "production": { "timeout": 30, "retries": 3, "host": "prod.internal" },
  "staging": { "timeout": 30, "retries": 3, "host": "stage.internal" }
}

데이터 자체는 온전하지만 "기본 설정을 공유한다"는 본래의 설계 의도는 사라집니다. JSON에는 앵커 개념이 없기 때문에 이를 다시 YAML로 변환하더라도 원래 앵커 구조는 복원되지 않습니다.

함정 7: 1.0이 부동소수점이 됨 (버전 문자열 깨짐)

YAML은 숫자로 보이는 값을 자동으로 숫자형으로 파싱합니다.

version: 1.0
release: 2026

변환 결과:

{ "version": 1.0, "release": 2026 }

버전 표기용 문자열 "1.0"을 의도했더라도 부동소수점 1.0으로 변환되어 JSON 인코더에 따라 1 또는 1.0으로 출력됩니다. if version == "1.0"과 같은 문자열 비교 로직은 실패합니다.

해결 방법: 버전 번호는 따옴표로 묶어 문자열임을 명시합니다.

version: "1.0"
release: "2026"

전화번호, 우편번호("01234"의 맨 앞자리 0 소실 방지), 16진수처럼 보이는 커밋 해시("e10"이 1e+10 지수 표기로 오인되는 문제) 등에도 동일하게 적용됩니다.

함정 8: 타입 추론 동작은 스키마에 따라 달라짐

YAML 사양에는 3가지 표준 타입 추론 스키마가 있습니다.

  • FailSafe 스키마: 문자열, 시퀀스, 매핑만 다룹니다. 숫자나 불리언 파싱을 일절 수행하지 않는 가장 엄격하고 안전한 모드입니다.
  • JSON 스키마: JSON의 기본 타입(문자열, 숫자, 불리언, null, 배열, 객체)과 정확히 일치합니다. 노르웨이 문제가 발생하지 않으며 yes/no도 불리언으로 파싱되지 않습니다.
  • Core 스키마 (YAML 1.2 기본값): JSON 스키마를 확장하여 null, Null, NULL, ~, 빈 값을 null로 인정하고 true/false/True/False/TRUE/FALSE를 불리언으로 처리합니다.

대부분의 최신 도구는 Core 스키마를 기본값으로 채택하고 있습니다.

Python에서 JSON 스키마 강제 지정:

yaml.safe_load(text, Loader=yaml.SafeLoader)  # 기본 안전 모드

Node.js js-yaml에서 지정:

yaml.load(text, { schema: yaml.JSON_SCHEMA });

yq v4는 YAML 1.2 Core 스키마를 기본으로 사용하므로 노르웨이 문제가 발생하지 않습니다.

온라인 도구 비교

2026년 기준 주요 온라인 YAML to JSON 변환기의 특성 비교입니다.

도구브라우저 내 처리파일 업로드멀티 다큐먼트줄 번호 오류 표시광고 없음
FormatArc YAML to JSON지원없음 (붙여넣기 전용)첫 1개 문서지원광고 없음
onlineyamltools.com지원 (주장)있음첫 1개 문서제한적광고 없음
jsonformatter.org지원 (주장)있음첫 1개 문서미지원광고 있음
codebeautify.org지원 (주장)있음첫 1개 문서미지원광고 있음
jsonlint.com지원없음첫 1개 문서지원광고 없음
dadroit.com지원있음첫 1개 문서제한적광고 없음

기밀성이 중요한 YAML(Kubernetes Secret, Ansible vault, API 토큰 포함 CI 설정)을 다룰 때는 브라우저 내 처리 여부가 결정적입니다. 개발자 도구의 네트워크 탭에서 오프라인 모드로 설정한 뒤 변환을 실행해 보면 실제 브라우저 내 처리 여부를 쉽게 검증할 수 있습니다. FormatArc는 네트워크 연결이 끊긴 상태에서도 정상 동작합니다.

멀티 다큐먼트 YAML의 경우 위 온라인 도구들은 모두 첫 번째 문서만 변환합니다. 멀티 다큐먼트 전체 변환이나 NDJSON 출력이 필요하다면 yq나 Python을 사용하세요.

YAML에서 JSON Lines (NDJSON) 스트리밍 처리

입력이 멀티 다큐먼트 YAML이고 출력을 스트리밍 파이프라인(Kafka 프로듀서, 행 단위 DB 로더, 로그 수집기)으로 넘겨야 한다면 JSON Lines(NDJSON) 포맷이 적합합니다.

yq를 사용하는 경우

# NDJSON: 각 YAML 문서를 1행의 JSON으로 출력
yq -o=json -I=0 '.' multi.yaml

# 필터링 후 NDJSON 출력
yq -o=json -I=0 '.items[]' kubernetes-list.yaml

Python 스트리밍을 사용하는 경우

import yaml
import json
import sys

for doc in yaml.safe_load_all(sys.stdin):
    sys.stdout.write(json.dumps(doc, ensure_ascii=False) + "\n")

실행: python3 yaml2ndjson.py < multi.yaml > multi.ndjson.

입력 파일 크기에 관계없이 일정한 메모리(O(1))로 동작하므로 수천 개의 문서가 포함된 대용량 YAML 로그 파일도 안전하게 처리할 수 있습니다.

Kafka / BigQuery / S3로 파이프 연결

# BigQuery로 스트리밍 로드
yq -o=json -I=0 '.' events.yaml | bq load --source_format=NEWLINE_DELIMITED_JSON dataset.events -

# AWS S3로 스트리밍 업로드
yq -o=json -I=0 '.' events.yaml | aws s3 cp - s3://bucket/events.ndjson

# kafkacat을 통해 Kafka 토픽으로 전송
yq -o=json -I=0 '.' events.yaml | kafkacat -P -b broker:9092 -t events

CI/CD 자동화

주요 CI/CD 파이프라인 플랫폼에서 YAML을 JSON으로 변환하는 구성 예시입니다.

GitHub Actions

name: Convert YAML config to JSON
on: [push, pull_request]

jobs:
  convert:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install yq
        run: |
          sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
          sudo chmod +x /usr/local/bin/yq
      - name: Convert
        run: yq -o=json '.' config.yaml > config.json
      - name: Validate against JSON Schema
        run: |
          npx ajv-cli validate -s schema.json -d config.json

Node.js 환경이 구성된 파이프라인이라면 formatarc npm 패키지를 활용할 수도 있습니다. npx formatarc yaml-to-json config.yaml 명령으로 웹 버전과 동일한 변환 엔진을 로컬에서 실행할 수 있어 추가 바이너리 설치가 필요 없습니다.

GitLab CI

convert-yaml:
  image: mikefarah/yq:latest
  stage: validate
  script:
    - yq -o=json '.' config.yaml > config.json
    - jq empty config.json   # 최종 구문 유효성 검사
  artifacts:
    paths:
      - config.json

Jenkins (Declarative Pipeline)

pipeline {
  agent any
  stages {
    stage('Convert YAML to JSON') {
      steps {
        sh 'yq -o=json . config.yaml > config.json'
        sh 'jq empty config.json'
      }
    }
  }
}

어떤 플랫폼이든 변환은 명령어 1개로 끝나므로 파이프라인 중간에 그대로 끼워 넣을 수 있습니다.

Kubernetes 실무 워크플로

실제 운영 환경에서 자주 쓰이는 패턴입니다. 동작 중인 Deployment 리소스를 가져와 편집하고 YAML과 JSON을 오가며 반영합니다.

# 현재 Deployment를 JSON으로 조회 (kubectl은 두 형식 모두 지원)
kubectl get deployment web-app -o json > deployment.json

# 또는 YAML로 조회한 뒤 변환 (로컬 yq 도구 동작 검증 겸용)
kubectl get deployment web-app -o yaml | yq -o=json '.' > deployment.json

# jq로 내용 수정 (예: 레플리카 수 조정)
jq '.spec.replicas = 5' deployment.json > updated.json

# Git 커밋을 위해 다시 YAML로 복원
yq -P '.' updated.json > deployment.yaml

# 클러스터에 반영
kubectl apply -f deployment.yaml

단일 파이프라인으로 연결:

kubectl get deployment web-app -o json \
  | jq '.spec.replicas = 5' \
  | yq -P '.' \
  > deployment.yaml

이 방식은 kubectl의 모든 리소스, Helm 차트 values 파일, 커스텀 리소스 정의(CRD)에 동일하게 적용됩니다.

자주 묻는 질문

YAML의 country: NO가 false가 되는 이유는?

이는 YAML 1.1의 대표적인 "노르웨이 문제"입니다. YAML 1.1 사양은 NO, Off, n, False 같은 문자열을 불리언 false로 자동 파싱합니다. 해결하려면 country: "NO"처럼 따옴표로 감싸야 합니다. YAML 1.2 사양에서는 이 동작이 삭제되었으나 많은 도구가 여전히 1.1을 기본 동작으로 유지하고 있습니다. yq v4는 YAML 1.2 Core 스키마를 사용하므로 이 문제가 발생하지 않습니다.

YAML의 주석을 JSON 출력에 유지할 수 있나요?

유지할 수 없습니다. 표준 JSON 사양에는 주석 문법이 정의되어 있지 않습니다. 주석이 꼭 필요하다면 ruamel.yaml로 주석 메타데이터를 별도 추출하거나 YAML 원본 파일을 소스 오브 트루스(Source of Truth)로 보관해야 합니다. JSON 환경에서 주석을 다루는 대안은 JSON 주석처리 방법을 참고하세요.

멀티 다큐먼트 YAML — 변환 시 어떻게 되나요?

대부분의 도구는 기본적으로 첫 번째 문서만 변환하고 나머지는 무시합니다. 모든 문서를 변환하려면 Python의 yaml.safe_load_all, Node.js의 yaml.loadAll, 또는 yq eval-all '[.]'을 사용하여 JSON 배열로 감싸야 합니다. 1행 1문서 스트리밍이 목적이라면 yq -o=json -I=0으로 NDJSON을 출력하세요.

YAML을 JSON Lines(NDJSON)로 출력하려면?

yq -o=json -I=0 '.' multi.yaml 명령을 사용하면 압축된 1행 1문서 형태로 출력됩니다. Python에서는 yaml.safe_load_all로 읽어 한 행씩 json.dumps()로 출력합니다. NDJSON은 BigQuery, S3, Kafka 등 대용량 데이터 파이프라인의 표준 규격입니다.

YAML을 JSON5(주석 허용 확장)로 변환할 수 있나요?

JSON5는 주석을 허용하는 JSON의 확장 규격입니다. YAML을 JSON5로 변환하려면 표준 JSON으로 먼저 변환한 뒤 수동으로 주석을 복원하거나 전용 파서를 사용해야 합니다. json5.org의 참조 구현체가 JSON5 파싱과 출력을 지원하지만, 주요 YAML 라이브러리 중 JSON5를 직접 출력하는 라이브러리는 없습니다.

앵커와 머지 키는 JSON에서 유지되나요?

유지되지 않습니다. JSON에는 앵커나 별칭 개념이 없으므로 변환 시 해당 위치에 데이터가 인라인으로 완전 복사되어 전개됩니다. 데이터의 내용은 유지되지만 기본 설정을 공유한다는 원본의 구조적 의도는 사라집니다.

yq나 Python 없이 YAML을 JSON으로 변환하려면?

FormatArc YAML to JSON 브라우저 도구를 사용하세요. 별도 설치 없이 브라우저 안에서 즉시 변환됩니다. 또한 거의 모든 현대 운영체제에는 Python 3가 기본 내장되어 있으므로 터미널에서 Python 원라이너를 실행할 수도 있습니다.

swagger: 2.0 같은 버전 번호를 JSON으로 변환하면 깨지나요?

그럴 수 있습니다. swagger: 2.0이나 info.version: 1.0처럼 두 자리 버전 번호를 따옴표 없이 쓰면, 변환된 JSON에서는 문자열이 아니라 부동소수점 2.0으로 출력됩니다. OpenAPI 명세는 openapi와 info.version을 모두 string으로 정의하므로 (OAS 3.1.0), 숫자가 되는 순간 명세에 어긋납니다. 함정 7과 같은 문제이며, swagger: "2.0"처럼 따옴표로 감싸면 해결됩니다.

역방향 변환 (JSON to YAML)

JSON을 YAML로 다시 변환하고 싶다면 FormatArc의 JSON to YAML 변환기를 사용할 수 있습니다. 동일하게 브라우저 내에서 안전하게 동작합니다. 언어별 스크립트와 CLI를 활용한 역방향 변환 방법은 JSON YAML 변환 가이드를 참고하세요.

관련 글

정리

YAML에서 JSON으로의 변환은 용도에 맞게 5가지 방법으로 해결할 수 있습니다.

  • 설치 불필요 및 기밀 데이터: FormatArc YAML to JSON — 브라우저 완결, 줄 번호 오류 검증
  • CLI 및 DevOps 파이프라인: yq -o=json '.' — 사실상의 표준
  • Python 애플리케이션: yaml.safe_load (보안을 위해 yaml.load는 금지) + json.dump
  • Node.js 애플리케이션: js-yaml (yaml.load, 보안을 위해 JSON 스키마 지정)
  • Go 서비스: gopkg.in/yaml.v3 + encoding/json, 멀티 다큐먼트는 Decoder 루프

변환 시 노르웨이 문제, 주석 소실, 멀티 다큐먼트 처리, yaml.load 보안 위험, 정수 키 문자열화, 앵커 전개, 1.0 부동소수점 변환, 스키마별 타입 추론 등 8가지 함정에 주의하세요. 모호한 문자열은 따옴표로 감싸고, 안전한 파서 함수를 사용하며, 멀티 다큐먼트를 명시적으로 다루는 세 가지 원칙만 지키면 안전하게 변환할 수 있습니다.