Engineering

JSON vs YAML vs JSONL: Which Format Should You Use?

JSON vs YAML vs JSONL: JSON for APIs, YAML for config people edit, JSONL for logs and batch jobs. With real parser output and the Norway bug.

SA
Samer Alsayegh
Founder
Published
9 min read
Key takeaways

Use JSON for APIs, YAML for config people edit, and JSONL for logs, exports, and batch jobs. Quote YAML values that must stay strings, or NO can turn into false.

JSON, YAML, and JSONL all store the same kind of data: objects, lists, strings, numbers, and booleans. The difference is who they're built for. JSON is a strict format for programs to swap. YAML is a looser format for people to edit, with comments and indentation. JSONL is JSON with one record per line, built for logs, streams, and batch jobs.

So the short answer is: JSON for APIs, YAML for config people edit, and JSONL for big lists you process one row at a time. The rest of this post shows where each one breaks, with parser output we ran ourselves. If you're shaping content for an API, our content modeling hub covers the layer above this.

What is JSON?

JSON is a text format for structured data. RFC 8259 defines it. A JSON text is one value: an object, an array, a string, a number, true, false, or null.

The grammar is tiny on purpose. Keys need double quotes. There are no comments. Trailing commas are an error. That strictness is why every language can read it with the same result.

{
  "title": "Hello",
  "tags": ["intro", "news"],
  "published": true
}

JSON is the default for web APIs and webhooks. It's also what most CMS APIs return. The downside is that people find it tedious to edit by hand. If you've wished you could leave a note in a JSON file, can JSON have comments? covers the options.

What is YAML?

YAML is a data format built for people to read and write. It uses indentation for nesting and # for comments. The current spec is YAML 1.2.2, released in October 2021.

The same data in YAML looks like this:

# shown on the home page
title: Hello
tags:
  - intro
  - news
published: true

YAML 1.2's main goal was to make YAML a strict superset of JSON. In theory, any JSON file is valid YAML 1.2. YAML also adds features JSON lacks. Anchors and aliases let you reuse a block. Multi-line strings are easy to write.

That's why YAML shows up in config: CI pipelines, Kubernetes files, Docker Compose, and Markdown front matter. People edit those files by hand, and comments help.

What is JSONL?

JSONL, also called JSON Lines, is a text file where each line is one JSON value. The rules at jsonlines.org are short:

  • The file is UTF-8, with no byte order mark.
  • Each line is a valid JSON value. A blank line is not.
  • Lines end with \n. A \r\n ending is also fine.
  • A newline after the last line is recommended.
  • The file extension is .jsonl.

Here's the same post plus a second one:

{"title":"Hello","tags":["intro","news"],"published":true}
{"title":"Second post","tags":["news"],"published":false}

The point is that you can read one line at a time. You never load the whole file into memory. You can append a record without rewriting the file. And if one line is broken, the others still parse.

The suggested media type is application/jsonl, but it isn't a registered standard yet. You'll also see the name NDJSON for the same idea.

JSON vs YAML vs JSONL: side by side

JSONYAMLJSONL
Built forProgramsPeopleStreams and batches
CommentsNoYes, with #No
NestingBracesIndentationBraces, per line
One file holdsOne valueOne or more docsMany values
Stream line by lineNoNoYes
Parsed by default in JSJSON.parseNeeds a libraryJSON.parse per line
Typical useAPIs, webhooksConfig, front matterLogs, exports, LLM batches

The table hides one big difference. JSON and JSONL types are explicit: a string has quotes, a number doesn't. YAML guesses types from bare text. That guess is where most YAML bugs come from.

Why does YAML turn NO into false?

This is the "Norway problem." In older YAML, the country code NO reads as the boolean false. We ran this file through two common parsers:

country: NO
port: 0755
version: 1.10
enabled: on

PyYAML 6.0.3 follows YAML 1.1. It returned:

{'country': False, 'port': 493, 'version': 1.1, 'enabled': True}

js-yaml 5.5.0 follows YAML 1.2. It returned:

{ country: 'NO', port: 755, version: 1.1, enabled: 'on' }

Four lines, four surprises. PyYAML read NO as false and on as true. It read 0755 as an octal number, which is 493. Both parsers read 1.10 as the number 1.1, so the trailing zero is gone. A version string just changed meaning.

YAML 1.2 fixed part of this. It dropped many of the old implicit types. In its core schema, only true and false (in three casings) are booleans. But many tools still use YAML 1.1 parsers. You can't assume which one reads your file.

The fix is simple: quote any value that should stay a string. Write country: "NO" and version: "1.10". JSON never has this problem, because a string always has quotes.

When should you use JSONL?

Use JSONL when you have many records of the same kind and you want to handle them one at a time. Common cases:

  • Logs. Each event is one line. You append, and tools like grep and tail still work.
  • Data exports. A dump of a million rows streams out and back in without one giant parse.
  • LLM batch jobs. OpenAI's Batch API takes a .jsonl file as input.

That last one is a good example of why the format exists. The OpenAI Batch API takes up to 50,000 requests per file, and the file can be up to 200 MB. Each line is one request with its own custom_id, so you can match each result to its input. One JSON array of 50,000 requests would be awkward to build and check. One line per request is easy.

