schema(3tcl)

📦

version 0.9.6 · 4 versions

0.9.6 · ubuntu resolute, ubuntu stonking (latest)
0.9.2 · ubuntu jammy
0.9.3 · debian bookworm, ubuntu noble
0.9.5.1 · debian trixie, ubuntu questing

okay bestie, this is schema(3tcl) — the tdom schema validation page 💖 it's a big one, so grab a snack

💖 NAME 💖

tdom::schema — creates a schema validation command ✨

🌸 SYNOPSIS 🌸

package require tdom

tdom::schema ?create? cmdName

✨ DESCRIPTION ✨

Every single time you call this command, it makes you a brand new validation command. Think of it like summoning a little schema-boss of your very own 🫶

A validation command comes with methods that let you:

define a schema,
validate XML data against that schema,
post-validate a tDOM DOM tree against it — and, to some degree, other kinds of hierarchical data too 👀

Also (this is the slay part) a validation command may be used as the argument to the -validateCmd option of the dom parse and the expat commands, which means you get validation on top of whatever those commands already do. stacking features, we love to see it 💅

The methods of created commands are:

🎀 `prefixns` 🎀

prefixns ?prefixUriList?

This one controls the prefix (or abbreviation) to namespace URI mapping. Anywhere a namespace argument is expected in the schema command methods, the "prefix" can be used instead of the namespace URI. lowkey a glow-up for your typing.

If the list maps the same prefix to different namespace URIs, the first one wins 👑
If there is no such prefix, the namespace argument is used literally as the namespace URI.
Called with no argument? It returns the current prefixUriList.
Called with the empty string? Then any namespace URI arguments are used literally. This is the default.

🦋 `defelement` 🦋

defelement name ?namespace? <definition script>

Defines the element name (optional in the namespace namespace) in the schema. The definition script is evaluated and defines the content model of the element. If the namespace argument is given, any element or ref references in the definition script that are not wrapped inside a namespace command get resolved in that namespace.

And if there's already an element definition for that name/namespace combo? It raises error. no duplicates, we don't do that here 😤

💜 `defelementtype` 💜

defelementtype typename ?namespace? <definition script>

Defines the element type typename (optional in the namespace namespace) in the schema. If the element type is used in a definition script with the schema command element, the validation engine expects an element content according to the content model definition script.

Real talk: defining (and using) element types seems only sensible if you really have elements with the same name and namespace but different content models. That's the whole point of them 🫠

The definition script is evaluated and defines the content model of the element it is assigned to. If the namespace argument is given, any element or ref references in the definition script not wrapped inside a namespace command are resolved in that namespace. If there is already an elementtype definition for that typename/namespace combination, the command raises error.

🚨 Huge caveat, don't skip this one: the document element of any XML you want to validate cannot be a defelementtype-defined element. periodt.

🌈 `defpattern` 🌈

defpattern name ?namespace? <definition script>

Defines a (maybe complex) content particle with the name (optional in the namespace namespace) in the schema, so it can be used in other definition scripts with the definition command ref. The definition script is evaluated and defines the content model of the content particle.

If the namespace argument is given, any element or ref references in the definition script not wrapped inside a namespace command are resolved in that namespace. If there is already a pattern definition for that name/namespace combination, the command raises error. 🚫

🍓 `deftexttype` 🍓

deftexttype name <constraint script>

Defines a bundle of text constraints that can be referred to by name while defining constraints on text element or attribute values. If there's already a text type definition with this name, the command raises error.

✨ cute little detail: a text type may be referred to before it is defined in the schema. And if a referred text type isn't defined anywhere in the schema at all, then literally any text will match this type during validation. vibes-based validation, iykyk 😌

👑 `start` 👑

start documentElement ?namespace?

Defines the name and namespace of the root element of a tree you want to validate. If this method is used, the root element must match for validity — no exceptions bestie.

If start is not used, any element defined by defelement may be the root of a valid document.

The start method may be used several times with varying arguments during the lifetime of a validation command. no commitment, we stan 💅

And if the command is called with just the empty string (and no namespace argument), the validation constraint for the root element is removed and any defined element will be valid as the root of a tree to validate. freedom 🦋

🧚 `define` 🧚

define <definition script>

Defines several elements or patterns, or a whole entire schema, in one single call — by evaluating the definition script. All the schema command methods we've met so far (prefixns, defelement, defelementtype, defpattern, deftexttype and start) are allowed at the top level in the definition script.

⚠️ But the define method itself is not allowed recursively. don't do inception, bestie.

💀 `event` 💀

event (start|end|text) ?event specific data?

This method enables validation of hierarchical data against the content constraints of the validation command.

`start`

start name ?attributes? ?namespace?

Checks if the current validation state allows the element name in the namespace to start here. It raises error if not. 😤

`end`

end

Checks if the current innermost open element may end there in the current state without violating validation constraints. It raises error if not.

`text`

text text

Checks if the current validation state allows the given text content. It raises error if not.

🌟 `validate` 🌟

validate ?options? <XML string> ?objVar?

Returns true if the <XML string> is valid, or false otherwise. If validation has failed and the optional objVar argument is given, the variable with that name is set to a validation error message. If the XML string is valid and the optional objVar argument is given, the variable will be untouched. (not me checking a variable that never got set 😭)

The valid options are:

