STXT Templates (@stxt.template)

1. Introduction

This document defines the specification of the STXT Template language, a mechanism to describe semantic rules (structure, types, and cardinalities) applicable to STXT documents.

A template:

• Is an STXT document whose namespace is @stxt.template.
• Is associated with a target namespace, analogous to a schema.
• Describes the expected structure through a Structure >> block with simplified syntax.
• Is information-equivalent to a schema: a template can be compiled into an @stxt.schema document with an equivalent internal representation.

Relationship with @stxt.schema:

• A validator MAY support only schemas, only templates, or both.
• If both exist (schema and template) for the same target namespace, a conforming validator SHOULD prioritize @stxt.schema over @stxt.template.
• STXT core MUST NOT impose semantics: templates are an optional layer, after parsing the STXT document.

2. Terminology

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be interpreted as described in RFC 2119.

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

Additional definitions:

• Target namespace: the STXT namespace to which the template applies (for example com.example.docs).
• Node template: an entry within the Structure >> block that defines a node (and optionally its type/cardinality and its children).
• Type: a semantic validation label (for example TEXT, DATE, ENUM) equivalent to STXT Schema types.
• Cardinality: a rule that defines how many times a child node may appear relative to its parent.

3. Relationship between STXT and Template

Validation using templates occurs after STXT parsing:

1. Parsing the STXT document into a hierarchical structure.
2. Resolving the logical namespace by inheritance.
3. Selecting the template corresponding to the logical namespace.
4. Applying template rules (structure, cardinality, types, values).

Optionally, a validator MAY apply rules during parsing, as long as it is loosely coupled to the parser.

4. General structure of a Template

A template is a document whose root node is:

Template (@stxt.template): <target_namespace>

The template MUST contain a Structure node in block form (>>).

Template (@stxt.template): com.example.docs
	Description: Example template
	Structure >>
		Document:
			Title: (1)
			Body: (1) TEXT

Rules:

• The namespace of the template document MUST be @stxt.template.
• <target_namespace> MUST be a valid namespace according to STXT-SPEC (namespaces section).
• Only one active template may exist per target namespace in a conforming validator (see section 5).

5. One template per target namespace

For each logical namespace:

• There MUST NOT be more than one active template simultaneously.
• If multiple templates exist for the same namespace, the validator SHOULD have a clear criterion to decide which one applies, but MUST NOT apply several at once.

6. `Structure >>` block

The Structure >> block defines a tree of node templates using indentation, where:

• Each non-empty line defines a node template.
• Indentation defines child nodes (just like STXT), but within Structure >> you are not describing a data document, but an expected structure.
• The indentation rules of the base STXT document apply to the template document (outside the block) and to the Structure >> block as literal text; however, the content of Structure >> is interpreted by the template system with its own grammar (section 6.2).

6.1 Recommended style convention

For readability, it is recommended:

• 4 spaces per level.
• A single space between components.
• Maintain consistency in names (use the same capitalization/diacritics as in real documents).

6.2 Syntax of a `Structure` line

Each line of the Structure >> block has the form:

<NodeName> [<NamespaceOverride>] ":" [<RuleSpec>]

where:

• <NodeName> is the node name (human text; normalized according to STXT-SPEC for comparison).
• <NamespaceOverride> is optional and has the form (<namespace>) or (@special.namespace) and defines the effective namespace of that node template.
• ":" is mandatory (to avoid visual ambiguity).
• <RuleSpec> is optional and includes, in this logical order:
  1. Optional cardinality (in parentheses).
  2. Optional type.
  3. Optional values if the type is ENUM.

Examples:

Title:
Title: (1)
Body: (1) TEXT
Color: (?) ENUM [red, green, blue]
Metadata (com.google.html): (0,1)

Notes:

• If <RuleSpec> is omitted entirely, default cardinality and default type are assumed (sections 7 and 8).
• A node template may have children even if it declares the default type INLINE. Types that forbid children are defined in section 8.

6.3 Parsing rules for `Structure >>`

