STXT Esquemas (@stxt.schema)

1. Introducción

Este documento define la especificación del lenguaje STXT Schema, un mecanismo para validar documentos STXT mediante reglas semánticas formales.

Un schema:

• Es un documento STXT con namespace @stxt.schema.
• Define los nodos, tipos y cardinalidades del namespace objetivo.
• No modifica la sintaxis base de STXT; opera sobre la estructura ya parseada.

2. Terminología

Las palabras clave "DEBE", "NO DEBE", "DEBERÍA", "NO DEBERÍA", y "PUEDE" deben interpretarse según RFC 2119.

Términos como nodo, indentación, namespace, inline y bloque >> mantienen su significado en STXT-SPEC.

3. Relación entre STXT y Schema

La validación mediante schema ocurre después del parseo STXT:

1. Parseo a estructura jerárquica STXT.
2. Resolución del namespace lógico (herencia).
3. Aplicación del schema correspondiente.

Opcionalmente PUEDE actuar durante el proceso de parseo, siempre y cuando esté débilmente acoplado con él. De esta forma los errores pueden ser detectados previamente.

4. Estructura general de un Schema

Un schema es un documento cuyo nodo raíz es: Schema (@stxt.schema): <namespace_objetivo>

Ejemplo:

Schema (@stxt.schema): com.example.docs
    Description: Schema for example documents
    Node: Document
        Type: GROUP
        Children:
        	Child: Metadata (@com.google.html)
        		Max: 1
        	Child: Autor
        	Child: Fecha
        		Max: 1
        	Child: Content
        		Min: 1
        		Max: 1
    Node: Autor
    Node: Fecha
        Type: DATE
    Node: Content
        Type: TEXT

5. Un schema por namespace

Para cada namespace lógico:

• NO DEBE existir más de un schema activo simultáneamente.
• Si existen varios schemas para el mismo namespace, el parser DEBERÍA establecer un criterio claro para saber cual de ellos está aplicando, pero nunca aplicar varios de forma simultánea.

6. Definición de Nodos (`Node:`)

6.1 Forma básica

Node: Nombre Nodo
	Descrip: Descripción del nodo
    Type: Tipo
    Children:
    	Child: name_child. Puede tener un namespace en caso que sea distinto al namespace destino
    		Min: opcional, indica el número mínimo de childs que pueden aparecer
    		Max: opcional, indica el número máximo de childs que pueden aparecer

Reglas:

• Nombre Nodo DEBE ser único dentro del schema.
• Cada Node define la semántica del nodo en el namespace objetivo.
• Si Type se omite, tipo por defecto es INLINE.

6.2 Valores en tipos ENUM

Node: Nombre Nodo
	Descrip: Descripción del nodo
    Type: ENUM
    Children:
    	Child: name_child. Puede tener un namespace en caso que sea distinto al namespace destino
    		Min: opcional, indica el número mínimo de childs que pueden aparecer
    		Max: opcional, indica el número máximo de childs que pueden aparecer
    Values:
    	Value: valor 1
    	Value: valor 2
    	Value: valor 3

El tipo ENUM (y sólo ENUM) puede especificar un nodo Values con los valores permitidos (Nodos Value). Al menos debe existir un Value.

7. Hijos (`Children:`) y namespaces cruzados

Un nodo puede tener una entrada Children. En caso de tenerla debe tener uno o más nodos Child, con la información de los childs permitidos.

Un Child puede pertenecer a otro namespace, en cuyo caso se indica en el nombre del child. Ejemplo:

Node: nombre del nodo
	Children:
		Child: nombre del child (namespace.del.child)
			Min: 0
			Max: 1

• Si se omite el namespace se asume el namespace objetivo del schema.
• Si se indica: el hijo pertenece a ese namespace concreto. La definición será hecha en otro documento de esquema.

7.1. Nodos deben estar explícitamente mostrados en schemas.

Todo nodo que aparezca en Children debe tener una definición propia como Node: en su schema correspondiente.

Así evitamos hijos “fantasma” y garantizamos que todos los nodos tienen semántica definida.

Esto implica:

• Si aparece: (1) Metadata (@com.google.html) entonces **debe existir un schema para com.google.htmly dentro de él debe existirNode: Metadata`**. No es necesario la validación en ese momento, pero sí al validar un documento para ese namespace.

8. Cardinalidades

Las cardinalidades se hacen mediante los nodos Min y Max de Child. Serán enteros no negativos opcionales. En caso de existir indican el número mínimo o máximo de apariciones del child.

Reglas:

• Se aplica por instancia del nodo padre.
• Cuenta solo hijos directos con nombre + namespace efectivo.
• Un validador conforme DEBE comprobar las cardinalidades.

9. Tipos

Los tipos definen:

1. La forma del valor del nodo (inline, bloque >>, o ninguno).
2. Si el nodo es compatible con hijos.
3. La validación del contenido.

Se definen el Nodo, con un elemento Type. Ejemplo:

Node: nombre del nodo
	Type: TIPO_DEL_NODO
	Children:
		Child: a child name

Otras consideraciones:

• El tipo NO controla obligatoriedad, solo forma y validez del valor. La obligatoriedad de aparición se controla mediante cardinalidad.
• Tipos BLOCK-only (TEXT, CODE, BASE64,...) NO SON COMPATIBLES con hijos, y una definición de hijos (Children) DEBE dar un error de parseo.

9.1. Tipos estructurales básicos

Un parser DEBE permitir estos tipos y DEBE validar la estructura.

9.2. Tipos Básicos de contenido INLINE

Un parser DEBE permitir estos tipos y DEBERÍA validar la estructura.

9.3. Tipos ampliados de contenido INLINE

Un parser DEBERÍA permitir estos tipos y DEBERÍA validar la estructura.

9.4 Tipos de contenido Binario INLINE/BLOCK

Un parser DEBERÍA permitir estos tipos y PUEDE validar la estructura.

9.5 Tipo ENUM

El tipo ENUM es especial, ya que permite enumerar los valores permitidos para ese nodo. Características:

• La comprobación será CASE-SENSITIVE
• Al ser valores inline se aplicará trim a izquierda y derecha.
• El nodo debe definir Values con nodos Value, que representan los valores permitidos.

Ejemplo:

Node: Nombre Nodo
    Type: ENUM
    Values:
    	Value: valor 1
    	Value: valor 2
    	Value: valor 3

Un parseador de esquemas DEBE comprobar los tipos ENUM con sus valores permitidos, y lanzar errores si no se cumplen.

10. Ejemplos Normativos

10.1. Schema con referencias cross-namespace

Schema (@stxt.schema): com.example.docs
    Node: Document
        Type: GROUP
        Children:
            Child: Metadata (@com.google.html)
            	Max: 1
            Child: Content
            	Min: 1
            	Max: 1
    Node: Content
        Type: BLOCK

Y en com.google.html:

Schema (@stxt.schema): com.google.html
    Node: Metadata
    	Type: INLINE

10.2. Documento válido

Document (@com.example.docs):
    Metadata (@com.google.html): info
    Content>>
        Línea 1
        Línea 2

11. Errores de Schema

Un schema es inválido si:

1. Define dos Node con el mismo nombre.
2. Usa un Type desconocido.
3. Define Children en un Node cuyo tipo no permite hijos.
4. La cardinalidad es inválida.
5. Aparece un hijo en Children cuyo Node no está definido en su schema correspondiente.

12. Conformidad

Una implementación es conforme si:

• Implementa íntegramente este documento.
• Valida tipos, formas de valor, cardinalidades y valores permitidos (ENUM).
• Aplica la regla estricta de definición obligatoria de todos los nodos referenciados en Children.
• Rechaza documentos y schemas inválidos.

13. Schema del Schema (`@stxt.schema`)

Esta sección define el schema oficial del propio sistema de schemas: el meta-schema que valida todos los documentos del namespace @stxt.schema.

13.1. Consideraciones

• Todo documento schema es: Schema (@stxt.schema): <namespace-objetivo>
• Un schema contiene:
  • Opcionalmente una Description.
  • Uno o más nodos Node.
• Cada Node:
  • Tiene valor inline (el nombre del nodo del namespace objetivo).
  • Puede tener opcionalmente:
    • Description
    • Type
    • Children
    • Child
• Cada Child (elemento de Children) define el nombre (y opcionalmente un namespace distinto) y pueden tener:
  • Min: Número mínimo de nodos que deben aparecer. Si no existe el nodo no hay un mínimo establecido.
  • Max: Número máximo de nodos que pueden aparecer. Si no existe el nodo no hay un máximo establecido.
  • Values: Sólo para ENUM, con nodos Value con los valores permitidos.
• Los nombres (Schema, Node, Type, Children, Child, Description, Min, Max) pertenecen al namespace @stxt.schema`.

13.2. Meta-Schema completo

Schema (@stxt.schema): @stxt.schema
    Node: Schema
        Children:
            Child: Description
                Max: 1
            Child: Node
                Min: 1
    Node: Node
        Children:
            Child: Type
                Max: 1
            Child: Children
                Max: 1
            Child: Description
                Max: 1
            Child: Values
                Max: 1
    Node: Children
       	Type: GROUP
        Children:
            Child: Child
                Min: 1
    Node: Description
        Type: TEXT
    Node: Child
        Children:
            Child: Min
                Max: 1
            Child: Max
                Max: 1
    Node: Min
        Type: NATURAL
    Node: Max
        Type: NATURAL
    Node: Type
    Node: Values
    	Children:
    		Child: Value
    			Min: 1
    Node: Value

13.3. Lectura rápida

• Schema Valor inline = namespace objetivo (ej. com.example.docs). Hijos: Description (?), Node (*).

• Node Valor inline = nombre del nodo objetivo (ej. Document, Autor). Hijos opcionales:

  • Type: tipo concreto (si falta ⇒ INLINE).
  • Children: Nodo con listado de Child permitidos
  • Description: texto explicativo.
  • Values: Valores permitidos (sólo tipo ENUM)

• Type Inline (INLINE), con el nombre del tipo (GROUP, INLINE, NUMBER, etc.).

• Children BLOCK: contiene literalmente el bloque Childs>>.

• Description TEXT: puede ser inline o multiline.

13.4. Ejemplo mínimo válido

Schema (@stxt.schema): com.example.docs
    Node: Document

13.5. Ejemplo completo

Schema (@stxt.schema): com.example.docs
    Description: Example schema
    Node: Document
        Type: GROUP
        Children:
        	Child: Title
        		Min: 1
        		Max: 1
        	Child: Author
        	Child: Metadata (@com.google.html)
        		Max: 1
    Node: Title
        Type: INLINE
    Node: Author
        Type: INLINE

14. Fin del Documento