DEV Community: UtiliStudio Team

JSON vs YAML vs TOML: which format should you use?

UtiliStudio Team — Sat, 31 Oct 2026 17:08:46 +0000

Originally published on UtiliStudio

The same configuration written three ways, with a clear comparison of readability, strictness, comments, and common pitfalls, so you can pick the right format for each job.

The short answer

JSON for data exchanged between programs: API requests and responses, stored documents, and anything generated by code.
YAML for configuration that people read and edit often, especially in ecosystems that already use it, such as Kubernetes, Docker Compose, GitHub Actions, and Ansible.
TOML for application and tool configuration with a clear, flat structure, such as Rust Cargo.toml and Python pyproject.toml.

All three describe the same building blocks: maps of keys to values, lists, strings, numbers, and booleans. The differences are in syntax, strictness, and how much the format tries to guess for you.

The same configuration in three formats

Here is a small service configuration written in each format. The data is identical; only the notation changes.

JSON

{
  "service": "orders",
  "port": 8080,
  "debug": false,
  "database": {
    "host": "db.internal",
    "pool_size": 10
  },
  "allowed_origins": ["https://app.example.com", "https://admin.example.com"]
}

YAML

service: orders
port: 8080
debug: false
database:
  host: db.internal
  pool_size: 10
allowed_origins:
  - https://app.example.com
  - https://admin.example.com

TOML

service = "orders"
port = 8080
debug = false
allowed_origins = ["https://app.example.com", "https://admin.example.com"]

[database]
host = "db.internal"
pool_size = 10

Side-by-side comparison

	JSON	YAML	TOML
Comments	No	Yes (`#`)	Yes (`#`)
Structure from	Braces and brackets	Indentation	Sections and dotted keys
Strings need quotes	Always	Usually not	Yes
Type guessing	None	Aggressive	Minimal
Deep nesting	Fine	Fine	Awkward
Dates and times	Strings only	Some parsers convert them	First-class type
Typical use	APIs, data storage	DevOps configuration	Tool and package configuration

JSON: strict and universal

JSON is the most widely supported of the three. Every mainstream language can parse and generate it without extra dependencies, and its grammar is small enough that two parsers almost always agree on what a document means. That predictability is exactly why it dominates APIs.

The trade-off is that JSON is unforgiving for people. There are no comments, keys must be quoted, and a single trailing comma breaks the whole file. Long configuration files in JSON tend to accumulate small syntax errors when edited by hand, which is why many tools that use JSON for configuration quietly accept a commented variant instead.

YAML: readable, but it guesses

YAML is designed to be pleasant to read and write. Indentation shows structure, most strings need no quotes, and comments are supported. Since YAML 1.2, any valid JSON document is also valid YAML, so you can mix styles when convenient.

The price of that convenience is implicit typing. YAML decides whether an unquoted value is a string, number, boolean, or null, and the guesses are not always what you meant. Many tools still use YAML 1.1 rules, where yes, no, on, and off become booleans, so the country code NO for Norway turns into false. Version numbers like 1.10 become the number 1.1, and long numeric IDs can lose precision.

Indentation errors are the other common problem. Tabs are not allowed for indentation, and a key indented one level too deep or too shallow silently moves to a different parent instead of causing an error. Quoting any value that must stay a string, and converting suspicious files to JSON to see their real structure, prevents most YAML surprises.

TOML: explicit and flat

TOML, short for Tom’s Obvious Minimal Language, aims to be easy to read like YAML but unambiguous like JSON. Strings are always quoted, booleans are only true and false, and dates and times are a real data type rather than strings that a parser might or might not convert.

TOML organizes data with [section] headers and dotted keys, which works beautifully for configuration that is a few levels deep. It becomes awkward for deeply nested or highly dynamic data, such as large lists of objects with their own nested lists, where JSON or YAML stay more readable. Tooling support is also narrower than for JSON and YAML, although every major language has a solid parser.

How to choose

Is the file written by a program and read by another program? Use JSON.
Does your platform already define a format? Follow it. Kubernetes expects YAML, Cargo expects TOML, and fighting the ecosystem rarely pays off.
Do people edit the file by hand and need comments? Prefer YAML or TOML over plain JSON.
Is the structure deep, repetitive, or generated? JSON or YAML handle it better than TOML.
Do subtle typing mistakes carry real risk? TOML’s explicit types, or JSON validated with a JSON Schema, are the safest choices.

Validating each format

Syntax checks only tell you that a file can be parsed. To catch valid-but-wrong configuration, such as a missing required key or a port written as a string, describe the expected structure with a JSON Schema. Despite the name, a JSON Schema validates the parsed data, so it works for YAML and TOML files too once they are loaded.

