Understanding Data Formats

Every time two systems exchange information — an API sending a response, a configuration file being read, a spreadsheet being imported — they need to agree on how that data is structured. Data formats are the shared language that makes this possible.

Choosing the wrong format can mean verbose, bloated files that are slow to parse; format-specific compatibility issues with third-party tools; or data that's hard for humans to read and debug. Choosing the right format means efficient data transfer, easy tooling support, and maintainable code.

The four formats covered in this guide — JSON, XML, YAML, and CSV — collectively handle the vast majority of data exchange scenarios you'll encounter. Each has strengths and weaknesses shaped by the problems they were designed to solve.

JSON (JavaScript Object Notation) is the dominant data interchange format for web APIs. Introduced by Douglas Crockford in the early 2000s as a simpler alternative to XML, JSON has become the default format for REST APIs, configuration files, and NoSQL databases like MongoDB.

JSON Structure

JSON is built on two structures: objects (key-value pairs enclosed in curly braces) and arrays (ordered lists enclosed in square brackets). Values can be strings, numbers, booleans, null, objects, or arrays — enabling arbitrarily complex nested structures.

{
  "user": {
    "name": "Alice",
    "age": 30,
    "roles": ["admin", "editor"],
    "active": true,
    "profile": null
  }
}

JSON Strengths

• Native to JavaScript — no parsing library needed in browsers
• Compact and efficient compared to XML
• Universal parser support in every modern programming language
• Human-readable while remaining machine-parseable
• Strong ecosystem of validators, formatters, and transformation tools

JSON Limitations

• No comments supported (a common frustration for config files)
• No support for dates natively — typically stored as ISO 8601 strings
• Strict syntax — trailing commas break parsing
• No schema enforcement without additional tooling (use JSON Schema for that)

Best for: REST APIs, web application data exchange, NoSQL database documents, application configuration (with caveats about the lack of comments).

XML (eXtensible Markup Language) predates JSON and was the dominant web data format through the 2000s. It remains essential in enterprise systems, document formats (Microsoft Office files are XML internally), RSS/Atom feeds, and SOAP web services.

<user>
  <name>Alice</name>
  <age>30</age>
  <roles>
    <role>admin</role>
    <role>editor</role>
  </roles>
  <active>true</active>
  <profile />
</user>

XML Strengths

• Supports attributes alongside element content (more metadata options)
• XSD schema validation — strict, formal type checking
• XSLT transformations — powerful way to transform XML into other formats
• XPath and XQuery for sophisticated querying
• Comments supported natively
• Namespace support for avoiding naming conflicts across schemas

XML Limitations

• Verbose — XML files are significantly larger than equivalent JSON
• More complex to parse and write by hand
• Fallen out of favor for new REST APIs
• The verbosity can make it harder to read at a glance

Best for: SOAP services, enterprise integrations, document-centric data (where mixed content matters), RSS/Atom feeds, Microsoft Office file formats, SVG graphics.

YAML (YAML Ain't Markup Language) is a superset of JSON specifically designed for human readability. It uses indentation to define structure instead of brackets and braces, making it feel more like natural prose. YAML is the dominant format for configuration files in the DevOps ecosystem — Docker Compose, Kubernetes, GitHub Actions, Ansible, and many more all use YAML.

user:
  name: Alice
  age: 30
  roles:
    - admin
    - editor
  active: true
  profile: null

YAML Strengths

• Highly readable — minimal punctuation compared to JSON or XML
• Comments supported (with #)
• Multi-line strings handled elegantly
• Anchors and aliases allow reusing values without repetition
• Superset of JSON — all valid JSON is valid YAML

YAML Pitfalls

• Indentation is syntactically significant — a misplaced space can break your entire configuration
• Implicit type conversions can cause unexpected behavior (the string "yes" becomes boolean true in some parsers)
• More complex spec than JSON — some edge cases in parsing are counterintuitive
• Not ideal for data that will be programmatically generated or parsed in performance-critical paths

Best for: Configuration files, CI/CD pipelines (GitHub Actions, GitLab CI), infrastructure-as-code (Kubernetes, Docker Compose), Ansible playbooks, any config file where humans edit by hand frequently.

CSV (Comma-Separated Values) is arguably the simplest data format: rows of values separated by commas (or sometimes tabs, semicolons, or other delimiters), with an optional header row. It's essentially a plain-text representation of a spreadsheet.

name,age,roles,active
Alice,30,"admin,editor",true

Notice that the CSV representation loses structure — the roles field has to be a delimited string inside the field itself, which requires special handling. CSV works well for flat data (one level, no nesting) but struggles with complex hierarchical data.

CSV Strengths

• Universal — opens in Excel, Google Sheets, LibreOffice, Python, R, virtually everything
• Minimal overhead — no tags, brackets, or punctuation beyond the delimiters
• Easy to generate from databases with SQL's export features
• Human-readable for simple data
• Excellent for bulk data imports/exports

CSV Limitations

• No standard for nested/hierarchical data
• No data types — everything is a string; parsing must infer types
• Handling commas inside values requires quoting, which adds complexity
• No standard for encoding or line endings across operating systems
• Poor for data that changes shape (optional fields, variable columns)

Best for: Database exports, spreadsheet data, bulk imports, reporting data, financial records, any flat tabular data that needs to be opened in spreadsheet software.