From 3715a16f5edf8110c93455fa14303d64339d7372 Mon Sep 17 00:00:00 2001 From: Mihaela Mihaljevic Date: Fri, 5 Jun 2026 11:15:03 +0200 Subject: [PATCH] docs(readme): clarify validation status --- README.md | 16 ++++++++++++++++ docs/DESIGN.md | 12 ++++++++---- 2 files changed, 24 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index eb81925..bfa6757 100644 --- a/README.md +++ b/README.md @@ -120,6 +120,22 @@ Literal block emission is intentionally conservative: multiline strings whose lines would not round-trip through the current parser are emitted as quoted strings instead. Flow collections always use inline scalar output. +## Validation + +Validation is path-aware and explicit. The default validator rejects duplicate +mapping keys anywhere in a parsed document. Callers can use strict mode, where +warnings fail validation, or non-strict mode, where warnings are returned while +errors still throw. + +```swift +let issues = try PureYAML.validate(document, strict: false) +``` + +Custom validation rules can be layered onto the default validator or attached to +a blank validator when callers want only project-specific checks. Validation +tests pin exact issue paths, descriptions, severity handling, rule traversal +order, strict/non-strict behavior, and duplicate-key diagnostics. + ## Development Contract PureYAML must stay dependency-free and portable. Before merging changes: diff --git a/docs/DESIGN.md b/docs/DESIGN.md index f706662..a4b5928 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -111,16 +111,20 @@ and flow-style collections. Literal block scalar emission is intentionally limited to strings whose lines round-trip through the current parser; other multiline strings stay quoted. Flow collections always use inline scalars. -The initial validator traverses parsed YAML values and reports path-aware -issues. The default rule rejects duplicate mapping keys, and callers can build a -blank validator plus custom rules for project-specific checks. +The validator traverses parsed YAML values and reports path-aware issues. The +default rule rejects duplicate mapping keys. Callers can compose custom rules on +top of the default validator or start from `Validation.Validator.blank` for +project-specific checks only. Strict validation treats warnings as failures; +non-strict validation returns warnings while still throwing for errors. The +validation corpus pins exact issue paths, descriptions, severity splits, +strict/non-strict behavior, rule traversal order, and duplicate-key diagnostics. ## Planned Compatibility Work Compatibility should be added in small, test-backed slices: 1. Tag-aware collection handling and merge keys. -2. Validation rules beyond duplicate-key behavior. +2. Additional built-in validation rules beyond duplicate-key behavior. 3. Codable-style decoding and encoding. 4. Yams corpus comparison tests in a separate compatibility suite.