A template parser MUST:

1. Read the Structure >> block as a sequence of lines (already canonicalized by STXT core: right-trim per line).
2. Ignore empty lines.
3. Compute hierarchy by indentation (same principles as STXT: consecutive indentation, no jumps).
4. For each line, parse:
   • Node name + optional namespace (ns) if present.
   • The mandatory : character.
   • The optional rule specification (RuleSpec).

A template parser MUST fail if a line does not contain :.

7. Cardinalities

Cardinality applies per instance of the parent node, counting only direct children that match by:

• Canonical node name (according to STXT-SPEC).
• Effective namespace of the node.

Cardinality is expressed as an optional token in parentheses: ( ... ).

7.1 Allowed forms

Allowed forms:

Rules:

• num, min, and max MUST be non-negative integers.
• In min,max, min <= max MUST hold.
• + is equivalent to 1+.
• ? is equivalent to 0,1.

7.2 Default cardinality

If no cardinality is specified, the default value is:

• * (any number).

8. Types

Types in templates reuse the set of STXT Schema types, with the same intent: validate the shape of the value and, optionally, its content.

The type is specified as a word after the cardinality (if present).

Examples:

Date: (1) DATE
Body: (1) TEXT
Is Public: (1) BOOLEAN

8.1 Default type

If the type is omitted, the default type is:

• INLINE

8.2 Compatibility with children

A conforming validator MUST apply these rules:

• BLOCK-only types (for example BLOCK, TEXT, CODE, BASE64, JSON, XML, YAML, HTML, MARKDOWN, etc.) are NOT compatible with children. If a node template has children in Structure >> and its effective type is BLOCK-only, the template MUST be considered invalid.

• GROUP types (or equivalent structural types without value) DO allow children.

• INLINE types (for example INLINE, NUMBER, DATE, BOOLEAN, ENUM, etc.) MAY allow children (same philosophy as Schema). Value validation applies to the node, and structure validation applies to its children.

8.3 Type set

The recommended type set is the same as STXT-SCHEMA-SPEC.

A template validator:

• MUST support at least: INLINE, GROUP, BLOCK, TEXT, NUMBER, BOOLEAN, DATE, ENUM.
• SHOULD support the rest of the types defined in STXT Schema (for example INTEGER, NATURAL, TIME, TIMESTAMP, UUID, URL, EMAIL, BASE64, etc.).

9. ENUM and value list

If the type is ENUM, the template MAY declare a list of allowed values.

The value list is specified with brackets [...] after the type:

ENUM [value1, value2, value3]

Color: (1) ENUM [red, green, blue]

Rules:

• If the type is ENUM, the value list SHOULD exist for validation to be useful.
• If the type is NOT ENUM, a [...] list MUST be considered a template error.
• Values are separated by commas ,.
• Trim (spaces/tabs) is applied around each value.
• Value comparison MUST be case-sensitive.
• At least one value must exist in the list if [...] is present.

10. Namespaces within `Structure`

Each line may include an explicit namespace for the node template:

Metadata (com.google.html): (?)

Rules:

• If the namespace is omitted, the node template belongs to the template’s target namespace.

• If (other.ns) is specified, that node template belongs to that namespace.

• Namespace inheritance in templates DOES NOT work as in STXT data documents: each line declares its effective namespace by:

  • explicit namespace on the line, or
  • the template’s target namespace if there is no override.

Motivation:

• In templates, the Structure block describes expected structure and cross-namespace references explicitly.

11. “Defined nodes” rules

In templates, a node exists if it appears in Structure. Unlike Schema, there is no separate Node: section; the structure itself is the definition.

Recommended consistency rule:

• If a template references cross-namespace nodes, a complete validation system SHOULD have the corresponding template or schema for that external namespace if deep validation is desired.
• A validator MAY validate only cardinality/structure of the target namespace and treat cross-namespace nodes as a “black box”, depending on configuration.

12. Compilation to Schema (semantic equivalence)

A template can be compiled into an equivalent schema:

