JSON·YAML·CSV·Markdown 차이 비교 치트시트 - 용도별 선택 가이드

JSON, YAML, CSV, Markdown은 모두 텍스트 기반으로 구조화된 정보를 표현하는 대표적인 데이터 형식입니다. 하지만 각 형식이 설계된 목적과 강점을 발휘하는 영역은 크게 다릅니다. 설정 파일에 CSV를 사용하면 복잡한 계층을 표현하기 어렵고, API 응답에 YAML을 쓰면 문법적 엄격함이 부족해지며, 대량의 표 데이터를 JSON으로 주고받으면 객체 키가 반복되어 데이터가 비대해집니다. Markdown은 사람이 읽는 기술 문서로는 최적이지만, 기계가 파싱해야 하는 원본 데이터 저장소로 다루면 나중에 파싱 단계에서 큰 문제가 발생합니다.

이 글은 프로젝트를 시작하거나 데이터 파이프라인을 설계할 때 "어떤 형식을 선택해야 하는가"를 한 페이지에서 빠르게 판단할 수 있도록 정리한 치트시트입니다. 빠른 결정 매트릭스부터 시작해 기능 비교표, 주석 지원 여부, 파서 생태계, 실무 용도별 매트릭스, 자주 발생하는 안티패턴, LLM(대규모 언어 모델) 프롬프트 환경에서의 선택 기준, 공식 표준 사양 정보까지 한눈에 파악할 수 있도록 구성했습니다.

빠른 결정 매트릭스 — 어떤 형식을 선택할까

형식 선택에 고민이 된다면 아래 대표 용도별 권장 형식 표를 참고하세요.

핵심을 요약하면 다음과 같습니다. 머신 간 데이터 통신에는 JSON, 사람이 손으로 편집하는 설정에는 YAML, 2차원 표 데이터에는 CSV, 사람이 읽는 문서에는 Markdown이 기본입니다. 그 외의 세부적인 요구사항은 아래 기능 비교를 통해 조정합니다.

YAML vs Markdown vs JSON 한눈에 보는 결론

YAML vs Markdown

YAML은 프로그램이 읽는 데이터, Markdown은 사람이 읽는 문서를 위한 형식입니다. 설정 파일, CI 파이프라인, Kubernetes 매니페스트에는 YAML을, README, 문서, 메모에는 Markdown을 선택합니다. 정적 사이트의 글은 보통 둘을 함께 쓰며, Markdown 본문 위에 YAML frontmatter를 둡니다.

Markdown vs JSON

JSON은 머신 간 데이터 교환, Markdown은 사람이 읽는 텍스트를 위한 형식입니다. API 응답이나 구조화된 로그에는 어느 언어에서나 엄격하게 파싱되는 JSON을 씁니다. Markdown에는 스키마가 없어서, 프로그램이 중첩된 데이터를 다시 읽어 들이는 용도에는 맞지 않습니다. LLM에 넘기는 컨텍스트라면 위의 결정 매트릭스대로 Markdown이 적합합니다.

YAML vs JSON

둘 다 중첩된 데이터를 표현할 수 있습니다. 프로그램끼리 주고받는 데이터에는 문법이 엄격하고 어느 언어의 표준 라이브러리에도 파서가 있는 JSON이 맞습니다. 사람이 손으로 편집하는 파일에는 주석과 앵커를 쓸 수 있고 기호가 적은 YAML이 맞습니다. 대개 주석이 필요한지가 결정적이며, 아래 '주석 지원 여부 비교'에 형식별 처리를 정리했습니다.

먼저 브라우저에서 4가지 형식 변환해 보기

각 형식의 구조적 차이는 설명만 읽는 것보다 동일한 데이터를 직접 변환해 보며 눈으로 확인하는 것이 가장 빠릅니다. FormatArc의 모든 변환 도구는 외부 서버 통신 없이 100% 브라우저 로컬에서 실행되므로, 보안이 중요한 사내 데이터나 실제 API 응답도 안전하게 테스트할 수 있습니다.

