PureYAML/docs/rules/validation.md

Validation Rules

Rules for writing PureYAML validators and validation tests.

Core Rule

A validator is a diagnostic contract, not just a throwing function. Every new validation rule must make these parts explicit:

• Subject: the YAML value shape the rule inspects.
• Predicate: the condition under which the rule runs. Use when for optional or context-specific checks instead of hiding that logic in the issue body.
• Context: use root, subject, and path deliberately. If a rule needs document-wide knowledge, read it from root; if it only needs the current node, read it from subject.
• Issue contract: return path-aware Issue values with exact severity, reason, and path. Do not report anonymous failures.
• Path contract: diagnostic paths must be unambiguous. Simple identifier keys may use dot paths; every key containing punctuation, whitespace, quotes, slashes, dots, or an empty string must render with bracket-quoted escaping.
• Default status: state whether the rule belongs in Validation.Validator.defaultRules or must be opt-in.

Validation Document Rule

User-facing tools must offer a validation document/report instead of exposing only a raw crash, trap, stack trace, or unstructured thrown error. Library APIs may throw typed errors, but CLIs, batch tools, and corpus runners must be able to write or print a readable validation document that includes:

• input URL or file path;
• failure category;
• line and column when available;
• failing reference or path when applicable;
• original error text;
• whether processing continued or stopped.

Input-level failures must be data. A tool may return a non-zero exit code after reporting failures, but it must not silently drop them or terminate before the validation document can be produced.

Test Contract

Every validator change must include Swift Testing coverage for:

• a document that succeeds and returns no issues;
• a document that fails with exact issue values;
• a case where the predicate prevents the rule from running;
• required presence and required absence checks, so false positives are caught;
• exact traversal order when multiple issues are possible;
• strict and non-strict behavior when the rule can emit warnings;
• exact thrown Issue.Collection contents for failure cases.
• direct Model.Value validation for YAML states that ordinary loaders may collapse or reject, such as duplicate keys and punctuation-heavy keys.

Implementation Rules

• Keep rules as immutable values under PureYAML.Validation.Rule.
• Prefer a when predicate over early-returning inside the rule body when the rule only applies to a subset of nodes.
• Keep built-in rules deterministic and allocation-conscious. Use sets or maps for membership checks instead of repeated linear scans.
• Do not add external dependencies, Foundation, C shims, or platform-specific code to validation.
• Do not make validation mutate parsed values. Validation observes and reports.