Editors make this practical. The YAML extension for VS Code can apply schemas to files like Kubernetes manifests and GitHub Actions workflows, and TOML tooling such as Taplo supports schemas as well. In continuous integration, parse the file, validate it against the schema, and fail the build on errors, so broken configuration never reaches a running system.

Converting between formats

Because the data models overlap, converting is usually straightforward, with a few caveats. Comments are lost when converting YAML or TOML to JSON, because JSON cannot represent them. YAML anchors and aliases are expanded, so the JSON output can be larger than the source. TOML dates become strings in JSON. And YAML values that were guessed into booleans or numbers stay that way, so check the converted output for strings that changed type.

A practical workflow for teams is to keep human-edited configuration in YAML or TOML, validate it, and convert it to JSON at build time for programs that need JSON. The YAML to JSON Converter handles the YAML and JSON half of that workflow in your browser and shows syntax errors as you type.

Try it in the browser: YAML/JSON Converter, JSON Formatter, JSON Schema Validator on UtiliStudio.

Related guides:

By the UtiliStudio Team. This article first appeared at utilistudio.com/guides/json-vs-yaml-vs-toml.

Use a ratio of 100:42 for best results.

published_at: 2026-10-31 16:49 +0000

UUID v4 vs v7: which one should you use?

UtiliStudio Team — Sun, 25 Oct 2026 17:02:35 +0000

Originally published on UtiliStudio.

Version 4 is random; version 7 starts with a timestamp so values sort by creation time. Here is how they differ and how to pick the right one for your system.

The short answer

Use UUID version 7 for new database primary keys and anything you want to sort by creation time. Use UUID version 4 when the identifier is exposed publicly and must not reveal when it was created, or when your platform does not support version 7 yet. Both are 128-bit values in the same familiar format, so they fit the same columns and APIs.

Primary keys in a relational database: version 7.
Event, log, or message IDs that should sort chronologically: version 7.
Public IDs in URLs where creation time is sensitive: version 4.
Correlation IDs, file names, and general unique labels: either works; version 4 is the most widely supported.

What is inside a UUID

A UUID (Universally Unique Identifier) is a 128-bit number written as 32 hexadecimal digits in five groups, in the pattern 8-4-4-4-12. The current standard is RFC 9562, published in 2024, which replaced RFC 4122 and formally added versions 6, 7, and 8.

Two small fields tell you how a UUID was made. The version is the first digit of the third group, and the variant is encoded in the first digit of the fourth group. For standard UUIDs that variant digit is always 8, 9, a, or b.

Where the version and variant live

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
              |    |
              |    +-- variant: 8, 9, a, or b
              +------- version: 4 or 7

Everything else depends on the version. In version 4 almost all of the remaining bits are random. In version 7 the first 48 bits hold a timestamp and the rest are random.

How UUID v4 works

A version 4 UUID fixes six bits for the version and variant and fills the other 122 bits with random data. There is no timestamp, no machine identifier, and no counter, so the value says nothing about when or where it was generated.

That makes version 4 simple and private, but also unordered. Two IDs created a millisecond apart can land at opposite ends of a sorted list. The quality of a version 4 UUID depends entirely on the random number generator, which is why it should come from a cryptographically secure source such as the Web Crypto API, crypto.randomUUID() in JavaScript, or uuid.uuid4() in Python, never from a hand-written function built on Math.random().

How UUID v7 works

A version 7 UUID begins with a 48-bit Unix timestamp in milliseconds, followed by the version, a block of random or counter bits, the variant, and more random bits.

Bits	Field	Purpose
0–47	unix_ts_ms	Milliseconds since 1 January 1970 UTC
48–51	version	Always 7
52–63	rand_a	Random bits, or a counter for ordering within one millisecond
64–65	variant	Marks the standard layout
66–127	rand_b	Random bits

Because the timestamp comes first and is stored most-significant byte first, version 7 values generated later sort after values generated earlier, both as raw bytes and as lowercase strings. Generators may use part of the random field as a counter so that IDs created within the same millisecond on one machine still come out in order.

You can read the creation time straight out of a version 7 UUID: the first 12 hexadecimal digits are the timestamp.

Extract the creation time from a version 7 UUID

function uuidV7Time(uuid) {
  const hex = uuid.replace(/-/g, '').slice(0, 12);
  return new Date(parseInt(hex, 16));
}

uuidV7Time('0192b3a4-5c6d-7e8f-9a0b-1c2d3e4f5a6b');
// -> a Date in October 2024

Side-by-side comparison

