◄ Introducción STXT Documentos ►

STXT Tutorial

1. ¿Qué es STXT?
2. Herramientas
3. Ejemplo básico: ficha de un libro
4. Comentarios
5. Uso de namespaces
6. Validación con Plantillas
7. Validación con Schemas
8. Documento final validable
9. 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:

Fácil de leer y escribir por personas.
Trivial de parsear por máquinas.
Seguro por diseño.

STXT permite representar documentos estructurados mediante:

Nodos INLINE (:) para valores simples.
Nodos BLOCK de texto literal (>>) para contenido multilínea.
Indentación para expresar jerarquía.
Namespaces para separar semántica y permitir validación externa.

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

@stxt.schema — validación formal y exhaustiva.
@stxt.template — validación mediante plantillas de estructura, orientada a prototipos.

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.

Repositorio del tutorial y ejemplos: Documentos STXT
Editor recomendado: Visual Studio Code
Extensión oficial: STXT (stxt-lang.stxt)
Instalación rápida: code --install-extension stxt-lang.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:

La jerarquía se define únicamente por indentación.
Summary >> y Content >> son bloques de texto literal: su contenido no se interpreta como STXT.
No existe ningún tipo implícito: todo es texto mientras no se valide.

4. 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:

Los comentarios son de línea completa. No existen comentarios a final de línea: en Title: Mi libro # nota, el # y lo que le sigue forman parte del valor, no un comentario.
La indentación de un comentario no se valida: puede ir a cualquier nivel. Por estilo, se recomienda alinearlo con el nodo que describe.
Dentro de un bloque de texto >> todo es literal: un # ahí es texto, no un comentario.

5. 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:

El namespace se hereda por los nodos hijos.
Un nodo puede redefinir su namespace si es necesario.
El lenguaje STXT no valida el namespace, sólo define las reglas de propagación.

5.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.

5.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.

6. 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.

6.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:

Book es el nodo raíz esperado.
Title, ISBN y Authors son obligatorios ((1)).
Author puede repetirse y al menos debe haber uno ((+)).
Published debe tener formato DATE.
Summary y Content son bloques de texto (TEXT).
Al menos debe haber un Chapter.

6.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`.

6.3 Aplicación del template

Un validador que soporte plantillas debe:

Verificar que los nodos existen.
Comprobar cardinalidades.
Validar tipos básicos (número, fecha, boolean, texto).

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.

7. 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:

Es un documento STXT con namespace @stxt.schema.
Define nodos, tipos y cardinalidades por separado.
Es la representación “canónica” de validación.

7.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: Chapters
				Max: 1

	Node: Authors
		Children:
			Child: Author
				Min: 1

	Node: Chapters
		Children:
			Child: Chapter
				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

El schema es más verboso, pero más explícito.
Un template puede compilarse automáticamente a esta forma.
Un validador DEBERÍA establecer un criterio de prioridad si existen esquemas y templates de forma simultánea para un mismo namespace. Sólo puede haber uno activo.

8. 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:

Es STXT válido.
Cumple el template com.acme.book.
Cumple el schema com.acme.book.

9. Buenas prácticas

Usar bloques >> para texto largo o literal.
Mantener indentación consistente (usar espacios o tabuladores, pero no mezclarlos).
Usar plantillas para iterar rápido o tener una visión lo más parecida posible a como son los documentos.
Usar esquemas cuando se necesite una descripción más formal de los campos

◄ Introducción STXT Documentos ►