STXT Tutorial

1. What is STXT?

STXT (Semantic Text) is a hierarchical and semantic textual language, designed to be Human-First:

• Easy to read and write by people.
• Trivial to parse by machines.
• Secure by design.

STXT allows representing structured documents through:

• Inline nodes (:) for simple values.
• Literal text blocks (>>) for multiline content.
• Indentation to express hierarchy.
• Namespaces to separate semantics and allow external validation.

The base syntax is minimal. Advanced semantics are added through:

• @stxt.schema — formal and exhaustive validation.
• @stxt.template — simplified and prototype-oriented validation.

2. Basic example: a book record

Let’s look at a simple example of an STXT document that describes a book. There is no validation yet: it is only STXT language. Also, it has no associated namespace.

Book:
	Title: Modern software architecture
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Publisher: ACME Publishing
	Published: 2025-10-01
	Summary >>
		This book offers a practical view of patterns and best practices
		for designing distributed and scalable systems.
	Chapter: Introduction to architecture
		Content >>
			In this chapter we present basic concepts:
			monoliths, microservices, and design criteria.
	Chapter: Communication between services
		Content >>
			Protocols, messaging, and integration patterns are described.

Observations:

• The hierarchy is defined only by indentation.
• Summary >> and Content >> are literal text blocks: their content is not interpreted as STXT.
• There is no implicit type: everything is text unless it is validated.

3. Using namespaces

Example of a document with a namespace:

Book (com.acme.book):
	Title: Modern software architecture
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8

In this example we see the Book node that belongs to the com.acme.book namespace. In addition, we also see nodes Title, Authors, Author, and ISBN, which, being descendants of Book, also inherit the com.acme.book namespace.

Key rules:

• The namespace is inherited by child nodes.
• A node can redefine its namespace if necessary.
• The STXT language does not validate the namespace; it only defines the propagation rules.

3.1 Special namespaces with `@`

Namespaces may or may not start with @. This indicates that they are special or reserved namespaces. For example, both templates and schemas start with @.

This is only a semantic indication, but the behavior is the same.

3.2 Document validation

To be able to semantically validate a document, it must be associated with a namespace. Once it has the namespace, a schema (@stxt.schema) or template (@stxt.template) is used to validate it. Validations are extensions to the base language, which parsers may or may not implement.

4. Validation with Templates

Templates allow defining structural and type rules in a compact way. They are ideal for prototypes and living documentation.

A template is an STXT document whose namespace is @stxt.template.

4.1 Template for books

Template (@stxt.template): com.acme.book
	Description: Template for publishing book records
	Structure >>
		Book:
			Title: (1)
			Authors: (1)
				Author: (+)
			ISBN: (1)
			Publisher: (?)
			Published: (?) DATE
			Summary: (?) TEXT
			Chapter: (+)
				Content: (?) TEXT

What this template defines:

• Book is the expected root node.
• Title, ISBN, and Authors are required ((1)).
• Author can repeat and there must be at least one ((+)).
• Published must have DATE format.
• Summary and Content are text blocks (TEXT).
• There must be at least one Chapter.

4.2 Applying the template

A validator that supports templates must:

• Verify that the nodes exist.
• Check cardinalities.
• Validate basic types (number, date, boolean, text).

The STXT language does not change: the template is applied over the already-parsed tree. Depending on the parser, it may validate at the same time it parses the content.

5. Validation with Schemas

Schemas provide the same information as a template, but in a more explicit and formal way.

A schema:

• Is an STXT document with namespace @stxt.schema.
• Defines nodes, types, and cardinalities separately.
• Is the “canonical” representation of validation.

5.1 Schema equivalent to the 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

6. Final validatable document

Complete STXT document that can be validated with the previous template or schema:

Book (@com.acme.book):
	Title: Modern software architecture
	Authors:
		Author: María Pérez
		Author: Juan García
	ISBN: 978-84-123456-7-8
	Published: 2025-10-01
	Summary: A practical introduction to the architecture of modern systems.
	Chapter: Introduction
		Content >>
			Basic concepts and objectives of the book.

This document:

• Is valid STXT.
• Complies with the com.acme.book template.
• Complies with the com.acme.book schema.

7. Best practices

• Use >> blocks for long or literal text.
• Keep indentation consistent (use spaces or tabs, but do not mix them).
• Use templates to iterate quickly or to have a view as close as possible to what the documents are like.
• Use schemas when a more formal description of the fields is needed