JSON과 YAML 설정 파일을 안전하게 변환하기

문제 상황

JSON과 YAML은 기본 mapping, sequence, 문자열, 숫자, boolean, null을 표현할 수 있지만 모든 세부 문법이 서로 바뀌는 것은 아닙니다. YAML 주석, anchor, alias, tag와 문서 stream에는 같은 JSON 문법이 없습니다. 약한 변환기는 중복 key의 마지막 값만 남기거나 긴 숫자를 반올림할 수도 있습니다. 이 작업 흐름은 원본을 검사하고 보존할 수 없는 문법을 확인한 뒤, 배포 전에 목적지 제품에서 결과를 다시 검증하도록 구성합니다.

공식 출처와 표준

다음 공식 문서는 이 작업 흐름에서 다루는 형식과 보안 경계의 기준입니다. 도구별 실행 검증은 위에 별도로 기록합니다.

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

  RFC Editor / IETF

• YAML Ain't Markup Language, Version 1.2.2

  YAML Language Development Team

이럴 때 사용하세요

• 애플리케이션 JSON 설정을 YAML 기반 설정 체계로 옮겨야 할 때 사용합니다.
• 하나의 Kubernetes, Docker Compose, CI YAML 예제를 점검 도구용 JSON으로 바꿀 때 적합합니다.
• 다른 팀이 선호하는 형식으로 작은 재현 설정을 만들어 지원 요청에 첨부할 때 사용합니다.
• 저장소 변경을 commit하거나 배포하기 전에 JSON과 YAML 표현을 함께 검토할 때 도움이 됩니다.

단계

1. 1단계

   원본 표준과 목적지 확인

   YAML이 YAML 1.2 동작을 전제로 하는지, 원본에 문서가 하나인지 확인합니다. 결과를 사용할 kubectl, Docker Compose, CI 공급자, API client, 애플리케이션 설정 loader를 기록하세요. 형식 변환은 그 제품의 schema 검사를 대신하지 않습니다.

2. 2단계

   옮겨야 할 설정만 남기기

   붙여넣기 전에 불필요한 secret, 생성된 구역, 비활성 예제, 환경 전용 값을 제거합니다. 주석, scalar style, anchor, alias는 목적지에서 같은 방식으로 표현되지 않을 수 있으므로 원본 백업을 보관하세요.

3. 3단계

   하나의 문서를 손실 검사와 함께 변환

   JSON→YAML 또는 YAML→JSON을 고르고 2칸/4칸 들여쓰기를 선택합니다. 검토 중에는 보기 좋은 JSON을 사용하세요. 엄격한 문법 위치, 중복 key, collection YAML key, 지원하지 않는 tag, 달라지는 숫자를 임의로 넘기지 말고 원본에서 수정합니다.

4. 4단계

   주석, anchor, alias와 scalar 타입 검토

   JSON에는 주석 문법이 없어 YAML 주석이 제거됩니다. 제한 내 anchor와 alias는 반복 값으로 펼쳐지므로 관계 자체는 사라집니다. 따옴표 날짜 문자열, 앞자리 0 ID, null, boolean, 여러 줄 문자열과 경고에 표시된 값을 모두 확인하세요.

5. 5단계

   구조와 경계 값 비교

   최상위 key, 중첩 path, 배열 길이, 검토에 필요한 key 순서와 표시된 노드·최대 깊이를 비교합니다. __proto__, constructor, 숫자처럼 보이는 key, 큰 식별자, 음의 0, 유효 숫자가 긴 소수는 특히 직접 확인하세요.

6. 6단계

   목적지에서 검증하고 시험

   현재 결과를 다운로드해 목적지 validator 또는 dry run을 실행합니다. Kubernetes는 schema 인식 도구, Docker Compose는 config 검사, CI와 애플리케이션 설정은 공급자 전용 parser를 사용하세요. Commit이나 배포 전에 실제 적용 설정이 원래 의도와 같은지 비교합니다.

예시

{
  "service": {
    "name": "api",
    "ports": [8080, 8081],
    "release": "2026-07-15",
    "enabled": true
  }
}

service:
  name: api
  ports:
    - 8080
    - 8081
  release: 2026-07-15
  enabled: true

흔한 실수

자주 묻는 질문