STXT Transform
1. Introducción
Este documento es STXT-TRANSFORM-SPEC; las demás especificaciones lo citan con ese nombre.
Este documento define STXT Transform: las operaciones que llevan el contenido de un documento STXT a JSON, lo traen desde JSON y lo completan con datos externos. Son tres:
| Operación | Entrada | Salida |
|---|---|---|
| Exportación (export) | Un documento STXT | El mismo contenido en JSON |
| Importación (import) | Un documento JSON | El mismo contenido como documento STXT |
| Relleno (fill) | Un documento STXT con Slots y unos datos JSON | Un documento STXT completo |
Un Slot es el lugar de un documento que espera un dato. El relleno pone en cada Slot el dato que le corresponde.
Su propósito es que un documento STXT pueda ser la fuente de los programas que ya leen JSON, y que los datos que ya existen en JSON puedan pasar a STXT, sin escribir una conversión propia para cada namespace.
Las tres operaciones se definen sobre JSON: la exportación lo produce, la importación lo lee y el relleno toma de él sus datos. Los formatos que representan los mismos datos (objetos, listas y valores), como YAML o NestedText, pasan por JSON con sus propias herramientas: esta especificación no los trata, y una implementación no necesita leerlos ni escribirlos. Los formatos de nodos, como XML o KDL, no tienen una correspondencia única con JSON y se tratarán en apartados propios, probablemente solo para la exportación: escribirlos a partir del documento y su definición es sencillo, y leerlos pide un parser de cada formato. La exportación basta para el uso que se busca: escribir en STXT y llevar el contenido como entrada a programas que leen otros formatos.
La exportación y la importación se apoyan en la definición del namespace del documento, sea un schema o un template. El texto de un documento no dice qué valor es un número, qué nodo es una lista ni cómo se llaman sus elementos: lo dice su definición. Por eso estas dos operaciones apenas necesitan más información que el documento y su definición, y por eso mismo esta especificación exige para ellas, de momento, que el documento tenga namespace y que ese namespace tenga definición.
El relleno no necesita definición ni namespace: lo que hace cada Slot está escrito en el propio documento.
Esta especificación no cambia la sintaxis de STXT-SPEC ni la validación de STXT-SCHEMA-SPEC: es una capa posterior al parseo y a la validación, y opcional como ellas.
1.1 Fecha y estado de esta especificación
Esta especificación lleva su propia fecha y su propio estado en los campos Last modif y
Status de su Metadata, independientes de los de las demás especificaciones de STXT y
con el significado que fija STXT-SPEC §1.1. Está en Genesis: en
construcción, y cualquier parte de ella puede cambiar sin aviso.
Depende de STXT-SPEC y de STXT-SCHEMA-SPEC.
Hoy contiene la presentación de las tres operaciones y dos ejemplos: la exportación y la importación con JSON, y un primer esbozo del relleno de Slots. Las reglas de JSON y las de los Slots están por escribir.
1.2 Relación con el árbol canónico
STXT-TREE-SPEC ya define una representación JSON de un documento: el árbol canónico. Su propósito es otro. El árbol canónico describe el resultado del parseo, con cada nodo como un objeto que lleva su nombre, su nombre canónico, su namespace, su forma y su valor, y existe para comparar implementaciones. No necesita definición, y todos los valores son texto.
La exportación de esta especificación produce el JSON que escribiría quien diseñara ese dato directamente en JSON: objetos con una clave por nodo, arrays, números y booleanos. Necesita la definición, y es la forma pensada para que la consuma un programa.
1.3 Relación con los templates
Un documento con Slots no es un @stxt.template. Un template
(STXT-TEMPLATE-SPEC) describe la estructura de todos los
documentos de un namespace y sirve para validarlos. Un documento con Slots es
un documento, con namespace o sin él, al que le faltan valores: sus Slots se rellenan con
unos datos externos, por ejemplo un JSON, y el resultado es un documento completo, que
se valida como cualquier otro.
Para evitar la confusión, esta especificación no llama «plantilla» ni «template» al documento con Slots.
2. Terminología
Las palabras clave "DEBE", "NO DEBE", "DEBERÍA", "NO DEBERÍA", y "PUEDE" deben interpretarse según RFC 2119 y RFC 8174: tienen ese significado únicamente cuando aparecen en mayúsculas, como aquí.
Términos como nodo, namespace, schema, template, tipo y cardinalidad mantienen su significado en STXT-SPEC, STXT-SCHEMA-SPEC y STXT-TEMPLATE-SPEC.
Definiciones adicionales:
- Definición: el schema o el template del namespace de un documento, como en STXT-DISCOVERY-SPEC.
- Exportación: la operación que produce, a partir de un documento STXT y su definición, un documento JSON.
- Importación: la operación que produce, a partir de un documento JSON y una definición, un documento STXT.
- Slot: el lugar de un documento STXT que el relleno sustituye por un dato.
- Documento con Slots: un documento STXT que contiene uno o más Slots.
- Relleno: la operación que produce un documento STXT completo a partir de un documento con Slots y unos datos.
3. Un ejemplo: STXT y JSON
Esta sección no es normativa. Muestra la dirección de la exportación y la importación con un documento sencillo.
Un documento:
# El servidor web de la oficina
Servidor (com.example.servidores):
Nombre: web-01
Activo: true
Puertos:
Puerto: 80
Puerto: 443
Responsable:
Persona: Ana Ruiz
Correo: ana@example.com
Notas >>
Reiniciar tras cada despliegue.
No apagar en horario de oficina.Y la definición de su namespace, aquí un template:
Template (@stxt.template): com.example.servidores
Structure >>
Servidor (com.example.servidores): GROUP
Nombre: (1)
Activo: (1) BOOLEAN
Puertos: (1) GROUP
Puerto: (+) NATURAL
Responsable: (?) GROUP
Persona: (1)
Correo: (1) EMAIL
Notas: (?) TEXT3.1 Exportación
La exportación del documento a JSON:
{
"Nombre": "web-01",
"Activo": true,
"Puertos": [80, 443],
"Responsable": {
"Persona": "Ana Ruiz",
"Correo": "ana@example.com"
},
"Notas": "Reiniciar tras cada despliegue.\nNo apagar en horario de oficina."
}
Lo que decide la definición:
| En el documento | En la definición | En JSON |
|---|---|---|
Nombre: web-01 |
Sin tipo | Un string |
Activo: true |
BOOLEAN |
Un booleano |
Puerto: 80 |
NATURAL |
Un número |
Puertos, con dos Puerto |
GROUP con un solo hijo, que se repite |
Un array. El nombre Puerto no aparece |
Responsable, con dos hijos |
GROUP con hijos distintos |
Un objeto, con una clave por hijo |
Notas >> |
TEXT |
Un string, con las líneas separadas por \n |
- Sin definición,
80ytrueserían texto, y nada distinguiría una lista de un nodo con un solo hijo. - El comentario no se exporta: no forma parte del árbol del documento.
- El nodo raíz no aparece: el JSON es el contenido de
Servidor.
Como contraste, el nodo Puertos en el árbol canónico de
STXT-TREE-SPEC, que en la exportación es [80, 443]:
{
"name": "Puertos",
"canonicalName": "puertos",
"namespace": "com.example.servidores",
"form": "inline",
"value": "",
"children": [
{
"name": "Puerto",
"canonicalName": "puerto",
"namespace": "com.example.servidores",
"form": "inline",
"value": "80",
"children": []
},
{
"name": "Puerto",
"canonicalName": "puerto",
"namespace": "com.example.servidores",
"form": "inline",
"value": "443",
"children": []
}
]
}
3.2 Importación
La importación es el camino inverso. Recibe el JSON anterior y el nodo raíz que debe
producir, Servidor (com.example.servidores), y devuelve este documento:
Servidor (com.example.servidores):
Nombre: web-01
Activo: true
Puertos:
Puerto: 80
Puerto: 443
Responsable:
Persona: Ana Ruiz
Correo: ana@example.com
Notas >>
Reiniciar tras cada despliegue.
No apagar en horario de oficina.La definición aporta lo que el JSON no lleva:
- El nombre
Puertode cada elemento del arrayPuertos. - El namespace de cada nodo.
- La forma de cada nodo. Si la definición solo admite una, es esa. Si admite las dos, como
TEXT, se elige la que pierde menos: bloque si el texto tiene saltos de línea o empieza por blancos, que un valor inline recortaría; inline en los demás casos.Notasse escribe como bloque>>porque su texto tiene más de una línea.
La importación acepta un string, un número o un booleano como valor de cualquier nodo sin
hijos, sea cual sea su tipo en la definición, y lo escribe como texto: Puerto recibe lo
mismo de 80 que de "80". Así se importan también los datos de formatos sin tipos, como
NestedText, en los que todo valor es un string. Lo que no encaja con su tipo, como "abc"
en Puerto, lo rechaza la validación del documento importado.
El documento importado tiene el mismo árbol que el original. Solo se ha perdido el comentario.
4. Un ejemplo: relleno de Slots
Esta sección no es normativa. Es un primer esbozo de los Slots y de cómo se combinan: un ejemplo completo y, después, las reglas que sigue, agrupadas por temas.
4.1 El ejemplo
Un documento con Slots:
Pedido (com.example.pedidos): <numero>
Fecha: <fecha>
Moneda: EUR
Cliente: {cliente}
Nombre: <nombre>
Correo: <correo>
# El teléfono es opcional
Teléfono: <?telefono>
Línea: [lineas]<producto>
Cantidad: <cantidad>
Precio: <precio>
Nota: <?nota>
Envío: [envios]
Transportista: <transportista>
Referencia: ${numero}/${transportista}
Bulto: [bultos]
Instrucciones >>
Pedido ${numero}, con fecha ${fecha}.
Entregar por la mañana.
Etiqueta >>
[envios]
Pedido ${numero}
Transportista: ${transportista}Los datos, en JSON:
{
"numero": "2026-0142",
"fecha": "2026-10-12",
"cliente": {
"nombre": "Librería Atenea",
"correo": "pedidos@atenea.example"
},
"lineas": [
{ "producto": "Cuaderno A5", "cantidad": 40, "precio": 3.25, "nota": "Tapa azul" },
{ "producto": "Lápiz HB", "cantidad": 200, "precio": 0.45 }
],
"envios": [
{ "transportista": "Correos", "bultos": ["C-01", "C-02"] },
{ "transportista": "MRW", "bultos": ["M-07"] }
]
}
Y el documento que produce el relleno:
Pedido (com.example.pedidos): 2026-0142
Fecha: 2026-10-12
Moneda: EUR
Cliente:
Nombre: Librería Atenea
Correo: pedidos@atenea.example
Línea: Cuaderno A5
Cantidad: 40
Precio: 3.25
Nota: Tapa azul
Línea: Lápiz HB
Cantidad: 200
Precio: 0.45
Envío:
Transportista: Correos
Referencia: 2026-0142/Correos
Bulto: C-01
Bulto: C-02
Envío:
Transportista: MRW
Referencia: 2026-0142/MRW
Bulto: M-07
Instrucciones >>
Pedido 2026-0142, con fecha 2026-10-12.
Entregar por la mañana.
Etiqueta >>
Pedido 2026-0142
Transportista: Correos
Etiqueta >>
Pedido 2026-0142
Transportista: MRWLínea y Envío se repiten una vez por elemento, y cada Envío busca su transportista
y sus bultos en su propio elemento; ${numero} lo encuentra en la raíz de los datos.
Teléfono no sale porque el cliente no tiene telefono, y la navegación no lo busca en la
raíz. Nota sale en la primera Línea y no en la segunda.
4.2 Los Slots
| Slot | Qué hace | En el ejemplo |
|---|---|---|
[lista] |
Repite el nodo, con sus hijos, una vez por cada elemento del array lista |
Línea, Envío, Bulto |
{objeto} |
Entra en el objeto objeto: los Slots del nodo y de sus hijos se buscan dentro de él |
Cliente: {cliente} |
<var> |
Pone el dato var como valor del nodo; cierra el valor |
Fecha: <fecha> |
${var} |
Pone el dato var dentro de un texto |
Referencia: ${numero}/${transportista} |
? |
Hace opcional el Slot (§4.7) | Teléfono: <?telefono> |
Los tres primeros son la navegación del nodo y van al principio de su valor; ${var} va
en el texto que la sigue.
- El nombre de un Slot tiene al menos un carácter, y solo letras ASCII, dígitos,
-y_:<numero>,[lineas],{datos-cliente},${id_2}. Se busca tal cual entre las claves de los datos, distinguiendo mayúsculas y minúsculas:<Fecha>no encuentrafecha.
4.3 Navegación
- El valor de un nodo con Slots empieza por su navegación:
[lista]y{objeto}, tantos como hagan falta y en cualquier orden, y como mucho un<var>al final. Se aplican de izquierda a derecha, y cada uno repite o entra sobre lo que deja el anterior:Dirección: {cliente}[direcciones]entra en el cliente y repite el nodo por cada una de sus direcciones. Puede haber blancos entre ellos y antes del texto:{cliente} [direcciones]es lo mismo que{cliente}[direcciones]. Lo que sigue es texto (§4.4). <var>pone el dato como valor del nodo y cierra el valor: detrás solo puede haber blancos.Línea: [lineas]<producto>repite el nodo y pone en cada uno suproducto;Línea: [lineas]<producto> (uds.)yLínea: <producto>[lineas]son errores. El nodo puede tener hijos:Pedido: <numero>tieneFecha,Clientey los demás.- Si el elemento de un array es un objeto, el relleno entra en él. Si es un valor, es el valor del nodo:
Bulto: [bultos]produceBulto: C-01yBulto: C-02. Ese nodo no puede tener nada más que la navegación: ni texto, ni hijos, ni más líneas de bloque, ni otra navegación detrás. Sibultostrae valores,Bulto: [bultos] (caja),Bulto: [bultos]con un hijoPeso: <peso>,Bulto: [bultos]{medidas}yBulto: [bultos]<peso>son errores.
4.4 Texto
- En el texto,
${var}pone un dato, y un valor puede llevar varios:Referencia: ${numero}/${transportista}produceReferencia: 2026-0142/Correos. Todo lo que tiene la forma${nombre}es un Slot, también en un bloque:echo "${HOME}"espera un datoHOME.Fecha: ${fecha}produce lo mismo queFecha: <fecha>cuando el dato está en el elemento en curso; si está más arriba, solo lo encuentra${fecha}(§4.6). - Para escribir
${como texto se escribe$${:echo "$${HOME}"produceecho "${HOME}". Es el único escape. Un$$que no va seguido de{se copia tal cual. - El resto del texto se copia tal cual: un valor sin Slots (
Moneda: EUR), lo que no tiene forma de Slot (${},${a b}) y también<x>,[x]y{x}, que en el texto no repiten, ni entran, ni ponen un valor.Etiqueta: Ver [nota]se copia tal cual, y en un bloque con HTML o XML<p>y<br>son texto.
4.5 Bloques
- En un bloque
>>, la primera línea hace el papel del principio del valor. Si empieza por[lista],{objeto}o<var>, es la navegación del nodo: tiene que ser navegación válida entera, sin nada más, se aplica igual que en un nodo inline y no pasa al documento rellenado.Etiqueta >>empieza con[envios]y produce un bloque por envío. Si la primera línea empieza por cualquier otra cosa, todo el bloque es texto, también los[lista],{objeto}y<var>de cualquiera de sus líneas.
| Primera línea | Resultado |
|---|---|
[envios], {cliente} [direcciones], <?notas> |
Navegación |
[envios] Pedido, <numero> Pedido, {cliente} ${nombre}, [parece]{navegacion} x |
Error: hay algo detrás de la navegación |
Un enlace de Markdown, como [Inicio](index); <html> o <p>Hola</p> en un bloque HTML |
Error: empiezan por algo con forma de Slot |
<!DOCTYPE html>, <html lang="es">, <?xml version="1.0"?>, Ver <b>[nota]</b> |
Texto: no empiezan por un Slot de navegación |
<var>pone el dato como contenido del bloque y cierra el valor, igual que en un nodo inline: el bloque no puede tener más líneas. Un bloqueNotas >>cuya única línea es<?notas>pone las notas, con sus saltos de línea, o quita el nodo si no hay notas; con la línea${notas}produce lo mismo cuando hay dato.- En el texto de un bloque, cada
${var}se sustituye por su dato y el resto se copia tal cual: dentro del bloque,Transportista: ${transportista}es texto, no un nodo.
4.6 Los datos
- La navegación busca su dato solo en el elemento en curso: la raíz de los datos, o el objeto o el elemento de array en el que ha entrado la navegación anterior, del propio nodo o de los que lo contienen. Si los datos tuvieran una
notaen la raíz,Nota: <?nota>no la cogería, y la segundaLíneaseguiría sinNota. ${var}busca su dato primero en el elemento en curso y, si la clave no está, va subiendo: el objeto o el elemento que lo contiene, y así hasta la raíz de los datos. Así encuentra cadaEnvíoelnumerodeReferencia: ${numero}/${transportista}.- Un dato que vale
nullcuenta como ausente. En el texto, además, termina la búsqueda:${?nota}en un elemento con"nota": nullno pone nada, aunque haya unanotamás arriba. - Un array vacío no produce ningún nodo y no es un error del relleno: si el nodo era obligatorio, lo dirá la validación del documento rellenado. Un elemento
nulles como si no estuviera: no produce ningún nodo. Un array que mezcla valores y objetos es un error, y también un array dentro de otro array. - Un dato que no encaja con su Slot es un error: un objeto donde
<var>o${var}esperan un valor, o un valor donde[lista]espera un array.
4.7 Slots opcionales
- Todo Slot es obligatorio salvo que lleve
?justo detrás del delimitador de apertura:[?lista],{?objeto},<?var>y${?var}. Si una línea no tuvieracantidad, o si faltaracliente, el relleno fallaría. Un?fuera de los delimitadores es texto:Nota: ?<nota>se copia tal cual, yEnlace: https://example.com/buscar?${consulta}conserva su?. - Sin dato,
[?lista],{?objeto}y<?var>quitan el nodo, con sus hijos.${?var}solo quita su trozo, y el resto del texto y el nodo se quedan:Referencia: ${numero}${?revision}produceReferencia: 2026-0142si no hayrevision, yTeléfono: ${?telefono}daríaTeléfono:vacío. Solo la navegación decide si un nodo aparece y cuántas veces.
4.8 El documento rellenado
- El nodo rellenado tiene la forma que tiene en el documento con Slots:
Nodo: <var>sale inline yNodo >>sale como bloque. Un dato con saltos de línea en un nodo inline es un error. En un bloque, produce varias líneas. - El documento rellenado tiene el árbol que daría su texto al parsearlo, con los valores normalizados como en cualquier documento: un valor inline sin blancos al principio ni al final (STXT-SPEC §5.1), y un bloque sin blancos al final de sus líneas ni líneas vacías al final (§10.2 y §10.3). Vale igual para lo que pone el dato que para el texto que lo rodea:
A: ${t} ${?falta}sinfaltadejaA: x, sin el blanco final. Los blancos del principio de una línea de bloque y las líneas vacías intermedias son contenido y se conservan. - El comentario no pasa al documento rellenado.
- Un documento con Slots no se valida. El que se valida es siempre el documento rellenado.