STXT Schemas (@stxt.schema)

1. Introduction

This document defines the specification of the STXT Schema language, a mechanism for validating STXT documents through formal semantic rules.

A schema:

• Is an STXT document with namespace @stxt.schema.
• Defines the nodes, types, and cardinalities of the target namespace.
• Does not modify the base syntax of STXT; it operates on the already parsed structure.

2. Terminology

The keywords "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" must be interpreted according to RFC 2119.

Terms such as node, indentation, namespace, inline and >> block retain their meaning in STXT-SPEC.

3. Relationship between STXT and Schema

Validation through schema occurs after STXT parsing:

1. Parsing the document into a hierarchical STXT structure.
2. Resolving the effective namespace of each node.
3. Applying the corresponding schema.

An implementation MAY apply validation during the parsing process, provided that such validation remains loosely coupled to the base parser. This allows errors to be detected before the full parsing is completed.

4. General Structure of a Schema

A schema document MUST have as its root node:

Schema (@stxt.schema): <target_namespace>

Rules:

• <target_namespace> MUST be a valid namespace according to STXT-SPEC.
• The root node Schema MUST belong to the @stxt.schema namespace.
• The schema document MAY include a Description node.
• The schema document MUST include one or more Node nodes.

Example:

Schema (@stxt.schema): com.example.docs
    Description: Example schema
    Node: Document
        Type: GROUP
        Children:
        	Child: Author
        	Child: Date
        		Max: 1
        	Child: Content
        		Min: 1
        		Max: 1
        	Child: Metadata (org.example.meta)
        		Max: 1
    Node: Author
    Node: Date
        Type: DATE
    Node: Content
        Type: TEXT

5. One schema per namespace

For each logical namespace:

• There MUST NOT be more than one effective schema simultaneously.
• If an implementation has several candidate schemas for the same namespace, it SHOULD apply a clear and deterministic selection policy.
• For a specific validation, there MUST be only one effective schema.

6. Node Definition (`Node:`)

6.1 Basic form

Node: Node Name
	Description: Node description
    Type: Type
    Children:
    	Child: Child Name. It may include a namespace if it is different from the target namespace
    		Min: optional, indicates the minimum number of children that may appear
    		Max: optional, indicates the maximum number of children that may appear

Rules:

• The inline value of Node MUST be a valid node name according to STXT-SPEC.
• Each Node MUST be unique within the schema at the canonical name level.
• Each Node defines the semantics of the node in the schema's target namespace.
• If Type is omitted, the default type is INLINE.
• A Node MUST NOT contain more than one Description node, more than one Type node, more than one Children node, nor more than one Values node.

6.2 Values in ENUM types

Node: Node Name
	Description: Node description
    Type: ENUM
    Children:
    	Child: Child Name. It may include a namespace if it is different from the target namespace
    		Min: optional, indicates the minimum number of children that may appear
    		Max: optional, indicates the maximum number of children that may appear
    Values:
    	Value: value 1
    	Value: value 2
    	Value: value 3

The ENUM type, and only ENUM, MAY specify a Values node with the allowed values through Value nodes. If Values exists, it MUST contain at least one Value node. If a Node declares Type: ENUM, it MUST include Values.

7. Children (`Children:`) and cross-namespace references

A node MAY have a Children entry. If Children exists, it MUST contain one or more Child nodes with the information about the allowed children.

A Child MAY belong to another namespace, in which case it is indicated in the name of the Child itself. Example:

Node: node name
	Children:
		Child: child name (child.namespace)
			Min: 0
			Max: 1

• If the namespace is omitted, the Child belongs to the target namespace of the current schema.
• If an explicit namespace is indicated, the Child belongs to that specific namespace.
• Within the same Children node, an implementation MUST NOT accept two Child nodes that point to the same logical pair canonical name + effective namespace.

7.1 Explicitly defined nodes

Every node that appears in Children must have its own definition as Node: in its corresponding schema.

This avoids “ghost” children and guarantees that all nodes have defined semantics.

This implies:

• If Child: Metadata (org.example.meta) appears, then there MUST be a schema for org.example.meta and within it there MUST be Node: Metadata.
• An implementation MAY defer this check until the moment of document validation, but the schema remains semantically incomplete until that definition exists.

8. Cardinalities

Cardinalities are expressed through the Min and Max nodes within each Child. They are optional non-negative integers that indicate the minimum or maximum number of allowed occurrences of that child.

Rules:

• If Min is omitted, the effective minimum is 0.
• If Max is omitted, the effective maximum is unlimited.
• Min and Max MUST NOT appear more than once within the same Child.
• If both exist, Min MUST NOT be greater than Max.
• Cardinality applies per instance of the parent node.
• Cardinality counts only direct children with the same canonical name and the same effective namespace.
• A conforming implementation MUST check cardinalities.

