JSON to YAML 변환 배열·들여쓰기 규칙

2026년 7월 18일

JSON 입력창에 예시 데이터를 넣자 오른쪽에 중첩 객체는 들여쓰기 계층으로, 배열은 대시 목록으로 변환된 YAML 결과가 표시된 화면

JSON 데이터를 쿠버네티스 매니페스트나 도커 컴포즈 파일에 넣으려면 YAML 형식으로 다시 써야 합니다. 이때 배열과 중첩 객체가 실제로 어떤 모양으로 바뀌는지, 들여쓰기 칸 수 선택이 결과에 무슨 영향을 주는지를 모르면 변환된 결과를 눈으로 검증할 수 없습니다. 이 글은 그 변환 규칙 자체와 결과를 읽는 법을 정리합니다.

요약 ① JSON의 배열은 YAML에서 대시(-)로 시작하는 목록이 되고, 중첩 객체는 들여쓰기 계층이 됩니다. ② 들여쓰기 2칸·4칸은 보기 좋게 하는 설정일 뿐 데이터 구조 자체는 바뀌지 않습니다. ③ 숫자처럼 보이는 문자열은 따옴표로 감싸야 값이 보존되며, 따옴표를 임의로 지우면 값이 달라질 수 있습니다.

왜 JSON을 YAML로 바꿔야 하나

쿠버네티스 매니페스트와 도커 컴포즈 파일은 YAML 형식을 씁니다. 반면 API 응답이나 데이터베이스에서 꺼낸 설정값은 JSON으로 되어 있는 경우가 많습니다. 두 형식을 맞추려면 JSON을 YAML 문법으로 다시 써야 합니다.

문제는 두 형식의 구조 표현 방식이 다르다는 점입니다. JSON은 중괄호·대괄호·쉼표로 구조를 나타내지만, YAML은 들여쓰기와 대시로 구조를 나타냅니다.

중괄호만 지운다고 YAML이 되지 않습니다. 배열이었던 부분은 대시 목록으로, 중첩 객체였던 부분은 들여쓰기 단계로 각각 형태를 바꿔야 합니다.

설정 항목이 몇 줄이면 손으로 다시 써도 되지만, 항목이 많아질수록 어느 계층에 몇 칸을 들여써야 하는지 헷갈리기 쉽습니다. YAML은 들여쓰기 자체가 문법이라, 한 칸만 어긋나도 다른 계층으로 읽힙니다.

도구 없이 직접 변환하는 방법

변환 규칙은 세 가지로 정리됩니다. 아래 JSON에 하나씩 적용해 보겠습니다.

{
  "name": "myapp",
  "port": 8080,
  "tags": ["web", "prod"],
  "database": { "host": "localhost", "port": 5432 }
}

규칙 1 — key와 value는 콜론과 공백으로 잇습니다. "name": "myapp"은 name: myapp이 됩니다. 문자열 값을 감싸던 큰따옴표는 대부분 생략할 수 있습니다.

규칙 2 — 중첩된 객체는 새 줄에서 한 단계 들여씁니다. "database": { "host": "localhost", "port": 5432 }는 아래처럼 바뀝니다.

database:
  host: localhost
  port: 5432

키 이름 뒤에 콜론만 남기고 새 줄로 내려가, 안에 있던 키들을 한 단계 들여써서 나열합니다. 중괄호는 사라집니다.

규칙 3 — 배열은 각 항목 앞에 대시(-)를 붙여 한 줄씩 나열합니다. "tags": ["web", "prod"]는 아래처럼 바뀝니다.

tags:
  - web
  - prod

대괄호와 쉼표 대신 항목마다 새 줄과 대시를 씁니다. 배열 안에 객체가 들어 있으면, 대시 바로 뒤에 그 객체의 첫 번째 키를 쓰고 나머지 키는 같은 들여쓰기 칸 수로 맞춰 이어 씁니다.

세 규칙을 모두 적용하면 결과는 이렇습니다.

name: myapp
port: 8080
tags:
  - web
  - prod
database:
  host: localhost
  port: 5432

여기에 규칙이 하나 더 있습니다. YAML은 따옴표 없는 값을 자동으로 숫자·null 같은 다른 형식으로 해석합니다. 그래서 1.0처럼 숫자로도 읽힐 수 있는 문자열은 따옴표를 남겨 '1.0'처럼 써야 문자열로 남습니다.

값 안에 콜론과 공백(: )이 그대로 들어가는 문자열도 따옴표로 감싸야 합니다. 콜론과 공백은 YAML에서 키와 값을 나누는 기호라, 값 안에 그대로 두면 구문 오류가 날 수 있습니다.

이 세 가지 구조 규칙과 따옴표 판단만 지키면 손으로도 변환할 수 있습니다. 다만 항목이 많아지면 몇 칸을 들여썼는지, 어떤 문자열에 따옴표가 필요한지 매번 손으로 확인하는 일이 번거롭습니다.

저희 도구로 확인하기.

JSON ➔ YAML 변환기

