JSON vs CSV vs YAML: Convert Between Data Formats Without Losing Data

Three formats dominate how structured data moves between systems today: JSON, CSV, and YAML. Every developer encounters all three within the first months of working on real projects. An API returns JSON. A client sends a spreadsheet export as CSV. A deployment pipeline is configured with YAML. At some point you need to go from one to another — and that is where the trouble starts. Each format was designed for a different job, and the seams show when you try to fit round data into a square format.

This guide explains what JSON, CSV, and YAML actually are, where they differ structurally, and the practical gotchas you will run into when converting between them. If you need to do a conversion right now, the JSON ↔ CSV ↔ YAML Converter on sourcecodestack runs entirely in your browser, with no server upload and no account required.

What is JSON and where is it used?

JSON (JavaScript Object Notation) was published as a lightweight data-interchange format in the early 2000s. Despite the name, it has nothing to do with JavaScript specifically — it is language-agnostic and parsers exist in virtually every programming language. JSON represents data as a hierarchy of objects (key-value pairs in curly braces) and arrays (ordered lists in square brackets). It supports six primitive types: string, number, boolean, null, object, and array. That last pair — object and array — is what gives JSON its expressive power: values can themselves be objects or arrays, creating arbitrarily deep nesting.

JSON is the lingua franca of web APIs. REST APIs almost universally return JSON. Browser-side storage (localStorage, IndexedDB) uses JSON-serialisable values. Configuration files for many modern tools (package.json, tsconfig.json, .eslintrc.json) are written in JSON. Its readability, strict syntax, and universal parser support make it the default choice whenever two systems need to exchange structured data over HTTP.

What is CSV and where is it used?

CSV (Comma-Separated Values) is one of the oldest data exchange formats still in daily use. Its structure is intentionally simple: a first line of column headers, followed by rows where each value is separated by a comma. That simplicity is also its greatest limitation. CSV is a flat tabular format — there is no concept of nesting, no types beyond text, no way to represent a null distinctly from an empty string, and no standard for escaping special characters (though RFC 4180 provides guidance, not every implementation follows it).

Where CSV excels is interoperability with spreadsheets and databases. Microsoft Excel, Google Sheets, LibreOffice Calc, PostgreSQL's COPY command, MySQL's LOAD DATA, and virtually every data analysis tool on the planet can read and write CSV. That makes it the right format when your audience is business users, data analysts, or any tooling that treats data as rows and columns. It is also the smallest representation for large flat datasets — no repeated keys, no brackets, just values and commas.

What is YAML and where is it used?