• Each Structure line generates a Node definition for the node template (in the corresponding namespace).
• The indentation hierarchy in Structure generates Children/Child in the schema.
• The ( ... ) cardinality in the template translates to:
  • Min / Max in the schema.
• The type is copied to Type.
• ENUM [a,b] translates to Values/Value.

Cardinality translation rules:

• (num) → Min=num, Max=num
• (*) → no Min, no Max
• (+) → Min=1
• (?) → Max=1
• (num+) → Min=num
• (num-) → Max=num
• (min,max) → Min=min, Max=max

13. Template errors

A template is invalid if any of these conditions occur:

1. The document does not have root Template (@stxt.template): <target_namespace>.
2. Structure >> is missing or Structure is not a >> block.
3. A non-empty line within Structure does not contain :.
4. Malformed cardinality or invalid numbers.
5. Unknown type (according to the set of types supported by the validator).
6. Use of [...] if the type is not ENUM.
7. BLOCK-only type with children defined in Structure.
8. Invalid indentation within Structure (level jumps, etc.).

14. Conformance

A template implementation is conforming if it:

• Implements the Template and Structure grammar of this document.
• Applies the cardinality, type, and ENUM rules.
• Applies the child-compatibility rules by type.
• Rejects invalid templates according to section 13.
• Defines a stable template selection criterion (if multiple sources exist), without applying more than one simultaneously per target namespace.

15. Meta-template of the `@stxt.template` system itself

This section defines a minimal recommended template to validate documents in the @stxt.template namespace.

Template (@stxt.template): @stxt.template
	Structure >>
		Template: (1)
			Description: (0,1) TEXT
			Structure: (1) BLOCK

Notes:

• Structure is BLOCK because in templates it must be a >> block.
• Description is optional and can be TEXT.

16. Normative examples

16.1 Simple template (one namespace)

Template (@stxt.template): com.example.docs
	Description: Simple template
	Structure >>
		Document:
			Title: (1)
			Author: (1)
			Date: (1) DATE
			Body: (1) TEXT

16.2 Template with repetition and nested nodes

Template (@stxt.template): com.blog.post
	Structure >>
		Post:
			Title: (1)
			Slug: (1)
			Published: (1) BOOLEAN
			Tags: (?)
				Tag: (+)
			Sections: (1)
				Section: (+)
					Heading: (1)
					Content: (1) TEXT

16.3 Template with ENUM

Template (@stxt.template): com.ui.theme
	Structure >>
		Theme:
			Name: (1)
			Mode: (1) ENUM [light, dark]
			Accent: (?) ENUM [blue, green, orange]

16.4 Cross-namespace (external references)

Template (@stxt.template): com.example.docs
	Structure >>
		Document:
			Metadata (com.google.html): (?)
			Content: (1) TEXT

In this case:

• Metadata belongs to com.google.html.
• Deep validation of Metadata will depend on whether a schema/template exists for com.google.html.

17. Appendix A — Grammar (informal)

TemplateDoc      = "Template" "(" "@stxt.template" ")" ":" NamespaceTarget { TemplateField }
TemplateField    = DescriptionField | StructureField
DescriptionField = "Description" ":" Text
StructureField   = "Structure" ">>" Newline { StructureLine }

StructureLine    = Indent NodeSpec Newline
NodeSpec         = NodeName [NsOverride] ":" [RuleSpec]
NsOverride       = "(" ["@"] Namespace ")"
RuleSpec         = [Card] [Type] [EnumValues]

Card             = "(" CardToken ")"
CardToken        = "*" | "+" | "?" | Num | Num "+" | Num "-" | Num "," Num
Type             = IdentUpper
EnumValues       = "[" Value { "," Value } "]"

NodeName         = Text (up to "(" or ":"), with trim and space compaction
NamespaceTarget  = Namespace per STXT-SPEC
Namespace        = Ident { "." Ident }
Ident            = [a-z0-9]+
IdentUpper       = [A-Z0-9_]+  ; recommended uppercase (style)

18. End of Document