-baseurl <baseURI> — If -baseurl <baseURI> is specified, the baseURI is used as the base URI of the document. External entities references in the document are resolved relative to this base URI. This base URI is also stored within the DOM tree.
-externalentitycommand <script> — If -externalentitycommand <script> is specified, the specified Tcl script is called to resolve any external entities of the document. The default is "::tdom::extRefHandler", which is a simple file URL resolver defined by the script part of the package. Setting the option value to the empty string disables resolving of external entities. The actual evaluated command consists of this option followed by three arguments: the base uri, the system identifier of the entity and the public identifier of the entity. The base uri and the public identifier may be the empty list. The script has to return a Tcl list consisting of three elements.
- The first element of this list signals how the external entity is returned to the processor. Currently the two allowed types are "string" and "channel".
- The second element of the list has to be the (absolute) base URI of the external entity to be parsed.
- The third element of the list are data — either the already read data out of the external entity as a string in the case of type "string", or the name of a Tcl channel in the case of type "channel".
- > ⚠️ Note that if the script returns a Tcl channel, it will not be closed by the processor. It must be closed separately if it is no longer needed. handle your own cleanup bestie 🫠
-paramentityparsing <always|never|notstandalone> — The -paramentityparsing option controls whether the parser tries to resolve the external entities (including the external DTD subset) of the document while building the DOM tree. -paramentityparsing requires an argument, which must be either "always", "never", or "notstandalone".
- "always" means the parser tries to resolve (recursively) all external entities of the XML source. This is the default in case -paramentityparsing is omitted.
- "never" means only the given XML source is parsed and no external entity (including the external subset) will be resolved and parsed.
- "notstandalone" means that all external entities will be resolved and parsed, with the exception of documents which explicitly state standalone="yes" in their XML declaration.
-useForeignDTD <boolean> — If <boolean> is true and the document does not have an external subset, the parser will call the -externalentitycommand script with empty values for the systemId and publicID arguments. Please note that if the document also doesn't have an internal subset, the -startdoctypedeclcommand and -enddoctypedeclcommand scripts, if set, are not called.

🌸 `validatefile` 🌸

validatefile ?options? filename ?objVar?

Returns true if the content of filename is valid, or false otherwise. The given file is fed as a binary stream to expat, therefore heads up: only US-ASCII, ISO-8859-1, UTF-8 or UTF-16 encoded data will work with this method. pick your encoding wisely 🫶

If validation has failed and the optional objVar argument is given, the variable with that name is set to a validation error message. If the XML data is valid and the optional objVar argument is given, the variable will be untouched.

The allowed options and their meaning are the same as for the validate method — go peek at that one for the full description 👀