Property	Version 4	Version 7
Ordering	Random, no order	Sorts by creation time
Reveals creation time	No	Yes, to the millisecond
Random bits	122	About 74
Database index locality	Poor: inserts scatter across the index	Good: inserts append near the end
Collision risk in practice	Negligible	Negligible
Library support	Universal	Growing quickly; check your stack

Version 7 has fewer random bits, but collisions are still not a practical concern: the random part only has to be unique among IDs created in the same millisecond, and 74 random bits is a very large space for that.

Why ordering matters for databases

Most relational databases keep primary keys in a B-tree index. When keys arrive in roughly increasing order, each new row is added near the right-hand edge of the index, the same few pages stay in memory, and pages fill up neatly.

Random version 4 keys behave very differently. Each insert lands somewhere unpredictable, so the database must load scattered index pages from disk, split pages that are already full, and leave fragmented pages behind. On small tables you will not notice. On tables with millions of rows and steady write traffic, this shows up as slower inserts, a larger index, and more pressure on the buffer cache.

The effect is strongest where the table itself is stored in primary-key order, such as MySQL InnoDB and SQL Server clustered indexes, but it applies to any B-tree index on a UUID column, including in PostgreSQL. Version 7 keys give you insert behavior much closer to an auto-increment integer while keeping the ability to generate IDs anywhere, without a central sequence.

Store UUIDs in a native column type, such as uuid in PostgreSQL, BINARY(16) in MySQL, or uniqueidentifier in SQL Server, rather than as 36-character strings. The binary form is less than half the size and compares faster.

Privacy and security considerations

The timestamp that makes version 7 useful is also visible to anyone who sees the ID. If your URLs contain version 7 UUIDs, a visitor can tell exactly when an account, order, or document was created, and can compare the creation order of two records. For many systems that is harmless; for some, such as user accounts or medical records, it is information you may not want to publish.

A common pattern is to use version 7 internally as the primary key and expose a separate version 4 UUID, or another opaque token, in public URLs. That keeps the database fast without leaking timing information.

Whichever version you choose, remember that a UUID is an identifier, not a secret. Being hard to guess does not make it safe as an access token. Always check permissions on the server, even when IDs are random.

A checklist for choosing

Will the ID be a primary key or indexed column in a large, write-heavy table? Prefer version 7.
Do you need to sort or paginate by creation time without an extra timestamp column? Prefer version 7.
Will the ID appear in public URLs or API responses where creation time is sensitive? Prefer version 4 for the public value.
Does every language, database, and library in your stack support version 7? If not, use version 4 or generate version 7 with a well-maintained library.
Are you generating IDs on devices with unreliable clocks? Version 7 still works, but order will only be as good as the clocks; version 4 avoids the question entirely.

Switching from v4 to v7

Because both versions share the same 128-bit format, you can start generating version 7 IDs for new rows without changing column types or API contracts. Existing version 4 values remain valid and unique.

Two details are worth planning for. First, old version 4 rows will not sort by creation time, so if you start relying on ID order for pagination, keep a separate creation timestamp for older data. Second, make sure every service that generates IDs uses the same version, otherwise you lose the index locality you wanted.

Quick answers

Is UUID v7 an official standard? Yes. Version 7 is defined in RFC 9562, published by the IETF in May 2024.

How can I tell which version a UUID is? Look at the first character of the third group. In 550e8400-e29b-41d4-a716-446655440000 it is 4, so that value is version 4.

Are version 7 UUIDs unique across machines? Yes. Different machines generating IDs in the same millisecond are separated by the random bits, just as with version 4.

Should I use version 1 or version 6 instead? For new systems, version 7 is the recommended time-ordered option. Version 1 sorts poorly and historically embedded a MAC address; version 6 exists mainly for compatibility with existing version 1 data.

Try it in the browser: UUID Generator, Developer Utilities on UtiliStudio.

Related guides:

How to generate a UUID in JavaScript, Python, Java, and SQL

By the UtiliStudio Team. This article first appeared at utilistudio.com/guides/uuid-v4-vs-v7.

DEV Community: UtiliStudio Team

JSON vs YAML vs TOML: which format should you use?

The short answer

The same configuration in three formats

Side-by-side comparison

JSON: strict and universal

YAML: readable, but it guesses

TOML: explicit and flat

How to choose

Validating each format

Converting between formats

Use a ratio of 100:42 for best results.

published_at: 2026-10-31 16:49 +0000

UUID v4 vs v7: which one should you use?

The short answer

What is inside a UUID

How UUID v4 works

How UUID v7 works

Side-by-side comparison

Why ordering matters for databases

Privacy and security considerations

A checklist for choosing

Switching from v4 to v7

Quick answers

Use a ratio of 100:42 for best results.

published_at: 2026-10-25 16:26 +0000