STXT Transform

Estado:
Genesis
última modificación:
2026-10-25

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: (?) TEXT

3.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, 80 y true serí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 Puerto de cada elemento del array Puertos.
  • 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. Notas se 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: MRW

Lí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 encuentra fecha.

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 su producto; Línea: [lineas]<producto> (uds.) y Línea: <producto>[lineas] son errores. El nodo puede tener hijos: Pedido: <numero> tiene Fecha, Cliente y 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] produce Bulto: C-01 y Bulto: 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. Si bultos trae valores, Bulto: [bultos] (caja), Bulto: [bultos] con un hijo Peso: <peso>, Bulto: [bultos]{medidas} y Bulto: [bultos]<peso> son errores.

4.4 Texto

  • En el texto, ${var} pone un dato, y un valor puede llevar varios: Referencia: ${numero}/${transportista} produce Referencia: 2026-0142/Correos. Todo lo que tiene la forma ${nombre} es un Slot, también en un bloque: echo "${HOME}" espera un dato HOME. Fecha: ${fecha} produce lo mismo que Fecha: <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}" produce echo "${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 bloque Notas >> 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 nota en la raíz, Nota: <?nota> no la cogería, y la segunda Línea seguiría sin Nota.
  • ${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 cada Envío el numero de Referencia: ${numero}/${transportista}.
  • Un dato que vale null cuenta como ausente. En el texto, además, termina la búsqueda: ${?nota} en un elemento con "nota": null no pone nada, aunque haya una nota má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 null es 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 tuviera cantidad, o si faltara cliente, el relleno fallaría. Un ? fuera de los delimitadores es texto: Nota: ?<nota> se copia tal cual, y Enlace: 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} produce Referencia: 2026-0142 si no hay revision, y Teléfono: ${?telefono} daría Telé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 y Nodo >> 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} sin falta deja A: 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.