JSON Vs. YAML Vs. TOML: How to Use in Python

JSON, YAML, and TOML are all data serialization formats. They are commonly used for configuration files. They are also used for data exchange between systems and storing structured data. Here are their differences and syntax examples.

Table of contents

1. Serialization formats: JSON Vs YAML Vs TOML
   1. Differences
   2. Syntax Examples:
      1. JSON Example:
      2. YAML Example:
      3. TOML Example:
   3. Key Points:
   4. Use Cases for JSON, YAML, and TOML
      1. 1. JSON (JavaScript Object Notation):
      2. 2. YAML (YAML Ain’t Markup Language):
      3. 3. TOML (Tom’s Obvious, Minimal Language):
   5. Choosing the Right Format:
   6. 1. Reading JSON Data in Python
      1. Example JSON File (data.json):
      2. Python Code to Read JSON:
   7. 2. Reading YAML Data in Python
      1. Example YAML File (data.yaml):
      2. Python Code to Read YAML:
   8. 3. Reading TOML Data in Python
      1. Example TOML File (data.toml):
      2. Python Code to Read TOML:
   9. Summary:

Serialization formats: JSON Vs YAML Vs TOML

Differences

1. JSON (JavaScript Object Notation):
   • Format: Text-based, uses a subset of JavaScript syntax.
   • Readability: Less human-readable, especially for complex structures.
   • Data Types: Supports strings, numbers, arrays, objects (dictionaries), booleans, and null.
   • Comments: This does not support comments.
   • Use Cases: Web APIs, data interchange between server and client, configuration files.
2. YAML (YAML Ain’t Markup Language):
   • Format: Human-readable, uses indentation and a clean, minimalistic syntax.
   • Readability: Very human-readable and easy to edit.
   • Data Types: Supports strings, numbers, lists, dictionaries, booleans, and null.
   • Comments: Supports comments using #.
   • Use Cases: Configuration files (e.g., Docker Compose, Ansible playbooks).
3. TOML (Tom’s Obvious, Minimal Language):
   • Format: Designed to be minimal and easily readable, with an INI-like syntax.
   • Readability: Human-readable, intended to be unambiguous.
   • Data Types: Supports strings, numbers, arrays, tables (dictionaries), booleans, dates, and times.
   • Comments: Supports comments using #.
   • Use Cases: Configuration files for applications (e.g., Python’s pyproject.toml).

Syntax Examples:

JSON Example:

{
  "name": "Example Project",
  "version": 1.0,
  "dependencies": {
    "library1": "1.2.3",
    "library2": "4.5.6"
  },
  "is_active": true,
  "tags": ["example", "json", "config"]
}

YAML Example:

name: Example Project
version: 1.0
dependencies:
  library1: "1.2.3"
  library2: "4.5.6"
is_active: true
tags:
  - example
  - yaml
  - config

TOML Example:

name = "Example Project"
version = 1.0
is_active = true

[dependencies]
library1 = "1.2.3"
library2 = "4.5.6"

tags = ["example", "toml", "config"]

Key Points:

• JSON is strict, less human-friendly, and commonly used in web contexts.
• YAML is more human-readable with support for comments, but its reliance on indentation can lead to syntax errors.
• TOML aims for simplicity and readability with a clear and unambiguous syntax.

Also, read: 50 Python Tips and Tricks You Should Read Right Away

Use Cases for JSON, YAML, and TOML

1. JSON (JavaScript Object Notation):

• Web APIs and Data Interchange: JSON is widely used to send data between a client and server in web applications. It is also widely used for receiving data. It’s supported by most programming languages and is ideal for RESTful APIs.
• Configuration Files: JSON is often used in configuration files for tools and applications. Especially in environments where human readability is less of a priority (e.g., package.json for Node.js projects).
• Data Storage: JSON is used for storing structured data: in NoSQL databases like MongoDB.
• Logging and Data Serialization: Ideal for logging and serializing data structures due to its compatibility with many languages and platforms.

2. YAML (YAML Ain’t Markup Language):

• Configuration Files: YAML is popular for configuration files in many tools and platforms because of its human-readable format. Examples include:
  • DevOps Tools: Docker Compose (docker-compose.yml), Kubernetes manifests.
  • CI/CD Pipelines: Configuration for services like GitLab CI, CircleCI, and Ansible playbooks.
  • Programming Frameworks: Configurations for frameworks like Ruby on Rails (database.yml).
• Data Serialization: Sometimes used for data serialization in scenarios where readability by humans is important, like in collaborative projects.
• Document Markup: YAML can be used for simple document markup or defining templates for content management systems.

3. TOML (Tom’s Obvious, Minimal Language):

• Configuration Files: TOML is designed to be a simple and unambiguous format for configuration files. It prioritizes clarity and ease of editing. Examples include:
  • Software Projects: Python’s pyproject.toml for specifying build system requirements.
  • Rust Projects: Cargo’s configuration (Cargo.toml) for Rust projects.
• Environment Configuration: Often used in projects where configuration needs to be human-readable and editable. This prevents introducing errors. An example is defining environment variables.
• Application Settings: Useful for defining settings for applications that need to be adjusted or fine-tuned by users or administrators.

Choosing the Right Format:

• Use JSON when you need a widely supported format for data interchange. This is especially useful in web APIs and systems where human readability is less important.
• Use YAML for configuration files where readability is essential. It also supports complex structures. This is especially useful in DevOps and infrastructure as code (IaC) scenarios.
• Use TOML when you want a balance between readability and simplicity. It is especially useful for project configuration files in environments like Python and Rust.

Here are examples of how to read data from JSON, YAML, and TOML files in Python.

1. Reading JSON Data in Python

You can use the built-in json module to read JSON data.

Example JSON File (data.json):

{
  "name": "Example Project",
  "version": 1.0,
  "dependencies": {
    "library1": "1.2.3",
    "library2": "4.5.6"
  },
  "is_active": true,
  "tags": ["example", "json", "config"]
}

Python Code to Read JSON:

import json

# Reading JSON data from a file
with open('data.json', 'r') as file:
    data = json.load(file)

# Accessing data
print(data['name'])         # Output: Example Project
print(data['dependencies']) # Output: {'library1': '1.2.3', 'library2': '4.5.6'}

2. Reading YAML Data in Python

To read YAML data, you need the PyYAML package, which you can install with pip install pyyaml.

Example YAML File (data.yaml):

name: Example Project
version: 1.0
dependencies:
  library1: "1.2.3"
  library2: "4.5.6"
is_active: true
tags:
  - example
  - yaml
  - config

Python Code to Read YAML:

import yaml

# Reading YAML data from a file
with open('data.yaml', 'r') as file:
    data = yaml.safe_load(file)

# Accessing data
print(data['name'])         # Output: Example Project
print(data['dependencies']) # Output: {'library1': '1.2.3', 'library2': '4.5.6'}

3. Reading TOML Data in Python

To read TOML data, you need the toml package, which you can install with pip install toml.

Example TOML File (data.toml):

name = "Example Project"
version = 1.0
is_active = true

[dependencies]
library1 = "1.2.3"
library2 = "4.5.6"

tags = ["example", "toml", "config"]

Python Code to Read TOML:

import toml

# Reading TOML data from a file
with open('data.toml', 'r') as file:
    data = toml.load(file)

# Accessing data
print(data['name'])         # Output: Example Project
print(data['dependencies']) # Output: {'library1': '1.2.3', 'library2': '4.5.6'}

Summary:

• JSON: Use the json module, which is built into Python.
• YAML: Use the PyYAML package (yaml module).
• TOML: Use the toml package (toml module).