Training and eval sets work the same way. One example per line makes it easy to shuffle, split, and count.

JSONL is for files a program reads. If the data goes into a prompt instead, the best format changes. Our TOON vs JSON token counts show which one costs the fewest tokens.

How do you convert JSON to JSONL?

If you have a JSON array, jq turns it into JSONL in one line:

jq -c '.[]' posts.json > posts.jsonl

The -c flag prints each item on one line. Going the other way, jq -s '.' posts.jsonl reads every line into one array.

In code, you write each record with JSON.stringify and add a newline. Here's a script that exports every published blog post from Draftbase's delivery API into a JSONL file. It follows the cursor until there are no more pages:

import { createWriteStream } from 'node:fs';

const out = createWriteStream('posts.jsonl');
let after = null;

do {
  const url = new URL('https://api.draftbase.co/delivery/entries');
  url.searchParams.set('templateId', 'blogPost');
  url.searchParams.set('limit', '100');
  if (after) url.searchParams.set('after', after);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.DRAFTBASE_KEY}` },
  });
  if (!res.ok) throw new Error(`Delivery API returned ${res.status}`);

  const { entries, nextCursor } = await res.json();
  for (const entry of entries) out.write(JSON.stringify(entry) + '\n');
  after = nextCursor;
} while (after);

out.end();

The API returns JSON pages of up to 100 entries with a nextCursor. The script turns them into one line per entry. From there, the file is ready for a batch job, a search index, or a backup. The Draftbase content API post covers the endpoints in more detail.

Converting YAML to JSON is also one step. Parse it with a YAML library, then JSON.stringify the result. Just check the types after the parse, for the reasons in the Norway section above.

What breaks in production?

Each format has its own common failure.

JSON: one bad byte kills the whole file. A truncated download or a stray comma fails the full parse. For large files, that also means you load everything into memory before you find out.

YAML: indentation and types. YAML doesn't allow tabs for indentation. A file that looks fine in one editor can fail in another. And as shown above, bare values like NO, on, and 0755 may not be what you typed.

JSONL: blank lines and pretty printing. A blank line is not valid JSONL. Some parsers skip it and some throw. A record printed across several lines breaks the format too. Always write records with JSON.stringify(value) and no spacing argument.

JSONL: missing final newline. If a writer crashes mid-line, the last line is cut off. A reader should skip or flag a last line that doesn't parse, not fail the whole job.

All three: encoding. JSON and JSONL should be UTF-8. If a tool on Windows saves with a byte order mark, some parsers choke on the first character.

Which format should a CMS use?

Each format has a job in a content stack. They don't compete.

A CMS API should return JSON. Every client reads it, and the types are clear. That's what Draftbase's delivery API does. Rich text fields come back as MDX strings inside that JSON, so you don't walk a nested node tree to render a post.

Bulk exports and imports suit JSONL, since you can stream them. Front matter in Markdown files is usually YAML. That's fine for files a person edits, but it's where the Norway bug shows up in content. A post with title: Yes or country: NO in its front matter can turn into a boolean on you.

A CMS with typed fields skips that guesswork. In Draftbase, each template field has a declared type: text, number, boolean, date, and so on. A NO in a text field stays the string NO. If you're moving from another platform, draftbase migrate reads a Contentful export JSON file or a WordPress site URL directly. The structured content for LLMs guide covers why typed fields also help when an AI agent reads your content.

Conclusion

JSON vs YAML vs JSONL comes down to who reads the file. Use JSON for APIs and anything a program writes. Use YAML for config that people edit and comment, and quote any value that should stay a string. Use JSONL for logs, exports, and batch jobs where you handle one record at a time.

If your content lives in a CMS, let the CMS hold the types and hand you plain JSON. Draftbase templates give every field a declared type, and the delivery API returns JSON you can turn into JSONL with one loop. The Hobby plan is free. See pricing to start.

Ship content that's built to be found

Draftbase generates schema, structured data, and a fast MDX editor for every post.

Frequently asked questions

What is the difference between JSON and JSONL?

A JSON file holds one value. A JSONL file holds one JSON value per line, so you can read, append, and stream records one at a time.

Is YAML a superset of JSON?

Yes, in YAML 1.2. Making YAML a strict superset of JSON was the main goal of 1.2. Older YAML 1.1 parsers can still read some JSON values differently.

Why does YAML read NO as false?

YAML 1.1 treats bare yes, no, on, and off as booleans. PyYAML 6.0.3 read country: NO as False. Quote the value to keep it a string.

What is JSONL used for?

Logs, data exports, and LLM batch jobs. OpenAI's Batch API takes a .jsonl file with up to 50,000 requests, one request per line.

Is JSONL the same as NDJSON?

Yes, in practice. Both names describe one JSON value per line, split by newline characters.

SA
Samer Alsayegh
Founder at Draftbase

Samer is a software engineer and entrepreneur, founder of Draftbase and Ezi Home Services, building technology that simplifies home services. Passionate about software, APIs, automation, and creating products that solve real-world problems.

jsonyamljsonlapi-design

Related posts