Validators

Configuration validators for Confii.

This module provides validation capabilities for configurations using Pydantic models and JSON Schema.

Available Validators

• SchemaValidator: Validates configurations against JSON Schema

• PydanticValidator: Validates configurations using Pydantic BaseModel classes

Example

>>> from confii.validators import PydanticValidator
>>> from pydantic import BaseModel
>>>
>>> class AppConfig(BaseModel):
...     database_url: str
...     port: int = 8080
>>>
>>> validator = PydanticValidator(AppConfig)
>>> validated = validator.validate(config_dict)

class confii.validators.PydanticValidator(model_class: Type[T])

Bases: Generic[T]

Validates configuration dictionaries using Pydantic models.

PydanticValidator wraps a Pydantic BaseModel subclass and uses it to validate raw configuration dictionaries. It provides detailed, structured error reporting by converting Pydantic ValidationError instances into ConfigValidationError with per-field error details.

This validator is useful when you want strict, type-safe validation of your configuration with automatic coercion, default values, and nested model support provided by Pydantic.

model_class

The Pydantic model class used for validation.

Example

>>> from pydantic import BaseModel, Field
>>> from confii.validators import PydanticValidator
>>>
>>> class DBConfig(BaseModel):
...     host: str = "localhost"
...     port: int = Field(default=5432, ge=1, le=65535)
...     database: str
>>>
>>> validator = PydanticValidator(DBConfig)
>>> model = validator.validate({"database": "mydb", "port": 3306})
>>> print(model.host)  # "localhost" (default applied)

Note

Requires the pydantic package (v2+). Install it with:

pip install pydantic

__init__(model_class: Type[T]) → None

Initialize with a Pydantic model class.

Parameters:

model_class – Pydantic model class for validation

Raises:

ImportError – If pydantic is not installed

validate(config: Dict[str, Any]) → T

Validate configuration against Pydantic model.

Parameters:

config – Configuration dictionary

Returns:

Validated Pydantic model instance

Raises:

ConfigValidationError – If validation fails (wraps Pydantic ValidationError)

validate_to_dict(config: Dict[str, Any]) → Dict[str, Any]

Validate and return as dictionary with defaults applied.

This is a convenience method that validates the configuration and immediately serializes the resulting model back to a dictionary. The returned dictionary includes all default values defined in the Pydantic model, making it suitable for merging back into the configuration pipeline.

Parameters:

config – Configuration dictionary to validate.

Returns:

Validated configuration as a plain dictionary with all model defaults applied.

Raises:

ConfigValidationError – If validation fails.

Example

>>> validator = PydanticValidator(DBConfig)
>>> result = validator.validate_to_dict({"database": "mydb"})
>>> print(result)
{'host': 'localhost', 'port': 5432, 'database': 'mydb', ...}

class confii.validators.SchemaValidator(schema: Dict[str, Any])

Bases: object

Validates configuration dictionaries against a JSON Schema.

SchemaValidator uses the jsonschema library to validate configuration dictionaries against a JSON Schema (Draft 4 through Draft 7). It also supports applying default values defined in the schema to produce a complete configuration dictionary.

This validator is ideal when you need a language-agnostic schema definition that can be shared across services written in different languages, or when you want to validate configuration without defining Python model classes.

schema

The JSON Schema dictionary used for validation.

Example

>>> from confii.validators import SchemaValidator
>>>
>>> schema = {
...     "type": "object",
...     "properties": {
...         "host": {"type": "string", "default": "localhost"},
...         "port": {"type": "integer", "minimum": 1},
...     },
...     "required": ["port"],
... }
>>> validator = SchemaValidator(schema)
>>> validator.validate({"port": 8080})  # Returns True
True

Note

Requires the jsonschema package. Install it with:

pip install jsonschema

__init__(schema: Dict[str, Any])

Initialize with a JSON Schema.

Parameters:

schema – JSON Schema dictionary

Raises:

ImportError – If jsonschema is not installed

classmethod from_file(schema_path: str) → SchemaValidator

Create a SchemaValidator from a JSON schema file.

Reads a JSON file from disk and uses its contents as the validation schema.

Parameters:

schema_path – Path to a JSON schema file.

Returns:

A new SchemaValidator instance configured with the loaded schema.

Raises:

• FileNotFoundError – If the schema file does not exist.

• json.JSONDecodeError – If the file is not valid JSON.

• ImportError – If jsonschema is not installed.

Example

>>> validator = SchemaValidator.from_file("schemas/app.schema.json")
>>> validator.validate({"port": 8080})
True

validate(config: Dict[str, Any]) → bool

Validate configuration against schema.

Parameters:

config – Configuration dictionary to validate

Returns:

True if valid

Raises:

ValidationError – If validation fails

validate_with_defaults(config: Dict[str, Any]) → Dict[str, Any]

Validate and apply default values from schema.

First validates the configuration against the schema, then creates a deep copy and fills in any missing properties that have default values defined in the schema. Nested object properties are handled recursively.

Parameters:

config – Configuration dictionary. This dictionary is not modified; a deep copy is returned.

Returns:

New configuration dictionary with schema defaults applied for any missing properties.

Raises:

ValidationError – If the configuration does not conform to the schema.

Example

>>> schema = {
...     "type": "object",
...     "properties": {
...         "host": {"type": "string", "default": "localhost"},
...         "port": {"type": "integer", "default": 5432},
...         "database": {"type": "string"},
...     },
...     "required": ["database"],
... }
>>> validator = SchemaValidator(schema)
>>> result = validator.validate_with_defaults({"database": "mydb"})
>>> print(result)
{'database': 'mydb', 'host': 'localhost', 'port': 5432}