• JSON 포맷터 — JSON 정렬, 유효성 검증 및 문법 오류 수정
• YAML to JSON / JSON to YAML — YAML과 JSON 상호 변환
• CSV to JSON / JSON to CSV — 표 데이터와 구조화된 JSON 상호 변환
• CSV to Markdown — 스프레드시트 표를 마크다운 테이블로 변환
• Markdown to HTML / HTML to Markdown — 문서 형식 상호 변환

보안이 중요한 데이터를 온라인 변환기에 입력할 때의 점검 기준은 온라인 변환 사이트 보안 검증 글에서 자세히 다루고 있습니다.

이 글에서 다루는 4가지 형식과 제외한 형식

본 글에서는 현대 웹 개발, 클라우드 인프라, 데이터 교환, 기술 문서 작성에서 가장 널리 쓰이는 JSON, YAML, CSV, Markdown 4가지 텍스트 형식을 중심으로 비교합니다.

본 비교에서 다루지 않는 형식은 다음과 같습니다.

• XML — 강력한 스키마 검증을 지원하지만 문법이 장황하여 신규 웹 프로젝트에서는 채택이 줄고 있습니다. SOAP, RSS, SVG, Office Open XML 등 기존 시스템 연동 시 주로 쓰입니다.
• TOML — Rust의 Cargo나 Python의 pyproject.toml 등에서 활발히 쓰이는 설정 형식입니다. YAML이나 JSON5와 용도가 겹치며 웹 프론트엔드 환경에서는 출현 빈도가 상대적으로 낮습니다.
• Parquet — 빅데이터 분석에 최적화된 열 지향(columnar) 바이너리 포맷입니다. 텍스트 형식 비교 범주에서 제외합니다.
• XLSX / ODS — 스프레드시트 바이너리 포맷입니다. 본 글에서는 CSV 내보내기/가져오기 경로를 통해서만 다룹니다.

같은 데이터를 4가지 형식으로 표현하기

사용자 2명의 정보(이름, 나이, 보유 기술 목록)를 4가지 형식으로 작성한 예시입니다. 동일한 데이터가 형식에 따라 어떻게 구조화되는지 비교해 보세요.

JSON 버전

{
  "users": [
    { "name": "Alice", "age": 30, "skills": ["Python", "Go"] },
    { "name": "Bob",   "age": 25, "skills": ["JavaScript"] }
  ]
}

YAML 버전

users:
  - name: Alice
    age: 30
    skills:
      - Python
      - Go
  - name: Bob
    age: 25
    skills:
      - JavaScript

CSV 버전

CSV는 중첩된 계층 구조를 직접 표현할 수 없습니다. 따라서 skills 배열을 단일 셀 안에 구분자(; 등)로 합치거나, 여러 열로 펼치거나, 별도의 테이블로 분리하는 평탄화 작업이 필요합니다. 가장 단순한 구분자 연결 방식은 다음과 같습니다.

name,age,skills
Alice,30,Python;Go
Bob,25,JavaScript

Markdown 버전

Markdown은 데이터 교환용 형식이 아니라 문서 작성을 위한 형식이므로, 구조화된 표는 GFM(GitHub Flavored Markdown) 테이블 문법을 활용해 표현합니다.

| name  | age | skills      |
|-------|-----|-------------|
| Alice | 30  | Python, Go  |
| Bob   | 25  | JavaScript  |

동일한 데이터를 넣었을 때 각 형식의 특성이 뚜렷하게 드러납니다. JSON은 문법이 엄격해 기계 파싱에 최적화되어 있고, YAML은 사람이 읽기 편합니다. CSV는 표 형태의 2차원 데이터를 간결하게 담지만 중첩 구조에 취약하며, Markdown은 렌더링된 시각적 결과물은 뛰어나지만 데이터 원본 저장소로는 한계가 있습니다.

4가지 형식의 기능 비교 매트릭스

각 형식이 어떤 데이터 구조와 기능을 지원하는지 정리한 비교표입니다.

JSON과 YAML은 객체, 배열, 기본 자료형이라는 동일한 데이터 모델을 공유하므로 상호 변환이 매우 쉽습니다. FormatArc에서는 YAML to JSON과 JSON to YAML 양방향 변환기를 모두 제공합니다. 두 형식의 문법과 실무 동작 차이에 대한 자세한 비교는 YAML과 JSON의 차이점 글에서 확인할 수 있습니다.