9. Types

Types define:

1. The form of the node value (inline, >> block, or none).
2. Whether the node is compatible with children.
3. Content validation.

They are defined within Node, through a Type element. Example:

Node: node name
	Type: NODE_TYPE
	Children:
		Child: Child Name

Other considerations:

• The type does NOT control requiredness; only the form and validity of the value. Requiredness of appearance is controlled through cardinality.
• The value of Type MUST match exactly one of the types defined in this section.
• Types that allow only BLOCK or INLINE/BLOCK form and are defined as not compatible with children MUST NOT coexist with Children.
• An incompatible definition between Type and Children MUST cause a schema error.

9.1. Basic structural types

A conforming implementation MUST support these types and MUST validate their structure.

9.2. Basic INLINE content types

A conforming implementation MUST support these types and MUST validate their structure.

9.3. Extended INLINE content types

A conforming implementation MUST support these types and SHOULD validate their structure.

9.4. Extended INLINE/BLOCK binary content types

A conforming implementation MUST support these types and MAY validate their structure.

9.5. ENUM type

The ENUM type allows explicitly enumerating the allowed values for a node. Rules:

• Comparison MUST be made on the inline value already normalized by left and right trim, as defined by STXT-SPEC.
• Comparison MUST be exact and CASE-SENSITIVE.
• Comparison MUST NOT apply additional canonicalization, removal of diacritics, or normalizations equivalent to the canonical name of nodes.
• The node MUST define Values with Value nodes, which represent the allowed values.
• Each Value MUST be unique after inline normalization by trim.

Example:

Node: Node Name
    Type: ENUM
    Values:
    	Value: value 1
    	Value: value 2
    	Value: value 3

A conforming implementation MUST check ENUM types against their allowed values and MUST reject any value that does not match exactly one of them.

10. Normative Examples

10.1. Schema with cross-namespace references

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

And in org.example.meta:

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

10.2. Valid document

Document (com.example.docs):
    Metadata (org.example.meta): info
    Content>>
        Line 1
        Line 2

11. Schema Errors

A schema is invalid if:

1. It defines two Node entries with the same canonical name.
2. It uses an unknown Type.
3. It defines Children in a Node whose type does not allow children.
4. The cardinality is invalid.
5. A Node: ENUM does not define Values, or Values does not contain any Value.
6. A duplicated Value appears after inline normalization by trim.
7. Two equivalent Child nodes appear within the same Children.
8. A child appears in Children whose Node is not defined in its corresponding schema.

12. Conformance

An implementation is conforming if:

• It fully implements this document.
• It validates types, value forms, cardinalities, and allowed values (ENUM).
• It applies the strict rule of mandatory definition of all nodes referenced in Children.
• It selects, for each validation, a single effective schema per namespace.
• It rejects invalid documents and schemas.

13. Schema of the Schema (`@stxt.schema`)

This section defines the official schema of the schema system itself: the meta-schema that validates all documents in the @stxt.schema namespace.

13.1. Considerations

• Every schema document is: Schema (@stxt.schema): <target-namespace>
• A schema contains:
  • Optionally a Description.
  • One or more Node nodes.
• Each Node:
  • Has an inline value (the name of the node in the target namespace).
  • May optionally have:
    • Description
    • Type
    • Children
    • Values
• Each Child (element of Children) defines the name (and optionally a different namespace) and may have:
  • Min: Minimum number of nodes that must appear. If the node does not exist, there is no established minimum.
  • Max: Maximum number of nodes that may appear. If the node does not exist, there is no established maximum.
• Each Values:
  • May only appear in Node nodes of type ENUM.
  • Contains one or more Value nodes.
• The names (Schema, Node, Type, Children, Child, Description, Min, Max, Values, Value) belong to the @stxt.schema namespace.

13.2. Complete Meta-Schema

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. Quick reading

• Schema Inline value = target namespace (e.g. com.example.docs). Children: Description (?), Node (*).

• Node Inline value = name of the target node (e.g. Document, Author). Optional children:

  • Type: specific type (if missing ⇒ INLINE).
  • Children: Node with list of allowed Child entries
  • Description: explanatory text.
  • Values: Allowed values (ENUM type only)

• Type Inline (INLINE), with the name of the type (GROUP, INLINE, NUMBER, etc.).

• Children GROUP: contains one or more Child nodes.

• Description TEXT: may be inline or multiline.

• Values GROUP: contains one or more Value nodes.

• Value Inline value with one of the allowed values for the ENUM.

13.4. Minimal valid example

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

13.5. Complete example

Schema (@stxt.schema): com.example.docs
    Description: Example schema
    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. End of Document