STXT Tutorial

Este tutorial enseña a leer y escribir documentos STXT desde cero, y termina con un documento validado contra su propia plantilla. No requiere conocimientos previos: basta con un editor de texto.

1. Un documento STXT en diez líneas

Un documento STXT es un árbol de nodos con nombre. Cada línea es un nodo, y la indentación dice de quién es hijo:

Book:
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Published: 2025-10-01
	Summary >>
		Este libro ofrece una visión práctica de patrones y buenas prácticas
		para diseñar sistemas distribuidos y escalables.

Con este ejemplo ya se ve casi todo el lenguaje:

Title: Arquitectura… es un nodo inline: un nombre, dos puntos y un valor en la misma línea.
Authors: es un nodo inline sin valor, que existe para agrupar a sus hijos.
Author aparece dos veces: un nombre puede repetirse tantas veces como haga falta. Así se escriben las listas.
Summary >> es un bloque de texto: todo lo indentado debajo es texto literal, tal como está escrito.
No hay comillas, ni llaves, ni etiquetas de cierre. La indentación es la estructura.

El resto del tutorial desarrolla cada uno de estos puntos. El documento completo del que sale este ejemplo está en tutorial/book-raw.stxt del repositorio.

Referencia: STXT-SPEC §1.

2. Antes de empezar

Para seguir el tutorial basta con un editor de texto. Dos opciones facilitan el trabajo:

El playground, en el navegador y sin instalar nada. Todos los ejemplos de esta página tienen un botón Abrir en el playground, que los carga en el editor con la validación activa.
Visual Studio Code con la extensión oficial stxt-lang.stxt (code --install-extension stxt-lang.stxt): coloreado, errores en el editor, autocompletado a partir de la plantilla e ir a la definición.

El ejemplo del libro se reutiliza en El entorno de trabajo, que enseña a organizar un proyecto y validarlo desde el terminal; la lista completa de herramientas está en Herramientas.

3. Nodos inline y bloques de texto

Todo nodo empieza por su nombre, seguido de un separador. El separador decide cuál de las dos formas tiene el nodo:

Nombre: valor — nodo inline. El valor es lo que hay tras los dos puntos, hasta el final de la línea; puede estar vacío. Un nodo inline puede tener hijos: las líneas indentadas debajo.
Nombre >> — bloque de texto. No lleva nada tras el >>; su contenido son las líneas indentadas debajo, y es texto literal: :, # y >> no significan nada dentro, y no hay secuencias de escape.

Chapter: Introducción a la arquitectura
	Pages: 24
	Content >>
		En este capítulo presentamos conceptos básicos:
		monolitos, microservicios y criterios de diseño.

Chapter es inline con valor y con dos hijos; Pages es inline con valor y sin hijos; Content es un bloque. Un bloque nunca tiene hijos: si un nodo necesita a la vez estructura y un texto largo, el texto va en un hijo bloque, como Content dentro de Chapter. Esa combinación —un nodo inline que agrupa valores cortos y bloques— es la forma habitual de un documento STXT.

Un valor puede contener cualquier carácter, dos puntos incluidos: en Ruta: C:\Users\ana, el valor es C:\Users\ana. El primer : de la línea es el separador; el resto es valor.

Referencia: STXT-SPEC §4 (el nodo), §5 (nodos inline) y §6 (bloques de texto).

4. La indentación es la estructura

El nivel de una línea —cuántas unidades de indentación lleva— es lo único que decide de qué nodo es hija. No hay otra marca de jerarquía.

Las reglas son cuatro:

Un tabulador es un nivel.
Cuatro espacios son un nivel. Siempre múltiplos de cuatro: dos espacios no son medio nivel, son un error.
No se mezclan en una misma línea. O solo tabuladores, o solo espacios.
Los niveles son consecutivos. Del nivel 1 no se salta al 3.

En este ejemplo, . representa un espacio y |--> un tabulador:

Book:
|-->Title: correcto, un tabulador = nivel 1
....ISBN: correcto, cuatro espacios = nivel 1
..Publisher: ERROR, dos espacios no son un nivel
.|-->Summary: ERROR, espacio y tabulador en la misma línea