주석 지원 여부 비교

설정 파일 포맷을 선택할 때 가장 중요한 기준 중 하나는 주석 작성 가능 여부입니다. 표준 사양과 파생 확장판 간의 차이를 정리했습니다.

표준 JSON에는 주석 문법이 없으므로, 설정 파일에 주석을 꼭 남겨야 한다면 YAML, JSONC, JSON5를 선택하거나 _comment 같은 더미 키를 활용하는 방안을 검토해야 합니다. JSON 주석 문제에 대한 자세한 해결 방법과 대안은 JSON 주석처리 방법 글에서 다루고 있습니다.

프로그래밍 언어별 파서 생태계 비교

실제 개발 환경에서 표준 라이브러리만으로 파싱할 수 있는지, 외부 라이브러리 설치가 필요한지는 생산성에 큰 영향을 미칩니다.

JSON과 CSV는 대부분의 주요 프로그래밍 언어에서 표준 라이브러리로 지원됩니다. 반면 YAML과 Markdown은 서드파티 라이브러리가 필요하지만, 언어별로 표준에 가까운 안정적인 라이브러리가 정착되어 있습니다. FormatArc는 Node.js 생태계의 yaml, papaparse, marked, turndown, remark 등을 브라우저 번들에 탑재하여 서버 통신 없는 독립적인 변환 환경을 구현했습니다.

용도별 권장 형식 결정 매트릭스

실제 업무 상황에서 마주하는 구체적인 사용 사례별 최적의 형식을 정리한 가이드입니다.

마크다운 표는 손으로 직접 편집하기 번거로우므로, 스프레드시트나 CSV로 원본을 관리하면서 CSV to Markdown 변환기를 통해 마크다운 표로 변환하는 워크플로를 추천합니다. GitHub README에 표를 삽입하는 구체적인 절차는 GitHub README 표 만들기 글을 참고하세요.

자주 발생하는 잘못된 선택과 안티패턴

프로젝트 현장에서 반복적으로 목격되는 데이터 형식 선택의 전형적인 실패 사례와 주의점입니다.

CSV에서 중첩 데이터 다루기

{ "user": { "address": { "city": "Seoul" } } }과 같은 계층적 데이터를 CSV로 다루려고 하면, 필드를 평탄화하는 규칙을 별도로 정의해야 하고 데이터를 읽어들일 때도 복원 로직이 복잡해집니다. 계층 구조가 필요한 데이터라면 처음부터 JSON이나 YAML을 선택하거나, 데이터베이스의 관계형 모델처럼 여러 개의 CSV로 분리해야 합니다.

YAML의 암묵적 타입 변환 함정 (노르웨이 문제)

YAML 1.1 사양에서는 no, yes, on, off 등의 문자열이 불리언(Boolean) 값으로 자동 변환되었습니다. 이로 인해 노르웨이의 국가 코드인 NO가 문자열이 아닌 false로 바뀌어 버리는 이른바 "노르웨이 문제(Norway Problem)"가 자주 발생했습니다. YAML 1.2에서 이러한 규칙이 개선되었지만, 여전히 구버전 호환 모드로 동작하는 파서가 많으므로 불리언으로 오인될 수 있는 문자열은 항상 따옴표로 감싸는 것이 안전합니다.

country: "NO"   # 안전함: 명시적 문자열로 파싱됨
country:  NO    # 위험함: YAML 1.1 호환 파서에서 false로 변환될 수 있음

표준 JSON에 주석 작성하기

VS Code의 settings.json에서 주석이 동작하기 때문에 표준 JSON에서도 주석을 쓸 수 있다고 오해하는 경우가 많습니다. 하지만 이는 VS Code가 채택한 비표준 확장인 JSONC입니다. 표준 JSON(RFC 8259)에 주석을 작성하면 JSON.parse나 각 언어의 표준 파서에서 Unexpected token 오류가 발생합니다. 주석이 필요한 설정 파일이라면 YAML, JSON5, JSONC를 사용하거나 별도의 설정 파일로 분리하세요.

CSV 포맷 방언 차이 간과하기