입력한 JSON을 js-yaml로 실시간 변환합니다. 들여쓰기 2칸·4칸을 선택할 수 있고 가입 없이 무료로 사용합니다.

변환 결과를 붙여넣을 때 흔히 겪는 혼동

변환 자체는 규칙대로 되지만, 결과를 실제 설정 파일에 옮기거나 손으로 다듬는 과정에서 문제가 생기는 경우가 많습니다. 대부분 들여쓰기 문자와 따옴표 처리 두 가지로 좁혀집니다.

상황	왜 문제가 되나	결과
들여쓰기에 Tab 키를 씀	YAML 명세는 들여쓰기에 탭 문자를 허용하지 않습니다	파서가 구문 오류를 냅니다
숫자처럼 보이는 문자열의 따옴표를 지움	`'1.10'`에서 따옴표를 지우면 문자열이 아니라 숫자로 읽힙니다	값이 `1.1`로 바뀌어 끝자리 0이 사라집니다
같은 계층의 형제 항목을 다른 칸 수로 들여씀	YAML은 형제 항목이 같은 칸 수로 들여써져 있어야 같은 계층으로 인식합니다	의도와 다른 계층으로 읽히거나 오류가 납니다
4칸으로 변환한 결과를 2칸짜리 기존 파일에 그대로 붙여넣음	문법적으로는 유효해도 그 파일에서 써 온 들여쓰기 칸 수와 달라집니다	다음에 수정할 때 계층을 눈으로 구분하기 어려워집니다

들여쓰기 2칸과 4칸 중 무엇을 고르든 데이터가 표현하는 계층 구조는 같습니다. 칸 수는 화면에 보이는 간격만 바꿀 뿐, JSON을 다시 파싱했을 때 나오는 값이나 구조는 동일합니다. 다만 기존 파일에 이어 붙일 계획이라면, 그 파일이 쓰고 있는 칸 수와 맞추는 편이 이후에 헷갈릴 일이 적습니다.

빈 객체({})와 빈 배열([])도 짚어둘 부분입니다. 이 둘은 들여쓰기 계층 없이 한 줄로 그대로 표시됩니다. 자식 항목이 있어야 할 자리에 아무 목록도 없이 {}나 []만 보이면 변환이 잘못된 게 아니라 원본 JSON에 애초에 값이 비어 있었다는 뜻입니다.

정리

JSON의 배열은 대시(-) 목록으로, 중첩 객체는 들여쓰기 계층으로 바뀝니다.
들여쓰기 2칸·4칸은 화면에 보이는 간격 차이일 뿐, 파싱했을 때 나오는 데이터 구조는 같습니다.
숫자처럼 보이는 문자열은 따옴표로 감싸야 값이 보존됩니다. 따옴표를 지우면 값이 달라질 수 있습니다.
YAML은 들여쓰기 자체가 문법이라 탭 문자를 쓰면 오류가 나고, 같은 계층의 항목은 칸 수를 통일해야 합니다.
항목이 많아질수록 손 변환은 실수하기 쉬우므로, 변환한 뒤 결과를 눈으로 한 번 검토하는 편이 안전합니다.

JSON ➔ YAML 변환기

입력한 JSON을 js-yaml로 실시간 변환합니다. 들여쓰기 2칸·4칸을 선택할 수 있고 가입 없이 무료로 사용합니다.

자주 묻는 질문

들여쓰기 2칸과 4칸 중 어느 쪽을 골라야 하나요?

데이터 구조는 동일하므로 어느 쪽을 골라도 값은 같습니다. 쿠버네티스·도커 컴포즈 예제 중에는 2칸을 쓰는 경우가 흔한 편이라, 기존 파일에 이어 붙일 계획이라면 그 파일이 쓰고 있는 칸 수와 맞추는 편이 이후 수정할 때 헷갈리지 않습니다.

변환된 YAML에서 어떤 값에 따옴표가 자동으로 붙나요?

숫자로도 읽힐 수 있는 문자열(예: 1.0, 007)이나, 콜론과 공백을 그대로 포함해 그대로 두면 다른 뜻으로 읽힐 수 있는 문자열에 따옴표가 자동으로 붙습니다. 값의 형태를 보고 문자열로 유지해야 하는지 판단해 붙이는 규칙입니다.

배열 안에 객체가 들어 있으면 어떻게 표시되나요?

대시 바로 뒤에 그 객체의 첫 번째 키가 이어지고, 같은 객체의 나머지 키는 그 아래 줄에 첫 번째 키와 같은 칸 수로 맞춰 나열됩니다. 예를 들어 - name: web 다음 줄에 image: nginx처럼 정렬됩니다.

입력한 JSON 형식이 잘못되면 어떻게 되나요?

YAML 결과 대신 구문 분석에 실패했다는 오류 메시지가 표시됩니다. 중괄호나 대괄호 짝이 맞지 않거나 쉼표가 잘못된 경우 흔히 발생하며, 오류가 사라질 때까지는 변환 결과가 나오지 않습니다.