💅 The Methods, Part Two (we're so back)

`validatechannel` ?options? channel ?objVar?

okay so this one reads from a Tcl channel and returns true if the content you pulled out of that channel is valid, or false if it's giving invalid. 💖

heads up bestie: since data read out of a Tcl channel is UTF-8 encoded, any misleading encoding declaration sitting at the beginning of the data will lead to errors. like, don't lie about your encoding, it never ends well. 😭

if the validation fails and you handed over the optional objVar argument, the variable with that name gets set to a validation error message. if the XML data is valid and you gave objVar, the variable stays untouched — not me leaving it alone, it's simply not its moment. ✨

the allowed options and their meaning are the same as for the validate method; go read there for the full description, iykyk.

`domvalidate` domNode ?objVar?

returns true if the first argument is a valid tree, or false otherwise. 🌈

if validation has failed and the optional objVar argument is given, the variable with that name is set to a validation error message. if the dom tree is valid and objVar is given, that variable gets set to the empty string. (yes literally empty. iconic behavior honestly. 💅)

`reportcmd` ?cmd?

this method expects the name of a Tcl command to be called in case of a validation error. the command will be called with two arguments appended: the schema command which raises the validation error, and a validation error code. 🎀

the possible error codes are:

MISSING_ELEMENT
MISSING_TEXT
UNEXPECTED_ELEMENT
UNEXPECTED_ROOT_ELEMENT
UNEXPECTED_TEXT
UNKNOWN_ROOT_ELEMENT
UNKNOWN_ATTRIBUTE
MISSING_ATTRIBUTE
INVALID_ATTRIBUTE_VALUE
DOM_KEYCONSTRAINT
DOM_XPATH_BOOLEAN
INVALID_KEYREF
INVALID_VALUE
UNKNOWN_GLOBAL_ID
UNKNOWN_ID

for more detailed information see section Recovering. 👑

`delete`

this method deletes the validation command. bye bestie, block and delete. 💀✨

`info` ?args?

this method bundles methods to query the state of and details about the schema command. it's giving ✨control panel✨, it's giving dashboard energy. 🦋

`validationstate`

this method returns the state of the validation command with respect to validation state. the possible return values and their meanings are:

READY — the validation command is ready to start validation 🌸
VALIDATING — the validation command is in the process of validating input. 🫶
FINISHED — the validation has finished, no further events are expected. 🎀

`vstate`

this method is a shorter alias for validationstate; see there. lowkey the same thing, highkey convenient. 💅

`line`

if the schema command is currently validating, this method returns the line part of the parsing position information, and the empty string in all other cases. if the schema command is currently post-validating a DOM tree, there may be no position information stored at some or all nodes. the empty string is returned in these cases. 😭

`column`

if the schema command is currently validating, this method returns the column part of the parsing position information, and the empty string in all other cases. if the schema command is currently post-validating a DOM tree, there may be no position information stored at some or all nodes. the empty string is returned in these cases. 😭

`byteIndex`

if the schema command is currently validating, this method returns the byte position of the parsing position information, and the empty string in all other cases. if the schema command is currently post-validating a DOM tree, there may be no position information stored at some or all nodes. the empty string is returned in these cases. 😭

`domNode`

if the schema command isn't currently post-validating a DOM tree, this method returns the empty string. otherwise, if the schema command waits for the reportcmd script to finish while recovering from a validation error, it returns the node on which the validation engine is currently looking at in case the node is an ELEMENT_NODE or, if not, its parent node. 🌳

⚠️ it is recommended that you do not use this method. or at least leave the DOM tree alone, use it read-only. like bestie pls don't touch, just look. 🙈

`nrForwardDefinitions`

returns how many elements, element types and ref patterns are referenced that aren't defined so far (summed together). it's the "who are you even" counter fr fr. 💀

`definedElements`

returns in no particular order the defined elements in the grammar as list. if an element is namespaced, its list entry will be itself a list with two elements, with the name as first and the namespace as second element. 🎀

`definedElementtypes`

returns in no particular order the defined element types in the grammar as list. if an element type is namespaced, its list entry will be itself a list with two elements, with the name as first and the namespace as second element. 🎀

`definedPatterns`

returns in no particular order the defined named pattern in the grammar as list. if a named pattern is namespaced, its list entry will be itself a list with two elements, with the name as first and the namespace as second element. 🎀

`expected`

returns in no particular order all possible next events (since the last successful event match, if there was one) as a list. ✨

if an element is namespaced, its list entry will be itself a list with two elements, with the name as first and the namespace as second element.
if text is a possible next event, the list entry will be a two elements list, with #text as first element and the empty string as second.
if an any element constraint is possible, the list entry will be a two elements list, with <any> as first element and the empty string as second.
if an any element in a certain namespace constraint is possible, the list entry will be a two elements list, with <any> as first element and the namespace as second.
if element end is a possible event, the list entry will be a two elements list with <elementend> as first element and the empty string as second element.

`definition` name ?namespace?

returns the code that defines the given element. the command raises error if there is no definition of that element. 🚨

`typedefinition` name ?namespace?

returns the code that defines the given element type definition. the command raises error if there is no definition of that element. 🚨

`patterndefinition` name ?namespace?

returns the code that defines the given pattern definition. the command raises error if there is no definition of a pattern with that name and, if given, namespace. 🚨

`vaction` ?name|namespace|text?

this method returns useful information only if the schema command waits for the reportcmd script to finish while recovering from a validation error. otherwise it returns NONE. 💅

if the command is called without the optional argument, the possible return values and their meanings are:

NONE — the schema command currently does not recover from a validation event.
MATCH_ELEMENT_START — element start event, which includes looking for missing or unknown attributes. 🔍
MATCH_ELEMENT_END — element end event.
MATCH_TEXT — validating text between tags.
MATCH_ATTRIBUTE_TEXT — attribute text value constraint check.
MATCH_GLOBAL — checking global IDs.
MATCH_DOM_KEYCONSTRAINT — checking domunique constraint.
MATCH_DOM_XPATH_BOOLEAN — checking domxpathboolean constant.

if called with one of the possible optional arguments, the command returns detail information depending on current action. 🫶

name — returns the name of the element that has to match in case of MATCH_ELEMENT_START. returns the name of the closed element in case of MATCH_ELEMENT_END. returns the name of the attribute in case of MATCH_ATTRIBUTE_TEXT. returns the name of the parent element in case of MATCH_TEXT.
namespace — returns the namespace of the element that has to match in case of MATCH_ELEMENT_START. returns the namespace of the closed element in case of MATCH_ELEMENT_END. returns the namespace of the attribute in case of MATCH_ATTRIBUTE_TEXT. returns the namespace of the parent element in case of MATCH_TEXT.
text — returns the text to match in case of MATCH_TEXT. returns the value of the attribute in case of MATCH_ATTRIBUTE_TEXT.

`stack` top|inside|associated

in Tcl scripts evaluated by validation, this method provides information about the current validation stack. called outside this context the method returns the empty string. 🥲

top — returns the element whose content is currently checked (the open element tag at this moment).
inside — returns all currently open elements as a list.
associated — returns the data associated with the current top most stack content particle or the empty string if there isn't any. 🎀
reset — this one resets the validation command right back into state READY, while preserving the grammar you already defined. Your grammar is safe, bestie, nothing gets yeeted 💅

🎀 Schema definition scripts 🎀

Okay so schema definition scripts are literally just ordinary Tcl scripts, and they get evaluated in the namespace tdom::schema. All the commands listed below live in that Tcl namespace, and they let you define a whole rainbow of document structures 🌈. Every single schema definition command sets up a validation constraint on the content — and that content either has to match, or it has to be optional, for it to qualify as valid. And if there's extra content that didn't get matched? That is a validation error, periodt. Also, white-space-only text (in the XML sense of white space, iykyk) between any different tags gets ignored — with the one exception of text only elements, where even white-space-only text counts as significant content. 🌸

The schema definition commands are:

`element name ?quant? (?<definition script>|“type“ typename)?`

If neither the optional definition script argument nor the string "type" plus a typename is given, this command refers to the element defined with defelement under the name name in the current context namespace. 👑
If the string "type" and a typename are given, then the content of the element is described by the content model defined with defelementtype under the name typename in the current context namespace.
If the defelement script argument is given, the validation constraint expects an element with the name name in the current namespace, with content "locally" defined by the definition script. Forward references to elements or patterns that haven't been defined yet — or other local definitions of the same name inside the definition script — are allowed, no stress 🫶. But if a forward referenced element still isn't defined by the time validation rolls around, then only an empty element with name name and namespace namespace and no attributes matches.

`ref name ?quant?`

This command refers to the content particle defined with defpattern under the name name in the current context namespace. Forward references to a pattern that isn't defined yet and recursive references are both allowed, iconic behaviour honestly. If a forward referenced pattern still isn't defined by validation time, then no content whatsoever is expected — the "empty match". ✨

`group ?quant? <definition script>`

This method groups a sequence of content particles defined by the definition script, and they all have to match in this sequence order. In order. No shuffling. 🎀

`choice ?quant? <definition script>`

This schema constraint matches if one of the top level content particles defined by the definition script matches. And if one of these top level content particles is optional, then this constraint matches the "empty match". Pick your fighter 💅

`interleave ?quant? <definition script>`

This schema constraint matches after every one of the required top level content particles defined by the definition script has matched (and, optionally, some or all of the other ones), in any arbitrary order. Chaos mode: enabled. 🌪️

`mixed ?quant? <definition script>`

This schema constraint matches for any text (including the empty one) and every top level content particle defined by the definition script with default quantifier *. She's flexible like that. 🦋

`text ?<constraint script>|“type“ typename?`

Without the optional constraint script, this validation constraint matches every string (including the empty one). With a constraint script, or with a given text type argument, a text matching this script or the text type is expected. 🍓

`any ?options? ?<namespace list>? ?quant?`

Without arguments, the any command matches every element. If the <namespace list> argument is given, this matches any element in a namespace out of that list. The empty string means elements with no namespace. If additionally the option -not is given, then this matches every element with a namespace not in the list. The only other recognized option is --, which signals the end of any options.

Please note that in the case of no namespace argument being given, that means the quantifiers * and + will eat up any elements until the enclosing element ends. And if you really have a namespace that looks like a valid tDOM schema quantifier, you will have to spell out always both arguments. Yes, both. Every time. 😭

`attribute name ?quant? (?<constraint script>|“type“ typename?)`

The attribute command defines an attribute (in no namespace) to the enclosing element. The first definition of name inside an element definition wins — later definitions of the same name are silently ignored, she said what she said 🙈. After the name argument there may be one of the quantifiers ? or !. If there is, it will be used. Otherwise the attribute will be required (so it must be present in the XML source). If there is one argument more, that argument is evaluated as a constraint script, defining the value constraints of the attribute. Otherwise, if there are two more arguments and the first of them is the bare-word "type", the following argument is used as a text type name.

This command is only allowed at top level in the definition script of a defelement/element script.

`nsattribute name namespace ?quant? (?<constraint script>|“type“ typename?)`

This command does the same as the command attribute, but for the attribute name in the namespace namespace. Same energy, different namespace 💜

`namespace URI <definition script>`

Evaluates the definition script with context namespace URI. Every element, element type or ref command name will be looked up in the namespace URI, and locally defined elements will be in that namespace. An empty string as URI means no namespace. 🫧

`tcl tclcmd ?arg arg ...?`

Evaluates the Tcl script tclcmd arg arg .... This validation command is only allowed in strict sequential context — so not in choice, mixed and interleave. If the return code is something else than TCL_OK, this is an error (which is not caught and reported by reportcmd). ⚠️

`self`

Returns the schema command. Short. Sweet. Iconic. 💅

`associate data`

This command is only allowed top-level inside definition scripts of the element, elementtype, pattern or interleave content particles. It associates the data given as argument with the currently defined content particle, and it may be requested in scripts evaluated while validating the content of that particle with the schema command method call info stack associated. 🧚

`domunique selector fieldlist ?name? ?“IGNORE_EMPTY_FIELD_SET“|(“EMPTY_FIELD_SET_VALUE“ emptyFieldSetValue)?`

If not postvalidating a DOM tree with domvalidate, this constraint always matches. If postvalidating, this constraint resembles the xsd key/keyref mechanism. The selector argument may be any valid XPath expression (without the xsd limits). Several domunique commands within one element definition are allowed. They are checked in definition order. The argument name is available in the recovering script per info vaction name. If the fieldlist does not select something for a node of the result set of the selector, the key value will be the empty string by default. If the arguments EMPTY_FIELD_SET_VALUE <value> are given, an empty node set will have the key value value. If instead the flag IGNORE_EMPTY_FIELD_SET flag is given, an empty node set result will not have any key value. 👑

`domxpathboolean XPath_expr ?name?`

If not postvalidating a DOM tree with domvalidate, this constraint always matches. If postvalidating, the XPath_expr argument is evaluated (with the node matching the schema parent of the domxpathboolean command as context node). The constraint matches if the result of this XPath expression, converted to boolean by XPath rules, is true. Several domxpathboolean commands within one element definition are allowed. They are checked in definition order.

This enables checks depending on more than one element. Consider:

tdom::schema s
s define {
    defelement doc {
        element a ! text
        element b ! text
        element c ! text
        domxpathboolean "a * b * c >= 20000" volume
        domxpathboolean "a > b and b > c" sequence
    }
}

`jsontype JSON structure type`

If not postvalidating a DOM tree with domvalidate, this constraint always matches. If postvalidating, the constraint matches if the enclosing element has the JSON type given as argument to the structure constraint. The possible JSON structure types are NONE, OBJECT and ARRAY. This constraint is only allowed as direct child of a defelement, defelementtype or local element definition. 🔥

`prefixns ?prefixUriList?`

This defines a prefix to namespace URI mapping exactly as a schemacmd prefixns would. It is meant as a top-level command of a schemacmd define script.

This command is not allowed nested in another definition script command, and it will raise an error if you call it there.

`defelement name ?namespace? <definition script>`

This defines an element exactly as a schemacmd defelement call would. It is meant as a top-level command of a schemacmd define script.

This command is not allowed nested in another definition script command, and it will raise an error if you call it there.

`defelementtype typename ?namespace? <definition script>`

This defines an elementtype exactly as a schemacmd defelementtype call would. It is meant as a top-level command of a schemacmd define script.

This command is not allowed nested in another definition script command, and it will raise an error if you call it there.

`defpattern name ?namespace? <definition script>`

This defines a named pattern exactly as a schemacmd defpattern call would. It is meant as a top-level command of a schemacmd define script.

This command is not allowed nested in another definition script command, and it will raise an error if you call it there.

`deftexttype name <constraint script>`

This defines a named bundle of text constraints exactly as a schemacmd deftexttype call would. It is meant as a top-level command of a schemacmd define script.

This command is not allowed nested in another definition script command, and it will raise an error if you call it there.

start name ?namespace? — bestie, this one works exactly like a schemacmd start call would. It is meant as the top-level command of a schemacmd define script. Not allowed nested in another definition script command, and it will raise error if you call it there. Periodt. 💅

✨ Quantity specifier ✨

Several schema definition commands expect a quantifier as one of their arguments, which determines how often the content particle specified by the command is expected. The valid values for a quant argument are:

! — the content particle has to occur exactly once in valid documents. One and done. 🎯
? — the content particle may not occur more than once in valid documents — the particle is optional. Zero or one, no more. 🙈
* — the content particle may occur zero or more times in a row in valid documents. Go off, do it as many times as you want. ✨
+ — the content particle may occur one or more times in a row in valid documents. At least one, bestie. 💪
n — the content particle must occur n times in a row in valid documents. The quantifier must be an integer greater zero. No zero, no negatives. 🚫
{n m} — the content particle must occur at least n and at most m times in a row in valid documents. The quantifier must be a Tcl list with two elements. The first element of this list must be an integer with n >= 0. If the second list element is the character *, then there is no upper limit. Otherwise the second list element must be an integer with n < m. So {0 *} is giving unlimited, {2 5} is giving strict. 💀

If an optional quantifier is not given, it defaults to * in case of the mixed command and to ! for all other commands. That's the default vibe. 🌈

✨ Text constraint scripts ✨

Text (parsed character data, as XML calls it) sometimes has to be of a certain kind or comply with certain rules to be valid. The text constraint script arguments to text, attribute, nsattribute and deftexttype commands are evaluated in the Tcl namespace tdom::schema::text namespace and allow the ensuing text constraint commands to check text for certain properties. The commands are defined in the Tcl namespace tdom::schema::text. They raise error in case they are called outside of a text constraint script. No sneaky calls, bestie. 🚫

A few of the ensuing text type commands are exposed as general Tcl commands. They are defined in the namespace tdom::type and are called as documented below with the text to check appended to the argument list. They return a logical value. Please note that the commands may not accept starting or ending white space. Whether a command is available in the tdom::type namespace is recorded in its documentation. iykyk. ✨

✨ The tcl text constraint command ✨

The tcl text constraint command dispatches the check to an arbitrary Tcl command, thus enabling any programmable decision rules. Main character energy: you decide. 👑

tcl tclcmd ?arg arg ...? — Evaluates the Tcl script tclcmd arg arg ... and the text to validate appended to the argument list. The return value of the Tcl command is interpreted as a boolean. So yes/no, true/false, slay/not slay. 💅

✨ Basic XML types ✨

name — <URL: https://www.w3.org/TR/xml/#NT-Name> This text constraint matches if the text value matches the XML name production . This means that the text value must start with a letter, underscore (_), or colon (:), and may contain only letters, digits, underscores (_), colons (:), hyphens (-), and periods (.). Iconic XML name behavior. 🏷️
ncname — <URL: https://www.w3.org/TR/xml-names/#NT-NCName> This text constraint matches if the text value matches the XML ncname production . This means that the text value must start with a letter or underscore (_), and may contain only letters, digits, underscores (_), hyphens (-), and periods (.). The only difference to the name constraint is that colons are not permitted. No colon, no problem. 🚫
qname — <URL: https://www.w3.org/TR/xml-names/#NT-QName> This text constraint matches if the text value matches the XML qname production . This means that the text value is either a ncname or two ncnames joined by a colon (:). Like prefix:local, periodt. 🔗
nmtoken — <URL: https://www.w3.org/TR/xml/#NT-Nmtoken> This text constraint matches if the text value matches the XML nmtoken production . Yes, that's the whole vibe. ✨
nmtokens — <URL: https://www.w3.org/TR/xml/#NT-Nmtokens> This text constraint matches if the text value matches the XML nmtokens production . Plural, more tokens, more fun. 💫

✨ Basic type tests ✨

integer ?(xsd|tcl)? — This text constraint matches if the text value could be parsed as an integer. If the optional argument to the command is tcl, everything that returns TCL_OK if fed into Tcl_GetInt() matches. If the optional argument to the command is xsd, the constraint matches if the value is a valid xsd:integer. Without argument xsd is the default. So xsd unless you say otherwise. 🔢
negativeInteger ?(xsd|tcl)? — This text constraint matches the same text values as the integer text constraint (see there), with the additional constraint that the value must be < zero. Negative vibes only. 💀
nonNegativeInteger ?(xsd|tcl)? — This text constraint matches the same text values as the integer text constraint (see there), with the additional constraint that the value must be >= zero. Zero is allowed, bestie. 🫶
nonPositiveInteger ?(xsd|tcl)? — This text constraint matches the same text values as the integer text constraint (see there), with the additional constraint that the value must be <= zero. Zero and down. ⬇️
positiveInteger ?(xsd|tcl)? — This text constraint matches the same text values as the integer text constraint (see there), with the additional constraint that the value must be > zero. Strictly above zero. ✨
number ?(xsd|tcl)? — This text constraint matches if the text value could be parsed as a number. If the optional argument to the command is tcl, everything that returns TCL_OK if fed into Tcl_GetDouble() matches. If the optional argument to the command is xsd, the constraint matches if the value is a valid xsd:decimal. Without argument xsd is the default. Numbers, but make it XSD. 🔢
boolean ?(xsd|tcl)? — This text constraint matches if the text value could be parsed as a boolean. If the optional argument to the command is tcl, everything that returns TCL_OK if fed into Tcl_GetBoolean() matches. If the optional argument to the command is xsd, the constraint matches if the value is a valid xsd:boolean. Without argument xsd is the default. True/false, yes/no, slay/not slay. ✅
date — This text constraint matches if the text value is a xsd:date, which is basically like an ISO 8601 date of the form YYYY-MM-DD, with optional time zone part (either the letter Z or plus (+) or minus (-) followed by hh:mm and with maximum allowed positive or negative time zone 14:00). It follows the date rules of the Gregorian calendar for all dates. A preceding minus sign for bce dates is allowed. There is no year 0. The year may have more than 4 digits, but only if needed (no extra leading zeros). This is available as common Tcl command tdom::type::date. Calendar girl, but make it XML. 📅
time — This text constraint matches if the text value is a xsd:time, which is basically like an ISO 8601 time of the form hh:mm:ss with optional time zone part. The time zone part follows the rules of the date command; see there. All three parts of the time value (hours, minutes, seconds) must be spelled out with 2 digits. Additional fractional seconds (with a point (.) as separator) are allowed, but not just a dangling point. The time value 24:00:00 (without fractional part) is allowed. This is available as common Tcl command tdom::type::time. Time is fake, but this constraint is real. ⏰
dateTime — This text constraint matches if the text value is a xsd:dateTime, which is basically like an ISO 8601 date time of the form YYYY-MM-DDThh:mm:ss with optional time zone part. The date and time zone parts follow the rules of the date and time command; see there. The time part (including the signaling 'T' character) is mandatory. This is available as common Tcl command tdom::type::dateTime. Date plus time, the full package. 📆⏱️
duration — This text constraint matches if the text value is a xsd:duration, which is basically like an ISO 8601 duration of the form PnYnMnDTnHnMnS. All parts other than the starting P and — if one of H, M or S is given — T are optional. In case the following sign letter is S, n may be a decimal (with at least one digit before and after the dot), otherwise it must be a (positive) integer. This is available as common Tcl command tdom::type::duration. Time is a construct, but this constraint is valid. ⏳
base64 — This text constraint matches if text is valid according to RFC 4648. Base64 bestie, we love her. 🧬
hexBinary — This text constraint matches if text is a sequence of binary octets in hexadecimal encoding, where each binary octet is a two-character hexadecimal number. Lowercase and uppercase letters A through F are permitted. Hex girl summer. 🔥
unsignedByte — This text constraint matches if the text value is a xsd:unsignedByte. This is an integer between 0 and 255, both included, optionally preceded by a + sign and leading zeros. Small but unsigned. 🐣
unsignedShort — This text constraint matches if the text value is a xsd:unsignedShort. This is an integer between 0 and 65535, both included, optionally preceded by a + sign and leading zeros. Short queen. 👑
unsignedInt — This text constraint matches if the text value is a xsd:unsignedInt. This is an integer between 0 and 4294967295, both included, optionally preceded by a + sign and leading zeros. Int but make it unsigned. 💅
unsignedLong — This text constraint matches if the text value is a xsd:unsignedLong. This is an integer between 0 and 18446744073709551615, both included, optionally preceded by a + sign and leading zeros. Long and unsigned, a whole vibe. 🌈
byte — This text constraint matches if the text value is a xsd:byte. This is an integer between -128 and 127, both included, optionally preceded by a + or a - sign and leading zeros. Tiny but signed. 🧸
short — This text constraint matches if the text value is a xsd:short. This is an integer between -32768 and 32767, both included, optionally preceded by a + or a - sign and leading zeros. Short and signed. ✨
int — This text constraint matches if the text value is a xsd:int. This is an integer between -2147483648 and 2147483647, both included, optionally preceded by a + or a - sign and leading zeros. Classic int behavior. 💯
long — This text constraint matches if the text value is a xsd:long. This is an integer between -9223372036854775808 and 9223372036854775807, both included, optionally preceded by a + or a - sign and leading zeros. Long long, signed, slay. 👑

Logical constructs ✨

Okay bestie, these are the big brain combinators. They let you mix and match other text constraints like it's a playlist. 💅

oneOf <constraint script> — matches if one of the text constraints defined in the argument constraint script matches the text. It stops after the first match and probes the text constraints in the order of definition. So first W wins, no cap. 🏆
allOf <constraint script> — matches if all of the text constraints defined in the argument constraint script match the text. It stops after the first match failure and probes the text constraints in the order of definition. Since the schema definition command text also expects all text constraints to match the text constraint, allOf is useful mostly in connection with the oneOf text constraint command. So it's giving "everybody has to pass", and it's lowkey a sidekick to oneOf. ✨
not <constraint script> — matches if none of the text constraints defined in the argument constraint script matches the text. It stops after the first matching constraint in the constraint script and reports a validation error. The text constraints in the constraint script are probed in the order of definition. So it's the "nope, absolutely not" vibe. 🚫
type text type name — matches if the text type given as argument matches. Simple as that. 💖

Constraints on processed text value 🧼

These ones clean up or slice up the text before checking it. Self-care for strings, honestly.

whitespace (preserve|replace|collapse) <constraint script> — does white-space normalization to the text value and checks the resulting text with the text constraints of the constraint script argument. The white-space characters are #x20 (space, ' '), #x9 (tab, \t), #xA (linefeed, \n), and #xD (carriage return, \r). The normalization method preserve keeps everything as it is; this is another way to say allOf. The replace normalization method replaces any single white-space character (as above) to a space. The collapse normalization method removes all leading and trailing white-space, and all the other sequences of contiguous white-space are replaced by a single space. So preserve is "leave my baby alone", replace is "one space per space", and collapse is "we're Marie Kondo-ing this whitespace". 🧹
split ?type ?args??<constraint script> — splits the text to test into a list of values and tests all elements of that list for the text constraints in the evaluated constraint script. The available types are:
- whitespace — the text to split is stripped of all white space at start and end and split into a list at any successive white space. Default behavior, basically.
- tcl tclcmd ?arg ...? — the text to split is handed to the tclcmd, which is evaluated on global level, appended with every given arg and the text to split as last argument. This call must return a valid Tcl list whose elements are tested. So you can bring your own splitter. 🛠️
- The default in case no split type argument is given is whitespace. Periodt.
strip <constraint script> — tests all text constraints in the evaluated constraint script with the text to test stripped of all white space at start and end. It's the "trim first, ask questions later" energy. ✂️

Various other string properties 💅

Just a whole bag of checks. Pick your fighter.

fixed value — only matches if the text value is string equal to the given value. Exact match, no notes.
enumeration list — matches if the text value is equal to one element (respecting case and any white-space) of the argument list, which has to be a valid Tcl list. So it's a VIP list, and case/whitespace still matter. 👑
match ?-nocase? glob_style_match_pattern> — matches if the text value matches the glob style pattern given as argument. It follows the rules of the Tcl [string match] command, see <URL: https://www.tcl.tk/man/tcl8.6/TclCmd/string.htm#M35>. (Yes, the trailing > in the syntax is in the original, so we're keeping it exactly. 🙈)
regexp expression — matches if the text value matches the regular expression given as argument. <URL: https://www.tcl.tk/man/tcl8.6/TclCmd/re_syntax.htm> describes the regular expression syntax. Regex girlies, this one's for you. 🔥
length length — matches if the length of the text value (in characters, not bytes) is length. The length argument must be a positive integer or zero. So zero is allowed, bestie.
maxLength length — matches if the length of the text value (in characters, not bytes) is at most length. The length argument must be an integer greater zero.
minLength length — matches if the length of the text value (in characters, not bytes) is at least length. The length argument must be an integer greater zero.
id ?keySpace? — marks the text as a document wide ID (to be referenced by an idref). Every ID value within a document must be unique. It isn't an error if the ID isn't actually referenced within the document. The optional argument keySpace does all this for a named key space. The key space "" (the empty sting) is another key space then the id command without keySpace argument. (We're keeping "sting" because that's what the original says. 🫶)
idref ?keySpace? — expects the text to be a reference to an ID within the document. The referenced ID may appear later in the document than the reference. Several references within the document to one ID are possible. For the optional keySpace argument see id. So it's the "I'll find them eventually" reference. 🔗
jsontype <JSON text type> — if not postvalidating a DOM tree with domvalidate this constraint always matches. If postvalidating the current TEXT_NODE to check must have the JSON text type given as argument to the text constraint command. The possible types are NULL, TRUE, FALSE, STRING and NUMBER. JSON besties, this is your moment. 📓

Local key constraints 🔑

Document wide uniqueness and foreign key constraints are available with the text constraint commands id and idref. Keyspaces allow for sub-tree local uniqueness and foreign key constraints. So yes, you can have local drama, not just document-wide drama. 💅

keyspace <names list> <constraint script> — any number of keyspaces are possible. A keyspace is either active or not. Calling keyspace inside a constraint script with the same name does nothing.
These text constraint commands work with keyspaces:
- key <name> — if the keyspace with the name <name> is not active the constraint always matches. If the keyspace is active, reports error if there is already a key with the value. Otherwise it stores the value as key in this keyspace and matches. So it's "first come, first served" inside that keyspace. 🗝️
- keyref <name> — if the keyspace with the name <name> is not active it always matches. If the keyspace is active then reports error if there is still no key as the value at the end of the keyspace <name>. Otherwise, it matches. It's the "where's the key bestie?" check. 🔍

Recovering 🩹

By default the validation engine stops at the first detected validation violation and reports that finding. It does so by returning false (and sets, if given, the result variable with an error message) in case the schema command itself is used to validate input. If the schema command is used by a SAX parser or the DOM parser, it does so by throwing error. So default mode is "we are NOT okay, shutting down." 😭

If a reportcmd is set this command is called on global level appended with the schema command and an error type as arguments in case a validation violation is detected. Then the validation recovers from the error and continues. For some validation errors the recover strategy can be determined with the script result of the reportcmd. So reportcmd is your little recovery bestie. 🫶

With a reportcmd (as long as the reportcmd does not throw error while called) the validation engine will never report validation failure to its caller. The validation engine recovers, continues, and reports the next error (if occurring) and so on until the end of the input. The schema command will return true and the SAX parser and DOM builder will process normally until the end of the input, as if there had not been a validation error. It's giving "we move." 💅

Please note that this happens only for validation errors. It is not possible to recover from well-formedness errors. If the input is not well-formed, the schema command returns false and sets (if given) the result variable with an error message about the well-formedness error. So no recovery for malformed input, periodt. 🚫

If the reportcmd throws error while called by the validation engine then validation stops and the schema command throws error with the error message of the script. So if your recovery script itself breaks, everything stops. 💀

While validating basically three events can happen: an element start tag has to match, a piece of text has to match or an element end tag has to match. The method info vaction called in the recovering script or any script code called from there returns which event has triggered the error report (MATCH_ELEMENT_START, MATCH_TEXT, MATCH_ELEMENT_END, respectively). While the command walks through the schema looking whether the event matches other, data driven events (as, for example checking, if any keyref within a keyspace exists) may happen. So info vaction tells you what kind of drama is happening. 🎬

Several of the validation error codes, appended as second argument to the reportcmd calls, may happen at more than one kind of validation event. The info vaction method and its subcommands provide information about the current validation event, if called from the report command. So use it, bestie. 🔍

If a structural validation error happens, the default recovering strategy is to ignore any following (or missing) content within the current subtree and to continue with the element end event of the subtree. So we skip to the end of that subtree. 🦋

Returning "ignore" from the recovering script in case of error type MISSING_ELEMENT recovers by ignoring the failed constraint and continues to match the event further against the schema. So "ignore" means "not today, keep going." 🙈

Returning "vanish" from the recover script in case of the error types MISSING_ELEMENT and UNEXPECTED_ELEMENT recovers by ignoring the event. So "vanish" means "pretend it didn't happen." 💨

🎀 Examples 🎀

Okay bestie, this is the part where we look at actual real-world schemas and translate them, it's giving "show don't tell" and honestly? Iconic. 💅

<URL: https://www.w3.org/TR/xmlschema-0/> The XML Schema Part 0: Primer Second Edition () starts with this example schema:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <xsd:annotation>
    <xsd:documentation xml:lang="en">
     Purchase order schema for Example.com.
     Copyright 2000 Example.com. All rights reserved.
    </xsd:documentation>
  </xsd:annotation>

  <xsd:element name="purchaseOrder" type="PurchaseOrderType"/>

  <xsd:element name="comment" type="xsd:string"/>

  <xsd:complexType name="PurchaseOrderType">
    <xsd:sequence>
      <xsd:element name="shipTo" type="USAddress"/>
      <xsd:element name="billTo" type="USAddress"/>
      <xsd:element ref="comment" minOccurs="0"/>
      <xsd:element name="items"  type="Items"/>
    </xsd:sequence>
    <xsd:attribute name="orderDate" type="xsd:date"/>
  </xsd:complexType>

  <xsd:complexType name="USAddress">
    <xsd:sequence>
      <xsd:element name="name"   type="xsd:string"/>
      <xsd:element name="street" type="xsd:string"/>
      <xsd:element name="city"   type="xsd:string"/>
      <xsd:element name="state"  type="xsd:string"/>
      <xsd:element name="zip"    type="xsd:decimal"/>
    </xsd:sequence>
    <xsd:attribute name="country" type="xsd:NMTOKEN"
                   fixed="US"/>
  </xsd:complexType>

  <xsd:complexType name="Items">
    <xsd:sequence>
      <xsd:element name="item" minOccurs="0" maxOccurs="unbounded">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="productName" type="xsd:string"/>
            <xsd:element name="quantity">
              <xsd:simpleType>
                <xsd:restriction base="xsd:positiveInteger">
                  <xsd:maxExclusive value="100"/>
                </xsd:restriction>
              </xsd:simpleType>
            </xsd:element>
            <xsd:element name="USPrice"  type="xsd:decimal"/>
            <xsd:element ref="comment"   minOccurs="0"/>
            <xsd:element name="shipDate" type="xsd:date" minOccurs="0"/>
          </xsd:sequence>
          <xsd:attribute name="partNum" type="SKU" use="required"/>
        </xsd:complexType>
      </xsd:element>
    </xsd:sequence>
  </xsd:complexType>

  <!-- Stock Keeping Unit, a code for identifying products -->
  <xsd:simpleType name="SKU">
    <xsd:restriction base="xsd:string">
      <xsd:pattern value="\d{3}-[A-Z]{2}"/>
    </xsd:restriction>
  </xsd:simpleType>

</xsd:schema>

A simple one-to-one translation of that into a tDOM schema definition script would be:

tdom::schema schema
schema define {

    # Purchase order schema for Example.com.
    # Copyright 2000 Example.com. All rights reserved.

    defelement purchaseOrder {ref PurchaseOrderType}

    foreach elm {comment name street city state product} {
        defelement $elm text
    }

    defpattern PurchaseOrderType {
        element shipTo ! {ref USAddress}
        element billTo ! {ref USAddress}
        element comment ?
        element items
        attribute orderDate date
    }

    defpattern USAddress {
        element name
        element street
        element city
        element state
        element zip ! {text number}
        attribute country {fixed "US"}
    }

    defelement items {
        element item * {
            element product
            element quantity ! {text positiveInteger}
            element USPrice ! {text number}
            element comment
            element shipDate ? {text date}
            attribute partNum {regexp "^\d{3}-[A-Z]{2}$"}
        }
    }
}

<URL: http://relaxng.org/tutorial-20011203.html> The RELAX NG Tutorial () starts with this example:

Consider a simple XML representation of an email address book:

<addressBook>
  <card>
    <name>John Smith</name>
    <email>js@example.com</email>
  </card>
  <card>
    <name>Fred Bloggs</name>
    <email>fb@example.net</email>
  </card>
</addressBook>

The DTD would be as follows:

<!DOCTYPE addressBook [
<!ELEMENT addressBook (card*)>
<!ELEMENT card (name, email)>
<!ELEMENT name (#PCDATA)>
<!ELEMENT email (#PCDATA)>
]>

A RELAX NG pattern for this could be written as follows:

<element name="addressBook" xmlns="http://relaxng.org/ns/structure/1.0">
  <zeroOrMore>
    <element name="card">
      <element name="name">
        <text/>
      </element>
      <element name="email">
        <text/>
      </element>
    </element>
  </zeroOrMore>
</element>

This schema definition script will do the same:

tdom::schema schema
schema define {
    defelement addressBook {
        element card *
    }
    defelement card {
        element name
        element email
    }
    foreach e {name email} {
        defelement $e text
    }
}

🌈 KEYWORDS 🌈

Validation, Postvalidation, DOM, SAX

And that's a wrap bestie!! 🫶 You just read the entire schema(3tcl) page and honestly? Main character energy, no notes. 💖 This lil masterpiece ships with Tcl as schema(3tcl), so go forth and validate everything — your XML has never been this safe, periodt. ✨👑

📦 where this page comes from

ubuntu resolute: tdom 0.9.6-2 · MPL-2.0
ubuntu stonking: tdom 0.9.6-3 · MPL-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

schema(3tcl)

💖 NAME 💖

🌸 SYNOPSIS 🌸

✨ DESCRIPTION ✨

🎀 prefixns 🎀

🦋 defelement 🦋

💜 defelementtype 💜

🌈 defpattern 🌈

🍓 deftexttype 🍓

👑 start 👑

🧚 define 🧚

💀 event 💀

start

end

text

🌟 validate 🌟

🌸 validatefile 🌸

💅 The Methods, Part Two (we're so back)

validatechannel ?options? channel ?objVar?

domvalidate domNode ?objVar?

reportcmd ?cmd?

delete

info ?args?

validationstate

vstate

line

column

byteIndex

domNode

nrForwardDefinitions

definedElements

definedElementtypes

definedPatterns

expected

definition name ?namespace?

typedefinition name ?namespace?

patterndefinition name ?namespace?

vaction ?name|namespace|text?

stack top|inside|associated

🎀 Schema definition scripts 🎀

element name ?quant? (?<definition script>|“type“ typename)?

ref name ?quant?

group ?quant? <definition script>

choice ?quant? <definition script>

interleave ?quant? <definition script>

mixed ?quant? <definition script>

text ?<constraint script>|“type“ typename?

any ?options? ?<namespace list>? ?quant?

attribute name ?quant? (?<constraint script>|“type“ typename?)

nsattribute name namespace ?quant? (?<constraint script>|“type“ typename?)

namespace URI <definition script>

tcl tclcmd ?arg arg ...?

self

associate data

domunique selector fieldlist ?name? ?“IGNORE_EMPTY_FIELD_SET“|(“EMPTY_FIELD_SET_VALUE“ emptyFieldSetValue)?

domxpathboolean XPath_expr ?name?

jsontype JSON structure type

prefixns ?prefixUriList?

defelement name ?namespace? <definition script>

defelementtype typename ?namespace? <definition script>

defpattern name ?namespace? <definition script>

deftexttype name <constraint script>

✨ Quantity specifier ✨

✨ Text constraint scripts ✨

✨ The tcl text constraint command ✨

✨ Basic XML types ✨

✨ Basic type tests ✨

Logical constructs ✨

Constraints on processed text value 🧼

Various other string properties 💅

Local key constraints 🔑

Recovering 🩹

🎀 Examples 🎀

🌈 KEYWORDS 🌈

🎀 `prefixns` 🎀

🦋 `defelement` 🦋

💜 `defelementtype` 💜

🌈 `defpattern` 🌈

🍓 `deftexttype` 🍓

👑 `start` 👑

🧚 `define` 🧚

💀 `event` 💀

`start`

`end`

`text`

🌟 `validate` 🌟

🌸 `validatefile` 🌸

`validatechannel` ?options? channel ?objVar?

`domvalidate` domNode ?objVar?

`reportcmd` ?cmd?

`delete`

`info` ?args?

`validationstate`

`vstate`

`line`

`column`

`byteIndex`

`domNode`

`nrForwardDefinitions`

`definedElements`

`definedElementtypes`

`definedPatterns`

`expected`

`definition` name ?namespace?

`typedefinition` name ?namespace?

`patterndefinition` name ?namespace?

`vaction` ?name|namespace|text?

`stack` top|inside|associated

`element name ?quant? (?<definition script>|“type“ typename)?`

`ref name ?quant?`

`group ?quant? <definition script>`

`choice ?quant? <definition script>`

`interleave ?quant? <definition script>`

`mixed ?quant? <definition script>`

`text ?<constraint script>|“type“ typename?`

`any ?options? ?<namespace list>? ?quant?`

`attribute name ?quant? (?<constraint script>|“type“ typename?)`

`nsattribute name namespace ?quant? (?<constraint script>|“type“ typename?)`

`namespace URI <definition script>`

`tcl tclcmd ?arg arg ...?`

`self`

`associate data`

`domunique selector fieldlist ?name? ?“IGNORE_EMPTY_FIELD_SET“|(“EMPTY_FIELD_SET_VALUE“ emptyFieldSetValue)?`

`domxpathboolean XPath_expr ?name?`

`jsontype JSON structure type`

`prefixns ?prefixUriList?`

`defelement name ?namespace? <definition script>`

`defelementtype typename ?namespace? <definition script>`

`defpattern name ?namespace? <definition script>`

`deftexttype name <constraint script>`