Líneas distintas del mismo documento pueden usar estilos distintos, porque lo que se compara es el nivel, no la columna. No es un error, pero por legibilidad conviene elegir un estilo y mantenerlo; stxt format --tabs o --spaces lo unifican.

Estas reglas son deliberadamente estrictas. Una línea que mezcla tabuladores y espacios se ve distinta según el ancho de tabulador de cada editor, y la jerarquía dejaría de ser evidente al leerla; y que el ancho de nivel sea fijo permite calcular el nivel de una línea mirando solo esa línea. Los errores tienen código propio: INDENTATION_MIXED, INDENTATION_SPACES_NOT_VALID e INDENTATION_LEVEL_NOT_VALID.

Referencia: STXT-SPEC §8 (indentación y jerarquía) y §8.3 (errores de nivel).

5. Dentro de un bloque de texto

Un bloque tiene un nivel de bloque: el del nodo >> más uno. Ese prefijo de indentación es lo único que el parser quita; todo lo que hay después de él es texto, y la sangría adicional forma parte del texto:

Summary >>
	Esta línea está en el nivel de bloque.
		Esta otra va más indentada, y esa sangría forma parte del texto.
	# Esto no es un comentario: es texto.
	Title: esto tampoco es un nodo.

El bloque termina en la primera línea no vacía cuya indentación sea menor o igual que la del nodo >>, sea un nodo o un comentario. Las líneas vacías no lo cierran: las que preceden a más texto forman parte del bloque como líneas vacías, se escriban sin nada o con la indentación del bloque; las que quedan al final se descartan al cerrarse el bloque, porque son separación visual del documento, no contenido.

Por eso un bloque sirve para cualquier contenido —un párrafo, un fragmento de código, un trozo de Markdown, un texto en otro formato— sin transformarlo ni escapar nada.

Referencia: STXT-SPEC §6.1 (reglas de los bloques) y §10.2 (líneas dentro de bloques).

6. Listas: todo son listas

STXT no tiene una sintaxis de lista porque no la necesita: los hijos de un nodo son una secuencia ordenada, y un mismo nombre puede repetirse. Una lista de elementos del mismo tipo es un nodo contenedor con el mismo hijo repetido:

Authors:
	Author: María Pérez
	Author: Juan García
	Author: Ana López

Y una secuencia de elementos distintos se escribe, sencillamente, en orden:

Book: Arquitectura de software moderna
	Chapter: Introducción
	Chapter: Comunicación entre servicios
	Appendix: Glosario
	Chapter: Despliegue

El árbol conserva el orden de aparición, así que una aplicación puede dar significado a la posición si lo necesita. Cuando más adelante se valide el documento, la plantilla dirá cuántas veces puede aparecer cada hijo; hasta entonces, cualquier número vale.

Referencia: STXT-SPEC §8.5 y la FAQ.

7. Los nombres de los nodos

Un nombre admite letras, dígitos y marcas combinantes de cualquier alfabeto —latino, griego, cirílico, árabe, devanagari, CJK…—, además de los separadores -, _ y espacio. No admite ningún otro signo: ni :, ni paréntesis, ni #. Debe contener al menos una letra o un dígito.

Para decidir si dos nodos son el mismo, STXT compara su nombre canónico, que se obtiene pasando el nombre a minúsculas, reduciendo cada secuencia de separadores a un solo - y quitando los guiones de los extremos. Los acentos y el alfabeto se conservan:

Un nombré con äcento: un-nombré-con-äcento
UN NOMBRÉ CON ÄCENTO: un-nombré-con-äcento
TAMaÑo número 2__ y 3: tamaño-número-2-y-3
Пример 1: пример-1
Nombre 日本語: nombre-日本語

Título, título y TITULO- son el mismo nodo.
Peña y Pena son nodos distintos, como lo son dos palabras distintas.

Es el mismo criterio que aplican los nombres de dominio internacionalizados: se puede escribir un documento en cualquier idioma sin que el lenguaje altere las palabras ni unifique dos nombres que para quien lee son distintos. La única excepción son los namespaces, que se verán en la sección 9: esos sí se limitan a ASCII.

