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 del documento a una estructura jerárquica STXT.
2. Resolución del namespace efectivo de cada nodo.
3. Aplicación del schema correspondiente.

Una implementación PUEDE aplicar la validación durante el proceso de parseo, siempre que dicha validación permanezca débilmente acoplada al parser base. Esto permite detectar errores antes de finalizar el parseo completo.

4. Estructura general de un Esquema

Un documento schema DEBE tener como nodo raíz:

Schema (@stxt.schema): <namespace_objetivo>

Reglas:

• <namespace_objetivo> DEBE ser un namespace válido según STXT-SPEC.
• El nodo raíz Schema DEBE pertenecer al namespace @stxt.schema.
• El documento schema PUEDE incluir un nodo Description.
• El documento schema DEBE incluir uno o más nodos Node.

Ejemplo:

Schema (@stxt.schema): com.example.docs
    Description: Schema de ejemplo
    Node: Document
        Type: GROUP
        Children:
        	Child: Autor
        	Child: Fecha
        		Max: 1
        	Child: Content
        		Min: 1
        		Max: 1
        	Child: Metadata (org.example.meta)
        		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 efectivo simultáneamente.
• Si una implementación dispone de varios schemas candidatos para el mismo namespace, DEBERÍA aplicar una política de selección clara y determinista.
• Para una validación concreta, sólo DEBE existir un único schema efectivo.

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

6.1 Forma básica

Node: Nombre Nodo
	Description: Descripción del nodo
    Type: Tipo
    Children:
    	Child: Nombre Hijo. Puede incluir un namespace si es distinto del namespace objetivo
    		Min: opcional, indica el número mínimo de hijos que pueden aparecer
    		Max: opcional, indica el número máximo de hijos que pueden aparecer

Reglas:

• El valor inline de Node DEBE ser un nombre de nodo válido según STXT-SPEC.
• Cada Node DEBE ser único dentro del schema a nivel de nombre canónico.
• Cada Node define la semántica del nodo en el namespace objetivo del schema.
• Si Type se omite, el tipo por defecto es INLINE.
• Un Node NO DEBE contener más de un nodo Description, más de un nodo Type, más de un nodo Children ni más de un nodo Values.

6.2 Valores en tipos ENUM

Node: Nombre Nodo
	Description: Descripción del nodo
    Type: ENUM
    Children:
    	Child: Nombre Hijo. Puede incluir un namespace si es distinto del namespace objetivo
    		Min: opcional, indica el número mínimo de hijos que pueden aparecer
    		Max: opcional, indica el número máximo de hijos 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 mediante nodos Value. Si existe Values, DEBE contener al menos un nodo Value. Si un Node declara Type: ENUM, DEBE incluir Values.

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

Un nodo PUEDE tener una entrada Children. Si existe Children, DEBE contener uno o más nodos Child con la información de los hijos permitidos.

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

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

• Si se omite el namespace, el Child pertenece al namespace objetivo del schema actual.
• Si se indica un namespace explícito, el Child pertenece a ese namespace concreto.
• Dentro de un mismo nodo Children, una implementación NO DEBE aceptar dos nodos Child que apunten al mismo par lógico nombre canónico + namespace efectivo.

7.1 Nodos definidos explícitamente

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 Child: Metadata (org.example.meta), entonces DEBE existir un schema para org.example.meta y dentro de él DEBE existir Node: Metadata.
• Una implementación PUEDE diferir esta comprobación hasta el momento de validación del documento, pero el schema sigue siendo semánticamente incompleto hasta que dicha definición exista.

8. Cardinalidades

Las cardinalidades se expresan mediante los nodos Min y Max dentro de cada Child. Son enteros no negativos opcionales que indican el número mínimo o máximo de apariciones permitidas de ese hijo.

Reglas:

• Si Min se omite, el mínimo efectivo es 0.
• Si Max se omite, el máximo efectivo es ilimitado.
• Min y Max NO DEBEN aparecer más de una vez dentro del mismo Child.
• Si existen ambos, Min NO DEBE ser mayor que Max.
• La cardinalidad se aplica por instancia del nodo padre.
• La cardinalidad cuenta sólo hijos directos con el mismo nombre canónico y el mismo namespace efectivo.
• Una implementación 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 dentro de Node, mediante un elemento Type. Ejemplo:

Node: nombre del nodo
	Type: TIPO_DEL_NODO
	Children:
		Child: Nombre Hijo

Otras consideraciones:

• El tipo NO controla obligatoriedad; sólo forma y validez del valor. La obligatoriedad de aparición se controla mediante cardinalidad.
• El valor de Type DEBE coincidir exactamente con uno de los tipos definidos en esta sección.
• Los tipos que admiten sólo forma BLOCK o INLINE/BLOCK y se definen como no compatibles con hijos NO DEBEN coexistir con Children.
• Una definición incompatible entre Type y Children DEBE provocar un error de schema.

9.1. Tipos estructurales básicos

Una implementación conforme DEBE admitir estos tipos y DEBE validar su estructura.

9.2. Tipos Básicos de contenido INLINE

Una implementación conforme DEBE admitir estos tipos y DEBE validar su estructura.

9.3. Tipos ampliados de contenido INLINE

Una implementación conforme DEBE admitir estos tipos y DEBERÍA validar su estructura.

9.4. Tipos ampliados de contenido binario INLINE/BLOCK

Una implementación conforme DEBE admitir estos tipos y PUEDE validar su estructura.

9.5. Tipo ENUM

El tipo ENUM permite enumerar de forma explícita los valores permitidos para un nodo. Reglas:

• La comparación DEBE hacerse sobre el valor inline ya normalizado mediante trim a izquierda y derecha, tal como define STXT-SPEC.
• La comparación DEBE ser exacta y CASE-SENSITIVE.
• La comparación NO DEBE aplicar canonización adicional, eliminación de diacríticos ni normalizaciones equivalentes al nombre canónico de los nodos.
• El nodo DEBE definir Values con nodos Value, que representan los valores permitidos.
• Cada Value DEBE ser único tras la normalización inline por trim.

Ejemplo:

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

Una implementación conforme DEBE comprobar los tipos ENUM contra sus valores permitidos y DEBE rechazar cualquier valor que no coincida exactamente con uno de ellos.

10. Ejemplos Normativos

10.1. Schema con referencias cross-namespace

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

Y en org.example.meta:

Schema (@stxt.schema): org.example.meta
    Node: Metadata
    	Type: INLINE

10.2. Documento válido

Document (com.example.docs):
    Metadata (org.example.meta): 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 canónico.
2. Usa un Type desconocido.
3. Define Children en un Node cuyo tipo no permite hijos.
4. La cardinalidad es inválida.
5. Un Node: ENUM no define Values, o Values no contiene ningún Value.
6. Aparece un Value duplicado tras la normalización inline por trim.
7. Aparecen dos nodos Child equivalentes dentro del mismo Children.
8. 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.
• Selecciona, para cada validación, un único schema efectivo por namespace.
• 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
    • Values
• 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.
• Cada Values:
  • Sólo puede aparecer en nodos Node de tipo ENUM.
  • Contiene uno o más nodos Value.
• Los nombres (Schema, Node, Type, Children, Child, Description, Min, Max, Values, Value) 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
        Type: ENUM
        Values:
            Value: INLINE
            Value: BLOCK
            Value: TEXT
            Value: GROUP
            Value: BOOLEAN
            Value: NUMBER
            Value: ENUM
            Value: INTEGER
            Value: NATURAL
            Value: DATE
            Value: TIME
            Value: TIMESTAMP
            Value: UUID
            Value: URL
            Value: EMAIL
            Value: HEXADECIMAL
            Value: BINARY
            Value: BASE64
    Node: Values
        Type: GROUP
        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 GROUP: contiene uno o más nodos Child.

• Description TEXT: puede ser inline o multiline.

• Values GROUP: contiene uno o más nodos Value.

• Value Valor inline con uno de los valores permitidos para el ENUM.

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: Schema de ejemplo
    Node: Document
        Type: GROUP
        Children:
        	Child: Title
        		Min: 1
        		Max: 1
        	Child: Author
        	Child: Metadata (org.example.meta)
        		Max: 1
    Node: Title
        Type: INLINE
    Node: Author
        Type: INLINE

14. Fin del Documento