RFC 4180이라는 표준 문서가 존재하지만, 실제 현장의 CSV 파일은 수많은 방언으로 나뉩니다. 구분자(쉼표 ,, 탭 \t, 세미콜론 ;), 줄바꿈 코드(CRLF vs LF), 따옴표 처리 방식, BOM(Byte Order Mark) 존재 여부, 문자 인코딩(UTF-8 vs EUC-KR), 셀 내 줄바꿈 이스케이프 등이 도구마다 다르게 동작합니다. "단순한 CSV니까 문제없겠지"라고 방심하지 말고, 시스템 연동 전 샘플 데이터로 양쪽 파서의 동작을 반드시 검증해야 합니다.

Markdown을 기계 파싱용 데이터 저장소로 사용하기

Markdown은 본질적으로 문서를 표현하기 위한 형식이며 기계가 안정적으로 데이터를 추출하도록 설계된 형식이 아닙니다. 마크다운 표 문법은 파서마다 세부 렌더링 방식이 다르고, 셀 안에 파이프 기호(|)나 줄바꿈이 포함되면 파싱이 깨지기 쉽습니다. 렌더러에 따라 마크다운 표가 깨지거나 표시되지 않는 원인과 해결법은 마크다운 표가 안 나오거나 깨질 때 해결법 글을 참고하세요. 기계 간 데이터 전달이 목적이라면 Markdown 대신 JSON이나 CSV를 사용하세요.

Markdown 표가 CommonMark 표준이라고 오해하기

마크다운 표는 순수 CommonMark새 탭에서 열립니다 사양에는 포함되어 있지 않으며, GitHub Flavored Markdown(GFM)새 탭에서 열립니다의 확장 기능입니다. CommonMark 표준만을 엄격하게 준수하는 렌더러에 마크다운 표를 넘기면 표가 아니라 일반 문단으로 뭉개져 렌더링됩니다. GitHub, GitLab, velog, Tistory 등 주요 개발 플랫폼은 GFM을 지원하지만, 사내 위키나 자체 블로그 엔진을 쓸 때는 GFM 확장 활성화 여부를 확인해야 합니다. CommonMark와 GFM의 상세한 문법 차이는 CommonMark와 GFM의 차이점 글에서 정리하고 있습니다.

LLM(대규모 언어 모델) 프롬프트에서의 형식 선택

ChatGPT, Claude, Gemini 같은 LLM에 문맥(Context) 데이터를 제공할 때 가장 추천되는 형식은 Markdown입니다. HTML과 비교했을 때 불필요한 태그와 속성이 제거되어 토큰 소비를 대폭 절약할 수 있으며, 표, 목록, 제목, 코드 블록 등의 구조를 LLM이 정확하게 인식합니다.

반면 LLM의 구조화된 출력(Function Calling, JSON Mode)을 생성할 때는 JSON이 필수적입니다. 따라서 실무에서는 "입력 프롬프트는 Markdown, 출력 데이터는 JSON"이라는 비대칭 구조가 사실상의 표준으로 자리 잡았습니다.

YAML은 들여쓰기가 LLM 토크나이저에 의해 불안정해질 수 있고 암묵적 타입 변환으로 인해 문자열이 불리언으로 뒤바뀌는 위험이 있어 LLM 입출력 포맷으로는 피하는 것이 안전합니다. LLM 환경에서의 Markdown과 HTML 토큰 효율 실측 데이터와 비교는 LLM 입력 시 Markdown vs HTML 글에서 다루고 있습니다.

사양과 표준 역사

형식 선택의 기술적 근거와 표준 버전을 확인하고 싶을 때 참고할 수 있는 사양 정보입니다.

JSON과 CSV는 IETF RFC를 통해 사양이 안정화되어 있습니다. 반면 YAML과 Markdown은 사양 버전(YAML 1.1 vs 1.2)이나 방언(CommonMark vs GFM)에 따른 동작 차이를 염두에 두고 작업해야 합니다.

각 형식의 기초 문법과 실무 활용법을 더 자세히 알아보려면 다음 글을 참고하세요.

• JSON이란? — JSON 기본 문법과 용도
• YAML이란? — YAML 기본 문법과 용도
• CSV란? — CSV 기본 문법과 용도

