STXT Tutorial

1. What is STXT?

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

STXT allows representing structured documents through:

• INLINE nodes (:) for simple values.
• BLOCK nodes of literal text (>>) 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 — validation through structure templates, oriented toward prototypes.

2. Tools

To start working with STXT, the most practical option is to use an editor that lets you write documents comfortably and navigate the hierarchy well. The recommended choice is Visual Studio Code, together with the official STXT extension.

• Tutorial and examples repository: STXT Documents
• Recommended editor: Visual Studio Code
• Official extension: STXT (stxt-lang.stxt)
• Quick installation: code --install-extension stxt-lang.stxt

With this combination you can read and edit the tutorial examples more comfortably, keep indentation under control, and experiment with the structure of the documents without having to prepare a complex environment.

In addition, the GitHub project does not contain only this tutorial: it includes more documents and examples that you can open, modify, copy, and reuse for testing. It is advisable to use them freely to experiment with nodes, text blocks, namespaces, templates, and schemas, because that is the fastest way to become familiar with the language.

3. Basic example: a book record

Let's look at a simple example of an STXT document that describes a book (tutorial/book-raw.stxt). 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 good 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.

Notes:

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

4. Indentation and levels

The rules are deliberately small:

• 1 tab = 1 level.
• 4 spaces = 1 level, always in multiples of 4.
• A line's indentation must be homogeneous: either tabs only, or spaces only. Mixing both on the same line is a parse error.
• Levels must be consecutive: you cannot jump from level 1 to level 3.

Different lines of the same document may use different styles, because hierarchy is compared by level and not by columns. It is not advisable, and a parser may emit a warning, but it is not an error.

In the following example . represents a space and |--> a tab:

Book:
|-->Title: Correct, 1 tab = level 1
....ISBN: Correct, 4 spaces = level 1
..Publisher: ERROR, 2 spaces do not reach a multiple of 4
.|-->Summary: ERROR, mixes space and tab on the same line

The reason for rejecting the mix instead of interpreting it is Human-First: a line combining tabs and spaces looks different depending on each editor's tab width, and the hierarchy would stop being obvious just by reading it.

A fixed level width (1 tab or 4 spaces, never 2) also has a practical consequence: a line's level is computed by looking at that line only, without carrying context or maintaining a stack of indentations. That is why parsing STXT is trivial.

4.1 Indentation inside `>>` blocks

A >> text block has a fixed block level: the level of the >> node plus one. That prefix is the only thing validated; everything after it is literal text, and its relative indentation is preserved as is.

Summary >>
	This line sits at the block level.
		This one looks indented, and that indentation is part of the text.
	# This is not a comment: it is text.
	Title: this is not a node either.

The block ends at the first non-empty line whose indentation is less than or equal to that of the >> node. Empty lines do not close it, and comments are transparent: they neither close it nor form part of its content.

5. Node names

A node is always Name: (inline) or Name >> (block). The name accepts Unicode letters and digits from any script —Latin, Greek, Cyrillic, Arabic, CJK…—, plus the separators -, _, and space, and must contain at least one letter or digit.

To decide whether two nodes are the same, STXT compares their canonical names, obtained as follows:

• Unicode NFC normalization.
• Conversion to lowercase.
• Every run of separators (-, _, space) becomes a single -.
• Leading and trailing hyphens are removed.

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

This is the same criterion used by internationalized domain names (IDN), and it is deliberate: it lets you write documents in any language without the language "correcting" the words behind your back, and without merging into one two names that are distinct to a reader.

Namespaces are the exception: they remain restricted to ASCII [a-z0-9] (see section 7).

6. Comments

STXT supports line comments. A line is a comment when its first character (after the indentation) is #; the parser discards it completely, so it is not part of the tree or the data.

# A book record
Book:
	# The title goes first
	Title: Modern software architecture
	ISBN: 978-84-123456-7-8

Key points:

• Comments are whole-line. There are no end-of-line comments: in Title: My book # note, the # and what follows are part of the value, not a comment.
• A comment's indentation is not validated: it may sit at any level. As a style rule, align it with the node it describes.
• Inside a >> text block everything is literal: a # there is text, not a comment.

7. Use of namespaces

Example of a document with a namespace (tutorial/book-ns.stxt):

Book (com.acme.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 good 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.

In this example we see the Book node that belongs to the com.acme.book namespace. In addition, we also see Title, Authors, Author, and ISBN nodes, 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.

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

That said, @ is part of the namespace: @com.acme.book and com.acme.book are different namespaces, and a document only validates against the template or schema whose namespace matches exactly. The @stxt.* branch is reserved for the language itself (@stxt.schema, @stxt.template): it must not be used for your own namespaces.

7.2 Document validation

In order to semantically validate a document, it must be associated with a namespace. Once it has a 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.

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

8.1 Template for books

Template (@stxt.template): com.acme.book
	Description >>
		Book: Template for publishing house 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 may be repeated 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.

8.2 Allowed forms for numbering

8.3 Available types

The type is written after the cardinality. If none is given, the default type is INLINE. The most common ones:

MARKDOWN validates nothing that TEXT does not: all text is valid Markdown, so no implementation must reject a value because of its content. What it adds is an interpretation contract for whoever consumes the document —renderers, exporters, editors—, which should read it as CommonMark.

Only INLINE and GROUP accept children: as soon as a type validates a specific piece of data (NUMBER, DATE, ENUM…), that node is data, and data is a leaf.

The complete list of types is in STXT-SCHEMA-SPEC.

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

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

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

• The schema is more verbose, but more explicit.
• A template can be compiled automatically into this form.
• A validator SHOULD establish a priority criterion if schemas and templates exist simultaneously for the same namespace. There can only be one active.

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

11. Best practices

• Use >> blocks for long or literal text.
• Pick one indentation style —tabs or spaces— and keep it throughout the document. Remember that mixing them on the same line is not a matter of style: it is a parse error (section 4).
• Write node names in the document's own language: accents and non-Latin scripts are first-class citizens (section 5).
• 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.
• Mark as MARKDOWN the text meant to be rendered, and as TEXT the text that must be read as is.