STXT - Semantic Text
Built for humans. Reliable for machines.
◄ Introducción STXT Documentos ►

STXT Tutorial

1. ¿Qué es STXT?
2. Herramientas
3. Ejemplo básico: ficha de un libro
4. Indentación y niveles
5. Nombres de nodo
6. Comentarios
7. Uso de namespaces
8. Validación con Plantillas
9. Validación con Schemas
10. Documento final validable
11. Buenas prácticas

1. ¿Qué es STXT?

STXT (Semantic Text) es un lenguaje textual jerárquico y semántico, diseñado para ser Human-First:

STXT permite representar documentos estructurados mediante:

La sintaxis base es mínima. La semántica avanzada se añade mediante:

2. Herramientas

Para empezar a trabajar con STXT, lo más práctico es usar un editor que permita escribir documentos con comodidad y navegar bien por la jerarquía. La opción recomendada es Visual Studio Code, junto con la extensión oficial de STXT.

Con esta combinación puedes leer y editar los ejemplos del tutorial de forma más cómoda, mantener bien la indentación y experimentar con la estructura de los documentos sin tener que preparar un entorno complejo.

Además, el proyecto de GitHub no contiene sólo este tutorial: incluye más documentos y ejemplos que puedes abrir, modificar, copiar y reutilizar para hacer pruebas. Es recomendable usarlos libremente para experimentar con nodos, bloques de texto, namespaces, templates y schemas, porque esa es la forma más rápida de familiarizarse con el lenguaje.

3. Ejemplo básico: ficha de un libro

Veamos un ejemplo sencillo de un documento STXT que describe un libro (tutorial/book-raw.stxt). No hay validación todavía: es sólo lenguaje STXT. Además, no tiene ningún namespace asociado.

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.

Observaciones:

4. Indentación y niveles

En STXT la indentación es la estructura: no hay llaves, corchetes ni etiquetas de cierre. El nivel de una línea es lo único que decide de quién es hija.

Las reglas son deliberadamente pequeñas:

Líneas distintas de un mismo documento pueden usar estilos distintos, porque la jerarquía se compara por nivel y no por columnas. No es recomendable, y un parser puede emitir un aviso, pero no es un error.

En el ejemplo siguiente . representa un espacio y |--> un tabulador:

Book:
|-->Title: Correcto, 1 tab = nivel 1
....ISBN: Correcto, 4 espacios = nivel 1
..Publisher: ERROR, 2 espacios no llegan a un múltiplo de 4
.|-->Summary: ERROR, mezcla espacio y tabulador en la misma línea

El motivo de rechazar la mezcla en lugar de interpretarla es Human-First: una línea que combina 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.

Que el ancho de nivel sea fijo (1 tab o 4 espacios, nunca 2) tiene además una consecuencia práctica: el nivel de una línea se calcula mirando sólo esa línea, sin arrastrar contexto ni mantener una pila de indentaciones. Por eso parsear STXT es trivial.

4.1 Indentación dentro de bloques `>>`

Un bloque de texto >> tiene un nivel de bloque fijo: el del nodo >> más uno. Ese prefijo es lo único que se valida; todo lo que va después es texto literal, y su sangría relativa se conserva tal cual.

Summary >>
	Esta línea está en el nivel de bloque.
		Esta otra se ve 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 >>. Las líneas vacías no lo cierran, y los comentarios son transparentes: ni lo cierran ni forman parte de su contenido.

5. Nombres de nodo

Un nodo es siempre Nombre: (inline) o Nombre >> (bloque). El nombre admite letras y dígitos Unicode de cualquier alfabeto —latino, griego, cirílico, árabe, CJK…—, además de los separadores -, _ y espacio, y debe contener al menos una letra o un dígito.

Para decidir si dos nodos son el mismo, STXT compara sus nombres canónicos, que se obtienen así:

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-日本語

La igualdad de nombres es insensible a mayúsculas y a separadores, pero sensible a acentos y alfabeto: Título y título son el mismo nodo,
pero Año y Ano son nodos distintos.

Es el mismo criterio que usan los nombres de dominio internacionalizados (IDN), y es deliberado: permite escribir documentos en cualquier idioma sin que el lenguaje "corrija" las palabras por detrás ni funda en uno solo dos nombres que para quien lee son distintos.