Referencia: STXT-SPEC §4.2 (caracteres permitidos) y §4.3 (nombre canónico).

8. Comentarios

Una línea cuyo primer carácter, tras la indentación, es # es un comentario. El parser la descarta: no forma parte del árbol ni de los datos.

# Ficha de un libro
Book:
	# El título va primero
	Title: Arquitectura de software moderna
	ISBN: 978-84-123456-7-8

Tres cosas que conviene saber:

Los comentarios son de línea completa. No hay comentarios a final de línea: en Title: Mi libro # nota, el # y lo que le sigue son parte del valor.
La indentación de un comentario se valida como la de un nodo (estilo homogéneo y, como máximo, un nivel más que el último nodo), aunque no mueve la jerarquía. Lo natural es alinearlo con el nodo que describe.
Dentro de un bloque >> no hay comentarios: un # ahí es texto. Un comentario al nivel del nodo >> o menor cierra el bloque.

Referencia: STXT-SPEC §9 y §9.1.

9. Namespaces

Hasta aquí, el documento del libro es solo sintaxis: un árbol de nombres y textos que cualquier parser lee, pero del que nadie sabe qué significa. Un namespace le da identidad: dice a qué vocabulario pertenecen sus nodos, y es lo que permite validarlo más adelante.

El namespace se escribe entre paréntesis tras el nombre del nodo:

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Publisher: ACME Editorial
	Published: 2025-10-01
	Summary >>
		Este libro ofrece una visión práctica de patrones y buenas prácticas
		para diseñar sistemas distribuidos y escalables.
	Chapter: Introducción a la arquitectura
		Content >>
			En este capítulo presentamos conceptos básicos:
			monolitos, microservicios y criterios de diseño.
	Chapter: Comunicación entre servicios
		Content >>
			Se describen protocolos, mensajería y patrones de integración.

Es el mismo documento de la sección 1 (tutorial/book-ns.stxt), con una sola diferencia: Book declara el namespace com.acme.book. Y con eso basta, porque el namespace se hereda: Title, Authors, Author, Chapter, Content… todos los descendientes de Book pertenecen a com.acme.book sin escribirlo. Un hijo puede declarar otro namespace, y entonces sus propios descendientes heredan el nuevo.

Las reglas de forma son pocas: solo ASCII [a-z0-9] y puntos, al menos dos partes (a.b), y las mayúsculas se pasan a minúsculas (COM.ACME.BOOK es el mismo). La convención es usar un dominio propio al revés, como en Java, para que dos organizaciones no choquen.

Los namespaces que empiezan por @ son especiales: la rama @stxt.* está reservada al propio lenguaje, y en la sección siguiente aparecen dos de ellos, @stxt.template y @stxt.schema. Un namespace propio nunca empieza por @.

El lenguaje base no valida nada con el namespace: solo define cómo se escribe y cómo se hereda. Un documento con un namespace para el que no hay definición es un documento válido que, simplemente, no se puede validar.

Referencia: STXT-SPEC §7 (namespaces), §7.1 (restricción a ASCII) y §7.2 (herencia).

10. Validar con una plantilla

Una plantilla describe qué forma deben tener los documentos de un namespace: qué nodos existen, cuántas veces aparece cada uno y de qué tipo son sus valores. Es un documento STXT más, con namespace @stxt.template, y su bloque Structure >> tiene la misma forma que los documentos que describe:

Template (@stxt.template): com.acme.book
	Description >>
		Book: Plantilla para fichas de libros editoriales
	Structure >>
		Book:
			Title: (1)
			Authors: (1)
				Author: (+)
			ISBN: (1)
			Publisher: (?)
			Published: (?) DATE
			Summary: (?) TEXT
			Chapter: (+)
				Content: (?) TEXT

Se lee casi como el documento del libro. Lo que hay entre paréntesis es la cardinalidad —cuántas veces puede aparecer ese nodo dentro de su padre— y lo que va después, si hay algo, el tipo del valor:

Title: (1) — exactamente uno. Authors e ISBN, igual.
Author: (+) — uno o más.
Publisher: (?) — cero o uno.
Published: (?) DATE — opcional y, si aparece, una fecha AAAA-MM-DD.
Summary: (?) TEXT — opcional, y su valor es texto (inline o bloque).
Chapter: (+) con Content: (?) TEXT dentro — al menos un capítulo, cada uno con su texto opcional.

Lo que la plantilla no dice también importa: Book no admite ningún hijo que no esté en esta lista. Es el modelo de contenido cerrado: un nodo Pages dentro de Book no es un dato extra que se ignora, es un error.

10.1 Cardinalidades

Forma	Significado
`(1)`	Exactamente uno.
`(?)`	Cero o uno.
`(*)`	Cualquier número.
`(+)`	Uno o más.
`(n)`	Exactamente `n`.
`(n+)`	`n` o más.
`(n-)`	Hasta `n`.
`(min,max)`	Entre `min` y `max`.

10.2 Tipos

El tipo va tras la cardinalidad; si no se indica, es INLINE. Los más habituales:

Tipo	Forma del valor	Qué valida
`INLINE`	inline	Texto simple. Admite hijos. Es el tipo por defecto.
`GROUP`	sin valor	Solo estructura: el nodo agrupa, no lleva valor.
`TEXT`	inline o `>>`	Texto, sin interpretación.
`MARKDOWN`	inline o `>>`	Texto que quien lo consuma debe tratar como Markdown.
`NUMBER`	inline	Un número.
`DATE`	inline	Fecha `AAAA-MM-DD`, con calendario.
`ENUM`	inline	Uno de los valores de una lista: `ENUM [a, b, c]`.

Solo INLINE y GROUP admiten hijos. En cuanto un tipo valida un dato concreto —un número, una fecha, un texto—, ese nodo es un dato, y un dato es una hoja.

Referencia: STXT-TEMPLATE-SPEC §6 (el bloque Structure), §7 (cardinalidades), §8 (tipos) y §9 (ENUM); la lista completa de tipos, en STXT-SCHEMA-SPEC §9.

11. Qué detecta la validación

Con la plantilla anterior, el documento de la sección 9 valida: tiene todo lo obligatorio, nada que no esté declarado, y Published es una fecha. Este otro no:

# ERROR: Pages no está declarado, Published no es una fecha y falta ISBN
Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
	Pages: 320
	Published: 2025-13-01
	Chapter: Introducción

Un validador informa de tres cosas, cada una con su código y su línea: Pages no está declarado en Book (CHILD_NOT_DECLARED), 2025-13-01 no es una fecha válida (INVALID_VALUE) y falta ISBN, que era obligatorio (TOO_FEW_CHILDREN). Los códigos son los mismos en todas las herramientas; el texto del mensaje, no.

Esta es la diferencia entre un documento bien formado y un documento válido: el primero lo lee cualquier parser; el segundo, además, cumple el contrato de su namespace.

Referencia: STXT-SCHEMA-SPEC §6 (modelo cerrado) y §13 (errores de validación).

12. Lo mismo con un esquema

Un esquema (@stxt.schema) describe exactamente lo mismo que una plantilla, pero nodo a nodo y de forma explícita: cada Node con su tipo y la lista de sus Child con cardinalidades Min/Max. Es la forma canónica; toda plantilla se compila a un esquema equivalente, y validar con uno u otro da el mismo resultado.

Schema (@stxt.schema): com.acme.book
	Node: Book
		Type: GROUP
		Children:
			Child: Title
				Min: 1
				Max: 1
			Child: Authors
				Min: 1
				Max: 1
			Child: ISBN
				Min: 1
				Max: 1
			Child: Publisher
				Max: 1
			Child: Published
				Max: 1
			Child: Summary
				Max: 1
			Child: Chapter
				Min: 1
	Node: Authors
		Children:
			Child: Author
				Min: 1
	Node: Chapter
		Children:
			Child: Content
				Max: 1
	Node: Title
	Node: Author
	Node: ISBN
	Node: Publisher
	Node: Published
		Type: DATE
	Node: Summary
		Type: TEXT
	Node: Content
		Type: TEXT

