Document (dev.stxt.website): Preguntas frecuentes | STXT Metadata: Last modif: 2026-09-16 Description: Preguntas frecuentes sobre STXT: qué significa el nombre, en qué se diferencia de XML, YAML, TOML, JSON y Markdown, cómo se valida y cómo empezar a usarlo. Header: Preguntas frecuentes Subheader: El lenguaje Subsubheader: ¿Qué significa el nombre STXT? Content >> La primera versión del lenguaje se llamaba **STxT** (*Semantic Text*); de ahí vienen el nombre y la pronunciación «S-text». @STXT@ es su evolución: conserva el espíritu, la motivación y la sintaxis base, pero ha cambiado significativamente desde entonces. Las referencias a *STxT* que puedan encontrarse corresponden al lenguaje antiguo. El término *Semantic Text* también se ha retirado. El nombre actual es @STXT@. Subsubheader: ¿Cómo se pronuncia STXT? Content >> «ESS-text» o «ESE-text»: primero la letra `S` y después `text`, como *S-text*. Subsubheader: ¿Es un lenguaje o un formato? Content >> Las dos. @STXT@ se define como **lenguaje**: una gramática pensada para escribirse a mano, especificaciones normativas, esquemas y herramientas. También **actúa como formato**, ya que los sistemas lo pueden usar para guardar o mostrar información. Las dos palabras no se excluyen; XML es _Extensible Markup Language_ y también _un fichero en formato XML_. Subsubheader: ¿Es un formato de datos o de documentos? Content >> Los dos. Un email tiene campos y un cuerpo; un contrato, cláusulas y metadatos; una configuración, valores y comentarios largos. @STXT@ es un árbol de nodos con nombre, y cada nodo lleva un valor, unos hijos o un bloque de texto. Con esto se describe tanto un documento como un formato de datos. Subsubheader: ¿Qué lo distingue de otros formatos? Content >> @STXT@ está diseñado para las personas, y de ese principio salen las características que lo definen: * **Pocas reglas.** * Un nodo es `Nombre: valor` o `Nombre >>` * La jerarquía es la indentación * No hay llaves, corchetes, comillas, etiquetas de cierre ni sintaxis de lista * **Sin caracteres de escape.** * **Parseo lineal.** Línea a línea, en una sola pasada, sin retroceso ni referencias. * **Seguridad del parseo por diseño.** Sin entidades, referencias, anclas, inclusión de ficheros ni ejecución de código; namespaces en ASCII, sin ambigüedad de identificadores. * **Namespaces y validación en el lenguaje.** Un documento declara a qué namespace pertenece. Además, se puede añadir una capa de esquemas, que lo valida contra su definición. Subsubheader: ¿Qué extensión y qué media type se usan? Content >> Extensión `.stxt`; media type `text/stxt` (registro en IANA previsto, aún no registrado), y `text/plain` como alternativa compatible. Codificación UTF-8 sin BOM (un parser acepta también el BOM), finales de línea `LF` (se acepta `CRLF`). Subsubheader: ¿Nos enseñas un uso real? Content >> Este portal. Todas las páginas de `stxt.dev` están escritas en @STXT@. El [generador](https://github.com/stxt-lang/stxt-cms) las convierte en HTML. El enlace `.stxt` de la cabecera abre el fuente de la página actual. También se puede añadir `.stxt` a la dirección de cualquier página para ver el código fuente; por ejemplo [faq.stxt](faq.stxt). Subheader: ¿Por qué no...? Subsubheader: ¿Por qué no XML, YAML o TOML? Content >> | | @STXT@ | XML | YAML | TOML | |---|---|---|---|---| | **Jerarquía** | Indentación, un tabulador o cuatro espacios por nivel; una sola grafía | Etiquetas de apertura y cierre | Indentación de ancho libre; sintaxis de bloque y de flujo para la misma estructura | Cabeceras `[a.b]` con la ruta completa; también claves con punto y tablas en línea | | **Valores** | Siempre texto; el tipo lo declara la definición | Texto; el tipo lo declara el esquema | El tipo lo decide la grafía (`no`, `3.10`), con reglas distintas en 1.1 y 1.2 | El tipo lo decide la grafía; las cadenas, siempre entre comillas | | **Texto libre** | Bloques `>>` literales: cualquier carácter, sin escapes | Escapar `<` y `&`, o CDATA | Escalares de bloque, literales o plegados, con indicadores de recorte | Cadenas multilínea entre triples comillas; la indentación entra en el valor | | **Namespaces** | En el lenguaje | En el lenguaje | No | No | | **Esquemas** | En el lenguaje, opcionales, modelo cerrado | DTD, XSD, RELAX NG, Schematron | No; herramientas externas | No; herramientas externas | | **Parseo** | Lineal, línea a línea, en una sola pasada | Entidades, DTD interno y namespaces que el parser resuelve | Gramática extensa; dos versiones con resolución de tipos distinta | Gramática pequeña; fechas, horas y tablas en línea como tipos nativos | | **Superficie de ataque** | Sin entidades, referencias, anclas ni ejecución de código | Entidades externas (XXE), expansión de entidades | Anclas expansibles; etiquetas que instancian objetos | Sin entidades ni referencias | Se puede ver la comparación completa con cada formato en las siguientes páginas: * [STXT frente a XML](stxt-vs-xml) * [STXT frente a YAML](stxt-vs-yaml) * [STXT frente a TOML](stxt-vs-toml) Subsubheader: ¿Por qué no Markdown? Content >> Markdown da **formato** al texto (negrita, enlaces, listas), mientras que @STXT@ da **estructura** al documento: nodos, jerarquía y validación. @STXT@ usa Markdown como un tipo de texto permitido, con lo que se consiguen documentos estructurados, con validación y con semántica Markdown para los bloques de texto: Code >> Article (example.article): Guía de estilo Introduction >> Un documento **STXT** permite múltiples formas de mostrar el contenido. Aquí explicamos las recomendadas. Summary >> Un bloque de tipo MARKDOWN admite **negrita**, [enlaces](https://stxt.dev) o listas; la estructura del documento la ponen los nodos de alrededor. Template (@stxt.template): example.article Structure >> Article: Introduction: (?) MARKDOWN Summary: (?) MARKDOWN Subsubheader: ¿Por qué no JSON? Content >> Porque JSON es un formato de serialización y no está pensado para escribirse a mano. Todo va entre comillas, llaves y comas; los saltos de línea se escriben `\n`; no hay comentarios, y un texto largo es una sola línea con escapes. @STXT@ tiene como objetivo principal la escritura de documentos por personas, que puedan leerlos y modificarlos sin otras herramientas. Subsubheader: ¿Por qué no hay listas? Content >> Porque todo son listas. Los hijos de un nodo son una secuencia ordenada, y un mismo nombre puede repetirse tantas veces como haga falta. Además, el árbol conserva el orden de aparición. Un documento @STXT@ es ya una lista de nodos raíz, y cada nodo inline es una lista de hijos. Por eso no hace falta una sintaxis aparte para expresarla. Ejemplo: Code >> Authors: Author: María Pérez Author: Juan García Author: Ana López Subsubheader: ¿Por qué no hay caracteres de escape? Content >> Porque no hacen falta. La sintaxis de @STXT@ solo valida el nombre del nodo y que exista un separador (`:` o `>>`). Todo lo que hay a continuación es valor o texto literal. Un valor puede contener `:`, un bloque puede contener `#` o `>>`, y una barra invertida es una barra invertida. Code >> Ruta: C:\Users\ana\docs Nota >> Los símbolos :, #, >>, \n no significan nada aquí. Subsubheader: ¿Por qué no se permiten otros caracteres en los nombres? Content >> Técnicamente era posible excluir solo los caracteres que delimitan la sintaxis (`:`, `>` y los paréntesis), pero por el principio Human-First se limitan a letras, dígitos y los separadores `-`, `_` y espacio. De esta forma no se sugiere un significado que no existe en @STXT@. Subsubheader: ¿Por qué un bloque de texto no puede tener hijos? Content >> Por diseño: * **Ruido visual.** Para saber dónde acaba el texto y empiezan los hijos haría falta una marca de fin de bloque, y un documento dejaría de leerse como un esquema de notas. * **Más complejidad en el parser.** * **Mezcla de significado.** Un nodo que necesita a la vez hijos y un bloque de texto está describiendo dos cosas distintas, y eso apunta a que son dos nodos. Por eso un nodo solo es inline o bloque, y no las dos cosas a la vez. En caso de necesitarse, hay que desdoblarlo en dos nodos de forma explícita. Code >> Chapter: Introducción Author: María Pérez Summary >> Conceptos básicos: monolitos, microservicios y criterios de diseño. Content >> El capítulo presenta... Subheader: Escribir documentos Subsubheader: ¿Tabuladores o espacios? Content >> Ambos son válidos y equivalentes: * **Un tabulador es un nivel y cuatro espacios son un nivel.** * No es válido mezclarlos en la indentación de una misma línea. * Un documento puede usar estilos distintos para distintas líneas, aunque no se recomienda. Subsubheader: ¿Por qué un ancho fijo? Content >> El ancho fijo es deliberado: el nivel de una línea se calcula a partir de su indentación, con independencia de las otras líneas. Esto se deriva del principio KISS, con parsers más sencillos de implementar y documentos más sencillos de escribir. Subsubheader: ¿Importan las mayúsculas, los acentos y los espacios en los nombres? Content >> Los nombres se comparan case-insensitive, pero conservando los acentos. Los espacios se comparan reduciéndolos a un guion (y se eliminan los iniciales y finales). Así: * `Fecha de nacimiento`, `fecha_de_nacimiento` y `Fecha-De-Nacimiento` son el mismo nodo. * `Título` y `título` son el mismo nodo; `Titulo` es otro. * `Caña` y `cana`, o `Peña` y `pena`, son nodos distintos. Los **namespaces** son más estrictos: solo ASCII `[a-z0-9]` y puntos, y al menos `a.b`. Además, se pasan a minúsculas en el proceso de parseo. Subsubheader: ¿Cómo se escribe un valor con dos puntos o almohadilla dentro? Content >> Sin ninguna marca. En un nodo inline el valor es todo lo que sigue al **primer** `:`, de modo que `Hora: 10:30` vale `10:30`, y `#` solo abre un comentario cuando es el primer carácter no blanco de la línea. En un bloque `>>` todo es texto literal. Code >> Cita: 10:30 en la sala 2 # esto forma parte del valor Notas >> # esto también es texto, no un comentario Clave: valor >> tampoco es un nodo Subsubheader: ¿Puede un documento tener varios nodos raíz? Content >> Sí. Un fichero puede contener varios nodos de nivel 0, cada uno con su árbol. Eso permite parsear en *streaming* ficheros grandes. Además, los namespaces no se heredan lateralmente entre raíces, ya que cada una declara el suyo. Subsubheader: ¿Puede un documento usar varios namespaces? Content >> Sí. Cualquier nodo puede declarar su propio namespace y sus descendientes lo heredan directamente a partir de él. Además, cada namespace tiene su propia validación independiente. Ejemplo: Code >> Book (com.acme.book): Title: Arquitectura de software moderna Review (com.acme.reviews): Reviewer: Ana López Score: 9 Content >> Y las plantillas de los dos namespaces: Code >> Template (@stxt.template): com.acme.book Structure >> Book: Title: (1) Review (com.acme.reviews): (*) Template (@stxt.template): com.acme.reviews Structure >> Review: Reviewer: (1) Score: (1) NUMBER Content >> `Reviewer` y `Score` pertenecen a `com.acme.reviews`, y cada namespace se valida contra su propia plantilla. Subsubheader: ¿Se indentan los comentarios? Content >> Un comentario se indenta igual que un nodo. Esto no es estrictamente necesario, pero es para que no quede fuera del estilo homogéneo de @STXT@ (principio Human-First). Subheader: Esquemas y plantillas Subsubheader: ¿Los esquemas son obligatorios? Content >> No. Un documento sin namespace se puede parsear sin problema, y uno con namespace contiene más información que otro sin él. Si tiene namespace, es la herramienta de parseo la que decide si validar o no el documento con el esquema. Subsubheader: ¿Esquema o plantilla? Content >> Son dos sintaxis distintas para el mismo modelo, y **toda plantilla equivale a un esquema**. La plantilla (`@stxt.template`) se escribe de forma muy similar al documento que describe, por lo que es la forma más directa de crear una definición. Aun así, una plantilla tiene decisiones implícitas, que deben tenerse en cuenta. En cambio, un esquema es más explícito, pero menos compacto que una plantilla. Subsubheader: ¿Cómo encuentra una herramienta los esquemas y plantillas? Content >> Depende de la herramienta, porque la resolución de definiciones no forma parte del lenguaje base: es una capa opcional más, como los propios esquemas y plantillas. Una aplicación sin sistema de ficheros la resuelve a su manera (el playground, por ejemplo, asocia documentos y gramáticas por namespace dentro del workspace). Para cuando intervienen ficheros y proyectos, [STXT-DISCOVERY-SPEC](stxt-discovery-ref) define una resolución común, que una herramienta puede implementar o no. Actualmente, la CLI, la extensión de VS Code y las tres bibliotecas implementan STXT-DISCOVERY-SPEC. Subsubheader: ¿Dónde se colocan los esquemas y plantillas? Content >> En las herramientas que siguen [STXT-DISCOVERY-SPEC](stxt-discovery-ref), en un directorio llamado **`.stxt/`** en el proyecto: se cargan todos los `.stxt` que haya dentro, recursivamente, con independencia de los nombres de fichero y de los subdirectorios. La cadena de resolución de un documento son todos los `.stxt/` de sus directorios ascendentes, luego `~/.stxt` y por último `/etc/stxt` (en Windows, `%USERPROFILE%\.stxt` y `%ProgramData%\stxt`). Gana el nivel más cercano, namespace a namespace. La variable `STXT_PATH` sustituye la cadena entera por una lista de directorios, por ejemplo en CI. Subsubheader: ¿Qué pasa si se escribe Titel en vez de Title? Content >> Con validación habilitada, se rechaza, ya que el modelo de contenido es **cerrado**. Un nodo solo admite los hijos definidos, y si no tiene hijos definidos, no admite ninguno. Subsubheader: ¿Se valida el orden de los hijos? Content >> No. Se valida la cardinalidad, pero no la posición. Dos documentos con los mismos hijos en distinto orden validan de la misma forma. Además, el orden se conserva en el árbol, de modo que el significado depende de la aplicación que lo consume y no del validador. Subsubheader: ¿Cómo se evoluciona un esquema sin romper documentos? Content >> Ampliando la definición sin invalidar lo ya escrito: todo documento que validaba sigue validando si el cambio solo permite más casos. No hace falta una versión nueva para: * Añadir un nodo **opcional**: con cardinalidad `(?)`, `(*)` o cualquier otra de mínimo cero. * Relajar una cardinalidad: rebajar un mínimo o ampliar un máximo, como pasar de `(2,5)` a `(1,5)` o a `(2,6)`. Un matiz: la compatibilidad es respecto a la definición ampliada. Un documento que use lo añadido no valida contra una copia anterior, así que si los consumidores del namespace no actualizan la definición a la vez, conviene versionar también las ampliaciones. Añadir un nodo obligatorio, retirar uno o estrechar una cardinalidad rompe siempre la compatibilidad. Para esos cambios se recomienda **versionar el namespace**, por ejemplo `com.example.docs.v1` → `com.example.docs.v2`. Subheader: Herramientas Subsubheader: ¿Cómo se valida en CI? Content >> Si se tiene Node.js instalado, se puede hacer desde la línea de comandos, sin añadir nada más: Listing >> npx @stxt-lang/cli validate --recursive docs/ npx @stxt-lang/cli format --check --recursive docs/ Subsubheader: ¿Existe una representación canónica de un documento STXT? Content >> Sí. Todo documento válido tiene un **árbol canónico** en JSON, definido en [STXT-TREE-SPEC](stxt-tree-ref): un array de raíces con `name`, `canonicalName`, `namespace` y `value`, más `children` (inline) o `lines` (bloque). No incluye posiciones ni comentarios: es el contenido lógico del documento. Subsubheader: ¿En qué lenguajes hay parser? Content >> La organización `stxt-lang` mantiene tres: TypeScript/JavaScript (`@stxt-lang/core`), Java (`dev.stxt:stxt-core`) y Python (`stxt`). Subsubheader: ¿Qué estabilidad se puede esperar? Content >> La estabilidad está explicada en [Estabilidad y versiones](stability). Las especificaciones no llevan número de versión: cada una lleva una **fecha** (la de su texto vigente) y un **estado**, que solo avanza y define el grado de estabilidad: * *Genesis*: en construcción, inestable. * *Aurora*: usable; pocos cambios incompatibles esperados. * *Zenith*: sin cambios incompatibles, y solo se añade. * *Twilight*: cerrada/obsoleta. Subsubheader: ¿Dónde pregunto, o doy mi opinión? Content >> En las [discusiones](https://github.com/orgs/stxt-lang/discussions) de la organización `stxt-lang` en GitHub: preguntas, ideas, ambigüedades de las especificaciones y lo que hayas construido con STXT. Los errores de una herramienta concreta deben reportarse en su repositorio.