Module

collections.validator

Schema validation engine for content collections.

Validates frontmatter against dataclass or Pydantic schemas with type coercion, helpful error messages, and support for nested types.

View source
2 Classes

Classes

ValidationResult dataclass
Result of schema validation.
1

Result of schema validation.

Attributes

Name Type Description
valid bool

True if validation passed
data Any | None

Validated instance (dataclass or Pydantic model) or None if invalid
errors list[ValidationError]

List of validation errors (empty if valid)
warnings list[str]

List of non-fatal warnings

Methods 1

error_summary property
Human-readable summary of all errors.
str 
def error_summary(self) -> str

Human-readable summary of all errors.

Returns

str —

Multi-line string with each error on its own line, or empty string if no errors.

SchemaValidator
Validates frontmatter against dataclass or Pydantic schemas. Supports: - Dataclass schemas (Python…
9

Validates frontmatter against dataclass or Pydantic schemas.

Supports:

  • Dataclass schemas (Python standard library)
  • Pydantic models (optional, auto-detected)
  • Type coercion for common types (datetime, date, lists)
  • Optional/Union types
  • Nested dataclasses
  • Strict mode (reject unknown fields)

Methods 1

validate
Validate frontmatter data against schema.
2 ValidationResult 
def validate(self, data: dict[str, Any], source_file: Path | None = None) -> ValidationResult

Validate frontmatter data against schema.

Parameters 2
data dict[str, Any]

Raw frontmatter dictionary from content file
source_file Path | None

Optional source file path for error context
Returns

ValidationResult —

ValidationResult with validated data or errors

Internal Methods 8
__init__
Initialize validator for a schema.
2 None 
def __init__(self, schema: type, strict: bool = True) -> None

Initialize validator for a schema.

Parameters 2
schema type

Dataclass or Pydantic model class
strict bool

If True, reject unknown fields in frontmatter
_validate_pydantic
Validate using Pydantic model.
2 ValidationResult 
def _validate_pydantic(self, data: dict[str, Any], source_file: Path | None) -> ValidationResult

Validate using Pydantic model.

Parameters 2
data dict[str, Any]
source_file Path | None
Returns

ValidationResult

_validate_dataclass
Validate using dataclass schema.
2 ValidationResult 
def _validate_dataclass(self, data: dict[str, Any], source_file: Path | None) -> ValidationResult

Validate using dataclass schema.

Parameters 2
data dict[str, Any]
source_file Path | None
Returns

ValidationResult

_coerce_type
Attempt to coerce value to expected type. Handles: - Optional[X] (Union[X, Non…
3 tuple[Any, list[Val… 
def _coerce_type(self, name: str, value: Any, expected: type) -> tuple[Any, list[ValidationError]]

Attempt to coerce value to expected type.

Handles:

  • Optional[X] (Union[X, None])
  • list[X]
  • datetime and date (from strings)
  • Basic types (str, int, float, bool)
Parameters 3
name str

Field name (for error messages)
value Any

Value to coerce
expected type

Expected type
Returns

tuple[Any, list[ValidationError]] —

Tuple of (coerced_value, list_of_errors)

_coerce_datetime
Coerce value to datetime.
2 tuple[datetime | No… 
def _coerce_datetime(self, name: str, value: Any) -> tuple[datetime | None, list[ValidationError]]

Coerce value to datetime.

Parameters 2
name str
value Any
Returns

tuple[datetime | None, list[ValidationError]]

_coerce_date
Coerce value to date.
2 tuple[date | None, … 
def _coerce_date(self, name: str, value: Any) -> tuple[date | None, list[ValidationError]]

Coerce value to date.

Parameters 2
name str
value Any
Returns

tuple[date | None, list[ValidationError]]

_is_optional
Check if type hint is Optional (Union with None).
1 bool 
def _is_optional(self, type_hint: type) -> bool

Check if type hint is Optional (Union with None).

Parameters 1
type_hint type
Returns

bool

_type_name
Get human-readable type name.
1 str 
def _type_name(self, t: type) -> str

Get human-readable type name.

Parameters 1
t type
Returns

str