La plantilla es más corta y se parece al documento; el esquema es más largo y más explícito, y es el lugar natural para las descripciones de cada nodo. Para un namespace solo puede haber una definición activa, plantilla o esquema; cuando hay varias en distintos niveles, gana la más cercana al documento.

Referencia: STXT-SCHEMA-SPEC §7 (Node), §8 (Children) y §10 (cardinalidades); la equivalencia con la plantilla, en STXT-TEMPLATE-SPEC §13; qué definición gana cuando hay varias, en STXT-DISCOVERY-SPEC §5.

13. El documento final

Un documento completo que valida tanto con la plantilla como con el esquema:

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Published: 2025-10-01
	Summary: Una introducción práctica a la arquitectura de sistemas modernos.
	Chapter: Introducción
		Content >>
			Conceptos básicos y objetivos del libro.

Summary va aquí inline y en la sección 9 iba como bloque: TEXT admite las dos formas, y el valor es el mismo texto. Publisher no aparece, y no hace falta: era (?).

Cómo se hace en un proyecto real —la plantilla en un directorio .stxt/, el documento al lado y stxt validate desde el terminal o los errores en el editor— lo enseña El entorno de trabajo.

14. Varios namespaces en un mismo documento

Nada obliga a que todo el documento pertenezca a un único namespace. Cualquier nodo puede declarar el suyo entre paréntesis, igual que lo declaró Book, y sus descendientes heredan el nuevo a partir de él. Cada namespace se valida contra su propia definición, así que un vocabulario se define una vez y se incorpora desde otros: unas reseñas, por ejemplo, que mañana podrían acompañar igual a cualquier otro producto.

En la plantilla que incorpora el vocabulario ajeno, el nodo externo se declara con su namespace y, como mucho, su cardinalidad: su forma no se describe ahí, sino en la plantilla de su propio namespace. El conjunto completo —el documento y las dos plantillas— cabe en un solo fichero:

Book (com.acme.book):
	Title: Arquitectura de software moderna
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Published: 2025-10-01
	Review (com.acme.reviews):
		Reviewer: Ana López
		Score: 9
		Comment >>
			Una guía clara y bien estructurada, con ejemplos
			que se siguen sin esfuerzo.
	Review (com.acme.reviews):
		Reviewer: Luis Martín
		Score: 8

Template (@stxt.template): com.acme.book
	Structure >>
		Book:
			Title: (1)
			Authors: (1)
				Author: (+)
			ISBN: (1)
			Published: (?) DATE
			Review (com.acme.reviews): (*)

Template (@stxt.template): com.acme.reviews
	Structure >>
		Review:
			Reviewer: (1)
			Score: (1) NUMBER
			Comment: (?) TEXT

La plantilla del libro —aquí reducida— añade una sola línea nueva, Review (com.acme.reviews): (*): un libro admite cualquier número de reseñas, y qué es una reseña lo dice la plantilla de com.acme.reviews. En el documento, cada Review declara su namespace, y Reviewer, Score y Comment lo heredan sin escribirlo: las reseñas se validan contra su plantilla, y el resto del libro contra la suya.

Un documento STXT puede tener varios nodos raíz, y este tiene tres: el libro y las dos plantillas. Van juntos a propósito: Abrir en el playground carga el bloque entero, y las dos plantillas validan el documento que las acompaña.

Referencia: STXT-SPEC §7.2 (herencia de namespaces), §8.5 (varios nodos raíz), STXT-TEMPLATE-SPEC §10 (namespaces dentro de Structure) y STXT-SCHEMA-SPEC §8 (hijos de otro namespace).

15. Dónde seguir

El entorno de trabajo: organizar un proyecto, instalar plantillas, validar desde el terminal y en integración continua.
Principios de diseño: por qué el lenguaje es como es.
Preguntas frecuentes: respuestas cortas con enlace a la regla.
Las especificaciones: STXT-SPEC para la sintaxis, STXT-SCHEMA-SPEC y STXT-TEMPLATE-SPEC para la validación, STXT-DISCOVERY-SPEC para dónde se buscan las definiciones y STXT-TREE-SPEC para el árbol JSON que producen las herramientas.

Las normas de estilo del lenguaje —recomendaciones, no reglas— están en STXT-SPEC §4.4 y §9.2.