Validation Options

Validation options verify field values against configured constraints during data export to prevent invalid data.

Option Applicability

Option	Supported Types
interval	integers, floats and duration
minLen, maxLen	- string, path, l10n, backref-n - all array and map types (compact, multi-column, subtable, tree)
maxChars	string, l10n
nonzero	- all Basic Types - backref - >>object, >>minmax, >>wtpool, >>vector, >>tuple - multi-column minmax, wtpool, vector, tuple, bitflags - tree minmax, wtpool, vector
whitelist	all Basic Types
blacklist	all Basic Types
regexp	all Basic Types
synclen	- not supported in tree-structured data - arrays and maps (compact, multi-column, subtable) - >>wtpool, multi-column wtpool
unique	integers, string, path, ref, enum, datetime, rgba, and the elements of backref-n
root, dir	path

Option List

Option	Description
interval	Numeric range constraint	View
minLen, maxLen	Minimum and maximum element count	View
maxChars	Maximum character count	View
nonzero	Rejection of zero values	View
whitelist	Allowed-value set, checked against the raw value	View
blacklist	Rejected-value set, checked against the raw value	View
regexp	Regular expression, checked against the raw value	View
synclen	Element count check across a group of containers	View
unique	Uniqueness check within a container	View
root, dir	Existence check for a path value	View

interval

The interval option constrains a numeric value to a range.

interval=[1,100]
interval=[0,)
interval=(0,1.0)      →  float
interval=[5s,1m]      →  duration

• Square brackets [ ] mean inclusive.
• Round brackets ( ) mean exclusive.
• Omit the lower bound when you don’t care about it: [,100].
• Omit the upper bound when you don’t care about it: [1,).
• The comma is always required.

See Option Applicability for the types this option supports.

minLen and maxLen

The minLen option enforces a minimum element count. The maxLen option enforces a maximum element count.

minLen=1
maxLen=10

Note

For string values, these two options count UTF-8 bytes, not characters. If you need to enforce a character-based limit, use the maxChars option instead.

Note

l10n values that reference shared strings, such as {{npc1_name}}, are not checked.

See Option Applicability for the types this option supports.

maxChars

The maxChars option enforces a maximum character count.

maxChars=20

Each Unicode code point counts as one character: abc counts as 3, and 你好 counts as 2.

Note

l10n values that reference shared strings, such as {{npc1_name}}, are not checked.

See Option Applicability for the types this option supports.

nonzero

The nonzero option rejects zero values.

nonzero       →  equivalent to nonzero=true
nonzero=true

See Option Applicability for the types this option supports.

See Zero Values for more information.

whitelist

The whitelist option restricts a field to a set of allowed values.

The check runs against the raw value.

Comparisons are case-insensitive for bool, enum, ref, and rgba, since their inputs are case-insensitive. For all other types, comparisons are case-sensitive.

whitelist=1,2,3
whitelist=foo,"hello world",bar

Values are comma-separated.

If a value contains && or ,, it must be quoted. If the first value is quoted, put a comma (,) before it, as in whitelist=,"hello world",foo.

Note

Default export values are not subject to the whitelist restriction.

See Option Applicability for the types this option supports.

blacklist

The blacklist option rejects the specified values.

The check runs against the raw value.

Comparisons are case-insensitive for bool, enum, ref, and rgba, since their inputs are case-insensitive. For all other types, comparisons are case-sensitive.

blacklist=0,99
blacklist=admin,root

Values are comma-separated.

If a value contains && or ,, it must be quoted. If the first value is quoted, put a comma (,) before it, as in blacklist=,"hello world",foo.

Note

Default export values are not subject to the blacklist restriction.

See Option Applicability for the types this option supports.

regexp

The regexp option validates a field with a regular expression.

The check runs against the raw value.

Archmage uses RE2 syntax — see the RE2 syntax reference for details.

regexp=\d+
regexp=`\d+&&\w+`
regexp=`^\d+(?:/\d+)*$`

Quote the pattern if it contains &&.

Caution

By default, regexp performs a contains check, not a full-match. To perform a full match, anchor the pattern with ^ and $.

Note

Default export values are not subject to the regexp restriction.

See Option Applicability for the types this option supports.

synclen

The synclen option groups multiple container fields together and requires all of them to have the same element count at export time.

synclen=<group>

Fields in the same group must share the same group name (case-sensitive).

See Option Applicability for the types this option supports.

unique

The unique option ensures that all exported values in a container are distinct.

unique       →  equivalent to unique=true
unique=true

See Option Applicability for the types this option supports.

Checking Scope

When unique is applied to a field, Archmage walks up the type tree from that field to the nearest array or map ancestor to determine the scope of the uniqueness check. The check then covers all values in that container.

When unique is applied to a field in a virtual table partition, the uniqueness check is limited to that partition, not the entire virtual table.

Zero Values Are Ignored

Zero values are excluded from the uniqueness check. Two zero values don’t count as a conflict.

root and dir

The root option sets a root directory for path validation: Archmage joins the root with the stored value and verifies that the file exists.

The dir option requires the path to be a directory rather than a file.

See the path type for full documentation.