STXT frente a JSON

JSON es un formato de serialización para máquinas, y STXT un lenguaje para personas. Solo se solapan en un punto: un fichero que una persona escribe y mantiene a mano.

El mismo contenido, dos veces

La ficha de un artículo en JSON:

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

Y en STXT:

# La ficha de un artículo
Article: Modern Software Architecture
	Published: 2026-09-01
	Tag: software
	Tag: architecture
	Summary >>
		A survey of monoliths and microservices.
		Second line, with "quotes".

La gramática de JSON está pensada para que un programa la escriba y otro la lea:

	JSON	STXT
Estructura	Llaves, corchetes, comillas y comas. Una coma tras el último elemento es un error	La indentación, y un nombre que termina en `:`
Comentarios	No tiene	Líneas que empiezan por `#`
Texto de varias líneas	Una sola línea, con `\n` y comillas escapadas	Un nodo block `>>`, con el texto literal
Esquemas	JSON Schema, una especificación aparte	Forman parte del lenguaje, y son opcionales

JSON Schema frente a una plantilla

La estructura del artículo, en 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
}

Y la misma estructura como plantilla STXT. Se lee como el documento que describe:

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

El artículo, con namespace:

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

Las diferencias van en las dos direcciones:

Modelo cerrado: en STXT un hijo no declarado es un error, sin necesidad de additionalProperties: false en cada nivel.
Tipos: DATE se comprueba siempre. En JSON Schema, format es por defecto una anotación, y un validador puede no comprobarla.
JSON Schema expresa más: patrones, rangos numéricos, condicionales y composición (oneOf, $ref). Los esquemas de STXT lo dejan fuera a propósito (STXT-SCHEMA-SPEC §11).

De STXT a JSON

STXT adopta JSON como representación de su árbol. STXT-TREE-SPEC define el JSON canónico de todo documento válido, idéntico en todas las implementaciones. El comando stxt describe lo imprime, y las tres bibliotecas lo exponen en su API.

El artículo anterior, en esa forma:

[
	{
		"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."]
			}
		]
	}
]

Es más largo que el JSON escrito a mano porque es el árbol completo: el nombre tal como se escribió, su forma canónica y el namespace de cada nodo. Cualquier programa que lea JSON lo puede usar, sin un parser de STXT.