Los namespaces son la excepción: siguen restringidos a ASCII [a-z0-9] (ver sección 7).

6. Comentarios

STXT admite comentarios de línea. Una línea es un comentario cuando su primer carácter (tras la indentación) es #; el parser la descarta por completo, así que no forma parte ni 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

Puntos clave:

7. Uso de namespaces

Los namespaces permiten agrupar nodos en categorías. Además, si se define un namespace para un nodo, los nodos hijos heredan el namespace del padre, a no ser que uno de ellos lo redefina.

Ejemplo de un documento con namespace (tutorial/book-ns.stxt):

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.

En este ejemplo vemos el nodo Book que pertenece al namespace com.acme.book. Además, también vemos nodos Title, Authors, Author y ISBN, que al ser descendientes de Book también heredan el namespace com.acme.book.

Reglas clave:

7.1 Namespaces especiales con `@`

Los namespace pueden empezar o no con @. Esto nos indica que son namespaces especiales o reservados. Por ejemplo, tanto los plantillas como los esquemas empiezan por @.

Esto es sólo una indicación semántica, pero el funcionamiento es el mismo.

Eso sí, @ forma parte del namespace: @com.acme.book y com.acme.book son namespaces distintos, y un documento sólo valida contra el template o schema cuyo namespace coincida exactamente. La rama @stxt.* está reservada al propio lenguaje (@stxt.schema, @stxt.template): no debe usarse para namespaces propios.

7.2 Validación de documentos

Para poder validar semánticamente un documento, debe asociarse a un namespace. Una vez tiene el namespace, se usa un esquema (@stxt.schema) o template (@stxt.template) para validarlo. Las validaciones son extensiones al lenguaje base, que los parsers pueden o no implementar.

Para validar un documento es necesario que pertenezca a un namespace.
Por otro lado, un documento con namespace no es obligatorio validarlo.

8. Validación con Plantillas

Las Plantillas permiten definir reglas estructurales y de tipo de forma compacta. Son ideales para prototipos y documentación viva.

Un template es un documento STXT cuyo namespace es @stxt.template.

8.1 Template para libros

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

Qué define este template:

8.2 Formas permitidas para la numeración

Forma Significado
num Exactamente num.
* Cualquier número (0..∞).
+ Una o más (1..∞).
? Cero o una (0..1).
num+ num o más (num..∞).
num- Hasta num (0..num).
min,max Entre min y max.

8.3 Tipos disponibles

El tipo se escribe después de la cardinalidad. Si no se indica ninguno, el tipo por defecto es INLINE. Los más habituales:

Tipo Forma del valor Para qué
INLINE inline Texto simple. Admite hijos. Por defecto.
GROUP sin valor Sólo estructura, sin valor propio.
TEXT inline o >> Texto genérico, sin interpretación.
MARKDOWN inline o >> Texto que se interpreta como Markdown.
NUMBER inline Número con formato JSON.
DATE inline Fecha YYYY-MM-DD.
ENUM inline Sólo los valores enumerados.

MARKDOWN no valida nada que TEXT no valide: todo texto es Markdown válido, así que ninguna implementación debe rechazar un valor por su contenido. Lo que aporta es un contrato de interpretación para quien consume el documento —renderizadores, exportadores, editores—, que debería leerlo como CommonMark.

Sólo INLINE y GROUP admiten hijos: en cuanto un tipo valida un dato concreto (NUMBER, DATE, ENUM…), ese nodo es un dato, y un dato es una hoja.

La lista completa de tipos está en STXT-SCHEMA-SPEC.

8.4 Aplicación del template

Un validador que soporte plantillas debe:

El lenguaje STXT no cambia: el template se aplica sobre el árbol ya parseado. Dependiendo del parser, puede validar al mismo tiempo que parsea el contenido.

9. Validación con Schemas

Los Schemas proporcionan la misma información que un template, pero de forma más explícita y formal.

Un schema:

9.1 Schema equivalente al template

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

10. Documento final validable

Documento STXT completo que puede validarse con el template o el schema anterior:

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.

Este documento:

11. Buenas prácticas

◄ Introducción STXT Documentos ►