YAML (YAML Ain't Markup Language, a recursive acronym) was designed to be maximally human-readable. Where JSON uses curly braces and square brackets to mark structure, YAML uses indentation. An object key followed by a colon starts a mapping; a line beginning with a hyphen starts a list item. Comments are supported with #. Multi-line strings, anchors, and aliases allow complex documents to avoid repetition.

YAML is the dominant format for configuration files in the DevOps and cloud-native ecosystem. Kubernetes manifests, GitHub Actions workflows, Docker Compose files, Ansible playbooks, and CircleCI pipelines are all written in YAML. Its verbosity compared to JSON is accepted because configuration files are read and edited by humans far more often than they are generated by machines. The ability to leave comments inline — explaining why a value is set — is something JSON simply cannot offer.

Structural differences: a side-by-side comparison

To make the differences concrete, here is the same dataset represented in all three formats — a short list of users with a nested address field:

Converting JSON to CSV: the flatness problem

JSON-to-CSV is the conversion that catches people off guard most often. The core constraint is this: CSV can only represent a two-dimensional table. Every row must have the same columns, and every cell must hold a scalar value (a string or number, not another object or array).

JSON that works cleanly as CSV is an array of flat objects — every item in the array has the same set of keys, and every value is a primitive. For example:

[ { "name": "Alice", "age": 30, "city": "London" }, { "name": "Bob", "age": 25, "city": "Paris" } ]

This maps to a perfect two-column CSV with a header row. But add a nested object — say, "address": { "street": "Baker St", "postcode": "NW1" } — and there is no obvious way to express that in a single CSV cell. You have three choices:

• Flatten the keys — turn address.street into a column named address_street (dot notation or underscore). This works but creates wide tables.
• Serialise nested values as JSON strings — store the nested object as a raw JSON string inside the CSV cell. Most spreadsheet tools will treat this as an opaque string, which defeats the purpose.
• Drop the nested fields — acceptable only if the nested data is truly not needed in the CSV output.

The sourcecodestack JSON converter will tell you clearly when your JSON cannot be expressed as CSV and why, rather than silently producing broken output. If you need to handle the flattening yourself before converting, flatten the data first and then paste the result.

Arrays inside objects are an even harder case. If a user has an array of phone numbers, there is no standard CSV column for "phone number 1, phone number 2, phone number 3…" without knowing the maximum array length upfront. This is why data modelling matters: if you know your output target is CSV, design your data to be flat from the start.

Converting JSON to YAML: mostly painless, with one trap

YAML is a superset of JSON — every valid JSON document is also valid YAML. That means converting JSON to YAML is conceptually lossless: all data types survive the round-trip. Objects become YAML mappings. Arrays become YAML sequences. Numbers, booleans, and nulls are preserved with their correct types.

The practical gotcha is indentation sensitivity. YAML uses whitespace to encode structure. Inconsistent indentation — mixing tabs and spaces, or accidentally shifting a block by one space — produces a completely different document or a parse error. When generating YAML programmatically or with a converter, always use a library (like js-yaml, PyYAML, or snakeyaml) rather than building the string with string concatenation. Libraries guarantee consistent indentation.

The other trap is YAML's implicit typing. A bare value like yes, on, or true is parsed as a boolean in YAML 1.1 (which many libraries still use). A plain number like 07 might be interpreted as octal in older parsers. These are edge-cases but they are real bugs in production. When you need a string value, quote it explicitly.

Converting CSV to JSON: the type coercion trap

Going from CSV to JSON is structurally simple — every row becomes an object, headers become keys, values become values. The catch is that CSV has no type system. Everything in a CSV file is a string. A column of ages like 30, 25, 35 will come out of a naive parser as the strings "30", "25", "35", not the numbers 30, 25, 35. If your downstream code does arithmetic on these values, it will either throw an error or silently produce wrong results.

Similarly, a column that represents booleans (TRUE/FALSE, yes/no, 1/0) will arrive as strings. Null-equivalent values are ambiguous: is an empty CSV cell a null, an empty string, or should it be omitted from the JSON object entirely? Different tools make different choices here.

The practical advice: after converting CSV to JSON, always add a validation or transformation step that coerces the types you expect. In JavaScript this might be a .map() that runs Number(row.age) and row.active === "true". In Python it is adding explicit type casts in your DictReader loop. In a database import, it is defining the column types in the target table's schema so the database does the coercion on INSERT.

Another CSV gotcha: the first row is assumed to be headers. If your CSV lacks a header row, the parser will treat the first data row as column names — producing unexpected results. Most parsers let you supply column names manually when there is no header.

Real workflows where format conversion matters

API response to spreadsheet

You fetch a list of records from a REST API — the response is JSON. A non-technical stakeholder needs it in a spreadsheet. The conversion path is JSON → CSV → Excel/Google Sheets. The constraint is that the JSON must be a flat array of objects. If it is not (common with API responses that nest metadata), you need to extract the relevant array first (usually the data or results key) before converting.

Spreadsheet data to a database or API

A product team hands you a CSV of 500 product records to import. The database API expects JSON. The path is CSV → JSON, and the main task after conversion is adding type coercion so numbers are numbers and booleans are booleans before you POST each record. A common mistake is to send the raw-string JSON and then wonder why numeric comparisons in the database behave oddly.

JSON config to YAML (or vice versa)

A tool you use accepts only YAML but you have been storing its configuration as JSON (for example, because your team already uses JSON for other settings files). Converting JSON → YAML is mostly mechanical, but check whether the target tool uses YAML 1.1 or 1.2 — a few edge cases around booleans and octals differ between versions. The reverse (YAML → JSON) is also common when an API or SDK requires JSON input and you authored the document in YAML for readability. Any comments in the YAML will be silently discarded.

Debugging a Kubernetes or CI/CD manifest

YAML's indentation sensitivity is a common source of subtle Kubernetes errors. If you are not sure whether your manifest is structurally valid, converting it to JSON (which makes the nesting explicit with braces and brackets) is often faster than reading the raw YAML. Once you confirm the structure is correct, you can convert back to YAML. The round-trip YAML → JSON → YAML will reformat consistently but discard any comments.

Data migration between systems

When moving data from one system to another — say, from a legacy MySQL database to a modern SaaS product — the typical flow is MySQL → CSV export → JSON → API import. Each conversion step introduces a potential type or encoding issue. The most common ones: character encoding (ensure UTF-8 throughout), date format (ISO 8601 is safest), and null vs. empty-string handling. Convert a small sample first, validate it end-to-end, then run the full migration.

Why doing data conversion locally protects sensitive information

Not all data you need to convert is public. API responses often contain personally identifiable information (PII) — names, email addresses, phone numbers, addresses. Configuration files may contain credentials, API keys, or database connection strings. Pasting this data into an online tool that runs on a server means transmitting it over the network and trusting a third party's data handling and logging practices.

A client-side converter avoids this entirely. The conversion logic runs as JavaScript in your browser; the data is never sent anywhere. You can verify this yourself with your browser's network inspector: open the Developer Tools (F12), go to the Network tab, and confirm no requests are made when you paste data and convert it. The sourcecodestack JSON ↔ CSV ↔ YAML Converter is fully client-side for exactly this reason — it is safe to use with production API responses, configuration files containing real credentials, and any data you would not want to upload to a server.

This also means the tool works offline once the page has loaded, there are no rate limits, and there is no need to create an account. The data lives only on your machine.

The most common conversion mistakes and how to avoid them

• Assuming CSV preserves types. Always add a type-coercion step after CSV-to-JSON conversion if your code depends on non-string values.
• Trying to convert nested JSON directly to CSV. Flatten the data first. A quick .map() that extracts the fields you need is usually enough.
• Mixing tabs and spaces in YAML. YAML forbids tabs for indentation. Use a formatter or linter to catch this before your CI pipeline does.
• Losing comments when round-tripping YAML. Comments are not part of the data model. If comments matter, keep the source YAML file; only convert a copy.
• Ignoring character encoding in CSV. CSV files exported from Excel are often Windows-1252 encoded, not UTF-8. Characters outside ASCII (accented letters, non-Latin scripts) will be garbled unless you convert the encoding explicitly.
• Not quoting CSV fields that contain commas. A value like "London, UK" must be wrapped in double quotes in the CSV; otherwise the comma is treated as a column separator, shifting all subsequent columns in that row.
• Forgetting that JSON keys are ordered in modern engines, but the specification does not guarantee order. If column order in CSV output matters, sort the keys explicitly before conversion.

Choosing the right tool for the job

For quick one-off conversions — an API response you want to paste into a spreadsheet, a config file you need to reformat — the fastest path is a browser-based converter like the one available on this site. Paste, select formats, done. The JSON ↔ CSV ↔ YAML Converter supports all six conversion directions (JSON ↔ CSV, JSON ↔ YAML, CSV ↔ YAML), converts as you type, and lets you copy or download the output with one click.

For repeated or automated conversions in a pipeline, write a small script. In Node.js, the js-yaml package handles YAML parsing and generation. In Python, the standard library json and csv modules plus the pyyaml package cover everything. For transforming CSV to JSON with type coercion at scale, jq (a command-line JSON processor) and csvkit are useful complements.

Understanding the structural constraints of each format — and respecting them rather than fighting them — is what separates a clean data pipeline from one that silently corrupts data. JSON is for richly structured data. CSV is for flat, tabular data that needs to travel to spreadsheets or databases. YAML is for human-authored configuration. Know which job you are doing, and pick accordingly.