STXT vs JSON

JSON does its job with a minimal grammar, one data model and parsers everywhere; it is the lingua franca of APIs. The comparison only makes sense at the point where the two overlap — a file that a person has to write and maintain by hand — because that is the job JSON never promised to do.

The same content, twice

An article record in JSON:

{
	"article": {
		"title": "Modern Software Architecture",
		"published": "2026-09-01",
		"tags": ["software", "architecture"],
		"summary": "A survey of monoliths and microservices.\nSecond line, with \"quotes\"."
	}
}

And in STXT:

Article: Modern Software Architecture
	Published: 2026-09-01
	Tag: software
	Tag: architecture
	Summary >>
		A survey of monoliths and microservices.
		Second line, with "quotes".

What separates them when writing by hand

Each difference below is a deliberate JSON decision that serves serialization, and gets in the way of authoring:

• Everything is quoted and delimited. Keys and strings between quotes, objects between braces, elements between commas — and the comma after the last element is a syntax error. In STXT, structure is indentation and a name ends at :.
• No comments. The exclusion is intentional in JSON; in a hand-maintained file it is the first thing missed. STXT has # comments, and tools preserve them when formatting.
• A text is one line. Line breaks are written \n, quotes are escaped, and a paragraph becomes a single escaped string. In STXT a >> block holds the text literally, as long as it needs to be.
• No schema in the language. JSON Schema exists, but it is a separate specification, written in JSON itself, with its own vocabulary of composition and references. The STXT template layer is part of the language and reads like the document it describes.

From STXT to JSON

STXT does not compete with JSON as an interchange format: it adopts it. STXT chose JSON as the representation of its logical tree, because representing a data structure for programs to consume is exactly the job JSON is designed for. STXT-TREE-SPEC defines that canonical representation for every valid document — an array of root nodes with name, canonicalName, namespace, and value plus children, or lines — identical in every implementation. The command stxt describe file.stxt prints it, and the three libraries expose it from their API, so anything downstream that expects JSON keeps working. The source stays readable; the serialization stays mechanical.

When to use which

Use JSON for what machines exchange: API payloads, serialized state, generated artifacts nobody edits. Its ubiquity is the feature, and STXT does not try to replace it there.

Write STXT when a person is on either end of the file: documents, configuration, corporate records, content that feeds a pipeline — and let the tools emit the canonical tree where JSON is expected. The AI and LLMs use case shows that route end to end: readable generated documents, validated, consumed as JSON.

To see the language, start with the tutorial or open the examples in the playground; the one-paragraph version of this page is in the FAQ.