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

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

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

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

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

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

6.2 Allowed forms for numbering

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

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

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

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

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

9. Best practices

• Use >> blocks for long or literal text.
• Maintain consistent indentation (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