STXT vs JSON

JSON is a serialization format for machines, and STXT a language for people. They overlap at a single point: a file that a person writes and maintains by hand.

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:

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

The JSON grammar is designed for one program to write and another to read:

	JSON	STXT
Structure	Braces, brackets, quotes and commas. A comma after the last element is an error	The indentation, and a name that ends in `:`
Comments	None	Lines that start with `#`
Multi-line text	A single line, with `\n` and escaped quotes	A block node `>>`, with the literal text
Schemas	JSON Schema, a separate specification	Part of the language, and optional

JSON Schema vs a template

The structure of the article, in JSON Schema:

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"article": {
			"type": "object",
			"properties": {
				"title": { "type": "string" },
				"published": { "type": "string", "format": "date" },
				"tags": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
				"summary": { "type": "string" }
			},
			"required": ["title", "published", "tags"],
			"additionalProperties": false
		}
	},
	"required": ["article"],
	"additionalProperties": false
}

And the same structure as an STXT template. It reads like the document it describes:

Template (@stxt.template): com.example.articles
	Structure >>
		Article (com.example.articles):
			Published: (1) DATE
			Tag: (+)
			Summary: (?) TEXT

The article, with a namespace:

Article (com.example.articles): Modern Software Architecture
	Published: 2026-09-01
	Tag: software
	Tag: architecture
	Summary >>
		A survey of monoliths and microservices.

The differences go in both directions:

Closed model: in STXT an undeclared child is an error, with no need for additionalProperties: false at every level.
Types: DATE is always checked. In JSON Schema, format is by default an annotation, and a validator may not check it.
JSON Schema expresses more: patterns, numeric ranges, conditionals and composition (oneOf, $ref). STXT schemas leave that out on purpose (STXT-SCHEMA-SPEC §11).

From STXT to JSON

STXT adopts JSON as the representation of its tree. STXT-TREE-SPEC defines the canonical JSON of every valid document, identical across implementations. The stxt describe command prints it, and the three libraries expose it in their API.

The previous article, in that form:

[
	{
		"name": "Article",
		"canonicalName": "article",
		"namespace": "com.example.articles",
		"form": "inline",
		"value": "Modern Software Architecture",
		"children": [
			{
				"name": "Published",
				"canonicalName": "published",
				"namespace": "com.example.articles",
				"form": "inline",
				"value": "2026-09-01",
				"children": []
			},
			{
				"name": "Tag",
				"canonicalName": "tag",
				"namespace": "com.example.articles",
				"form": "inline",
				"value": "software",
				"children": []
			},
			{
				"name": "Tag",
				"canonicalName": "tag",
				"namespace": "com.example.articles",
				"form": "inline",
				"value": "architecture",
				"children": []
			},
			{
				"name": "Summary",
				"canonicalName": "summary",
				"namespace": "com.example.articles",
				"form": "block",
				"lines": ["A survey of monoliths and microservices."]
			}
		]
	}
]

It is longer than the hand-written JSON because it is the complete tree: the name as written, its canonical form and the namespace of every node. Any program that reads JSON can use it, without an STXT parser.