Node-Rules Definition

A section in a Validation Rules document whose name ends in a regular name or in vr_any defines the rules for one or more nodes in the validated document. Such sections are called Node-Rules definitions.

Each node-rules definition specifies the expected type of a node, its constraints, optional default values, and additional metadata such as documentation or dependency information.

[server.name]
type: "text"
title: "The name of this server entry"
description: """
    Specify a unique name for the server, used in logs and diagnostics.
    Only letters, digits, underscores, and hyphens are allowed, up to 60 characters.
    """
minimum: 1
maximum: 60
allowed_chars: "[-A-Za-z0-9_]"

Rules for a Node-Rules Definition

Type Requirement: Each node-rules definition must have exactly one effective type. The type is provided either by:
- a local type field, or
- a use_template reference that defines a type.
A node-rules definition must not define both. See Types for the exact rules governing type and use_template.
```
[client.port]
type: "integer"   # Either "type" or "use_template" is required.
```
Defaults: Node-rules definitions for a scalar value or a value list may define a default value using the default field.
```
[client.port]
type: "integer"
default: 9000
```
Note

When a default is applied, only the type constraint is validated. All other constraints are skipped for the default value.

See Defaults and Optionality for details.
Optionality: A node-rules definition may explicitly mark a node as optional using is_optional: yes.

Optional nodes are not required to exist in the configuration document. Optionality can also be achieved implicitly by providing a default value.

See Defaults and Optionality for details.
```
[client]
type: "section"
is_optional: yes
```
Documentation Fields: A node-rules definition may provide documentation metadata using the title and description fields.

These fields do not influence validation. They are intended for tooling, user interfaces, and generated documentation. Parsers should expose these values through their APIs.
```
[client.port]
type: "integer"
title: "Port on the server to connect to"
description: """
    The numeric port where the client connects to the server.
    """
default: 9000
```
Constraints: A node-rules definition can define zero or more constraints that further restrict valid values or structures.

Constraints are evaluated according to the rules defined in Evaluation Order.

See Constraints for the complete list of available constraints, including negated constraints and custom error messages.
```
[client.port]
type: "integer"
minimum: 1         # Constraint on the value
maximum: 65534     # Further constraint
```
Custom Error: A node-rules definition may define a custom error message for the entire node using the error field.

This message is used when validation of the node fails and no more specific constraint-level error applies.

See Diagnostics for details.
```
[client.port]
type: "integer"
minimum: 1
maximum: 65534
error: "Please specify a valid port from 1–65534."
```
List Entries: Node-rules definitions for value lists or section lists must describe their elements using a vr_entry subsection or section list.

The vr_entry rules define the structure and constraints of each list element.

See Lists for details.
```
[main.tags]
type: "ValueList"

[main.tags.vr_entry]
type: "text"
minimum: 1
```
Dependencies: A node-rules definition may express dependencies between child nodes using a vr_dependency section list.

Dependencies are validated in a later validation stage and can express logical relationships such as mutual inclusion or exclusion.

See Dependencies for details.
```
# ...

[client]
type: "section"

*[client.vr_dependency]*
mode: "xnor"
source: "username"
target: "password"

# ...
```
Variable Names: Node-rules definitions that end in vr_any may restrict the allowed variable names using a vr_name subsection.

This allows rule authors to constrain the names of dynamically created child nodes.

See Variable Names and Reserved Names for details.
```
[user.vr_any]
type: "section"

[user.vr_any.vr_name]
maximum: 60
```
Case Sensitivity: A node-rules definition may enable case-sensitive evaluation for text-based constraints using the case_sensitive field.

If not enabled, text comparisons are case-insensitive by default.

See The Case Sensitive Flag for details.
```
[app.message]
type: "text"
case_sensitive: yes
starts: "message:"
```
Secrets: A node-rules definition may mark a node as secret using the is_secret field.

Secret nodes should be redacted or masked in diagnostics, logs, and error messages.

See Security for details.
```
[client.secret]
type: "text"
is_secret: yes
```