Document (dev.stxt.website): STXT Tutorial Metadata: Author: ChatGPT 5.2 Last modif: 2026-08-02 Header: @STXT@ Tutorial Subheader: 1. What is @STXT@? Assert >> **@STXT@ (Semantic Text)** is a hierarchical and semantic textual language, designed to be **Human-First**: Content >> * 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. Subheader: 2. Tools Content >> 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](https://github.com/stxt-lang/stxt-web) * Recommended editor: [Visual Studio Code](https://code.visualstudio.com/) * Official extension: [STXT (stxt-lang.stxt)](https://marketplace.visualstudio.com/items?itemName=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. Subheader: 3. Basic example: a book record Content >> 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. Code >> 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. Content >> 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. Subheader: 4. Indentation and levels Assert >> In @STXT@ indentation **is** the structure: there are no braces, brackets, or closing tags. A line's level is the only thing that decides whose child it is. Content >> 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. Content >> In the following example `.` represents a space and `|-->` a tab: Listing >> 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 Content >> 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. Subsubheader: 4.1 Indentation inside `>>` blocks Content >> 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. Code >> 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. Content >> 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. Subheader: 5. Node names Content >> 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. Code >> 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-日本語 Assert >> Name equality is insensitive to case and separators, but **sensitive to accents and script**: `Título` and `título` are the same node,\\ but `Año` and `Ano` are different nodes. Content >> 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). Subheader: 6. Comments Content >> @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. Code >> # A book record Book: # The title goes first Title: Modern software architecture ISBN: 978-84-123456-7-8 Content >> 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. Subheader: 7. Use of namespaces Assert >> Namespaces allow grouping nodes into categories. In addition, if a namespace is defined for a node, **child nodes inherit the parent's namespace**, unless one of them redefines it. Content >> Example of a document with a namespace (tutorial/book-ns.stxt): Code >> 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. Content >> 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. Subsubheader: 7.1 Special namespaces with `@` Content >> 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. Subsubheader: 7.2 Document validation Content >> 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. Assert >> To validate a document, **it is necessary for it to belong to a namespace**.\\ On the other hand, a document with a namespace does not have to be validated. Subheader: 8. Validation with Templates Content >> **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`. Subsubheader: 8.1 Template for books Code >> 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 Content >> 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`. Subsubheader: 8.2 Allowed forms for numbering Content >> | Form | Meaning | |------------|------------------------------| | `num` | Exactly `num`. | | `*` | Any number (`0..∞`). | | `+` | One or more (`1..∞`). | | `?` | Zero or one (`0..1`). | | `num+` | `num` or more (`num..∞`). | | `num-` | Up to `num` (`0..num`). | | `min,max` | Between `min` and `max`. | Subsubheader: 8.3 Available types Content >> The type is written **after** the cardinality. If none is given, the default type is `INLINE`. The most common ones: | Type | Value form | What for | |------------|-----------------|-------------------------------------------------| | `INLINE` | inline | Simple text. Accepts children. **Default.** | | `GROUP` | no value | Structure only, no value of its own. | | `TEXT` | inline or `>>` | Generic text, no interpretation. | | `MARKDOWN` | inline or `>>` | Text to be interpreted as Markdown. | | `NUMBER` | inline | Number in JSON format. | | `DATE` | inline | `YYYY-MM-DD` date. | | `ENUM` | inline | Only the enumerated values. | `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*. Subsubheader: 8.4 Applying the template Content >> 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. Subheader: 9. Validation with Schemas Content >> **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. Subsubheader: 9.1 Schema equivalent to the template Code >> 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 Content >> * 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**. Subheader: 10. Final validatable document Content >> Complete @STXT@ document that can be validated with the previous template or schema: Code >> 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. Content >> This document: * Is valid @STXT@. * Complies with the `com.acme.book` template. * Complies with the `com.acme.book` schema. Subheader: 11. Best practices Content >> * 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.