FormatArc로 데이터 형식 상호 변환하기

실무에서 데이터 형식을 변환해야 할 때 자주 쓰이는 경로입니다. FormatArc의 모든 도구는 브라우저 내부에서만 연산이 수행되며 서버로 데이터를 전송하지 않습니다.

이 도구들을 조합하면 "API 응답 JSON → YAML로 변환해 설정 파일 생성", "Excel 표 → CSV 내보내기 → Markdown 표로 변환해 README 작성", "웹 문서 HTML → Markdown으로 변환해 ChatGPT 프롬프트 입력"과 같은 전체 작업 파이프라인을 브라우저 탭 하나에서 안전하게 끝낼 수 있습니다.

자주 묻는 질문

설정 파일로는 JSON, YAML, TOML 중 무엇을 써야 하나요?

주석과 가독성이 중요하다면 YAML이 가장 널리 쓰입니다(Kubernetes, Docker, GitHub Actions 등). 주석이 필요하지만 들여쓰기 민감도가 부담스럽다면 TOML이나 JSON5가 좋은 대안입니다. 표준 JSON은 주석을 지원하지 않으므로 사람 손으로 자주 수정해야 하는 설정 파일로는 추천되지 않습니다.

REST API에서 JSON 대신 YAML이나 CSV를 쓰면 안 되나요?

기술적으로 불가능하지는 않지만 권장되지 않습니다. JSON은 엄격한 문법, 명확한 타입 정의, 모든 주요 언어의 표준 파서 내장 지원으로 인해 웹 API의 사실상 표준입니다. YAML은 파싱 속도가 상대적으로 느리고 암묵적 타입 변환 문제가 있으며, CSV는 중첩 계층 구조를 표현할 수 없습니다.

Excel 데이터를 Markdown 표나 JSON으로 쉽게 바꾸는 방법은?

Excel이나 Google Sheets에서 영역을 복사하거나 CSV로 내보낸 후, CSV to Markdown을 사용하면 즉시 정렬된 마크다운 테이블이 생성됩니다. API 연동을 위해 구조화된 데이터가 필요하다면 CSV to JSON을 사용하세요.

LLM에 데이터를 입력할 때 가장 유리한 형식은 무엇인가요?

문서나 표 데이터를 입력할 때는 Markdown이 가장 유리합니다. 불필요한 태그가 없어 토큰을 절약할 수 있고 구조 인식 정확도가 높습니다. 반면 LLM이 프로그래밍적으로 처리할 수 있는 결과를 반환해야 할 때는 JSON 출력을 요구하는 것이 표준입니다.

FormatArc에서 변환할 때 데이터 유출 위험은 없나요?

FormatArc의 모든 데이터 변환 작업은 사용자의 웹 브라우저 내에서 JavaScript(WebAssembly 및 로컬 라이브러리)로만 처리됩니다. 입력한 텍스트나 파일 데이터가 외부 서버로 전송되는 일이 전혀 없으므로, 기밀 데이터나 개인정보도 안전하게 다룰 수 있습니다.

마무리

어떤 형식을 선택해야 할지 고민될 때의 최종 체크포인트입니다.

• 시스템 간 데이터 교환 및 API 통신: JSON
• 사람이 직접 작성하고 관리하는 설정 파일: YAML
• 대규모 2차원 수치·표 데이터: CSV
• 사람이 읽는 서식 있는 문서: Markdown
• LLM 프롬프트 입력: Markdown / LLM 구조화된 출력: JSON

데이터 형식에 절대적인 정답은 없습니다. 가독성, 엄격함, 파서 지원 범위, 주석 필요성, 토큰 효율 등 내 프로젝트가 어떤 가치를 최우선으로 두는지에 따라 알맞은 형식을 선택하는 것이 중요합니다.

공식 사양 정보는 아래 문서를 참고하세요.

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format새 탭에서 열립니다
• YAML 1.2.2 Specification새 탭에서 열립니다
• RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files새 탭에서 열립니다
• CommonMark Specification새 탭에서 열립니다
• GitHub Flavored Markdown Spec새 탭에서 열립니다