0
# Yamale
1

2
A comprehensive Python library for validating YAML documents against schemas. Yamale provides a powerful validation syntax supporting various data types (strings, integers, booleans, lists, maps), advanced constraints (min/max values, regex patterns, custom validators), recursive schema definitions through includes, and both strict and non-strict validation modes.
3

4
## Package Information
5

6
- **Package Name**: yamale
7
- **Language**: Python  
8
- **Installation**: `pip install yamale` or `pip install yamale[ruamel]` for YAML 1.2 support
9
- **Python Requirements**: 3.8+
10
- **Dependencies**: PyYAML (required), ruamel.yaml (optional)
11

12
## Core Imports
13

14
```python
15
import yamale
16
```
17

18
Common usage imports:
19

20
```python
21
from yamale import make_schema, make_data, validate, YamaleError, YamaleTestCase, __version__
22
from yamale.validators import DefaultValidators
23
```
24

25
## Basic Usage
26

27
```python
28
import yamale
29

30
# Check version
31
print(f"Yamale version: {yamale.__version__}")
32

33
# Create a schema from file
34
schema = yamale.make_schema('./schema.yaml')
35

36
# Load data to validate
37
data = yamale.make_data('./data.yaml')
38

39
# Validate data against schema
40
try:
41
    yamale.validate(schema, data)
42
    print('Validation success!')
43
except yamale.YamaleError as e:
44
    print('Validation failed!')
45
    for result in e.results:
46
        print(f"Error validating data '{result.data}' with '{result.schema}'")
47
        for error in result.errors:
48
            print(f"  {error}")
49
```
50

51
Example schema (`schema.yaml`):
52
```yaml
53
name: str()
54
age: int(max=200)
55
height: num()
56
awesome: bool()
57
```
58

59
Example valid data (`data.yaml`):
60
```yaml
61
name: Bill
62
age: 26
63
height: 6.2
64
awesome: True
65
```
66

67
## Architecture
68

69
Yamale follows a schema-driven validation architecture:
70

71
- **Schema**: Defines validation rules using YAML syntax with validator expressions
72
- **Validators**: Built-in validation classes for different data types and constraints
73
- **Data Parsing**: YAML file and content parsing with support for multiple parsers
74
- **Validation Engine**: Processes data against schema rules and generates detailed error reports
75
- **Includes System**: Enables schema composition and recursive validation structures
76

77
The library supports both programmatic API usage and command-line validation workflows, making it suitable for configuration validation, data processing pipelines, API input validation, and automated testing scenarios.
78

79
## Capabilities
80

81
### Core Validation Functions
82

83
Primary functions for schema creation, data loading, and validation that form the foundation of Yamale's functionality.
84

85
```python { .api }
86
def make_schema(path=None, parser="PyYAML", validators=None, content=None): ...
87
def make_data(path=None, parser="PyYAML", content=None): ...  
88
def validate(schema, data, strict=True, _raise_error=True): ...
89
```
90

91
[Core Functions](./core-functions.md)
92

93
### Schema Management
94

95
Schema creation, include management, and validation result handling for building complex validation structures.
96

97
```python { .api }
98
class Schema:
99
    def __init__(self, schema_dict, name="", validators=None, includes=None): ...
100
    def add_include(self, type_dict): ...
101
    def validate(self, data, path, strict): ...
102

103
class ValidationResult:
104
    def isValid(self): ...
105
    errors: list
106
    data: str
107
    schema: str
108
```
109

110
[Schema Management](./schema-management.md)
111

112
### Built-in Validators
113

114
Comprehensive set of validators for all common data types with constraint support for building robust validation schemas.
115

116
```python { .api }
117
# Core type validators
118
class String(Validator): ...    # str()
119
class Integer(Validator): ...   # int()  
120
class Number(Validator): ...    # num()
121
class Boolean(Validator): ...   # bool()
122
class Null(Validator): ...      # null()
123

124
# Collection validators  
125
class List(Validator): ...      # list()
126
class Map(Validator): ...       # map()
127

128
# Advanced validators
129
class Enum(Validator): ...      # enum()
130
class Any(Validator): ...       # any()
131
class Subset(Validator): ...    # subset()
132
class Include(Validator): ...   # include()
133
class Regex(Validator): ...     # regex()
134

135
# Specialized validators
136
class Day(Validator): ...       # day() - YYYY-MM-DD
137
class Timestamp(Validator): ... # timestamp() - YYYY-MM-DD HH:MM:SS  
138
class Ip(Validator): ...        # ip() - IPv4/IPv6
139
class Mac(Validator): ...       # mac() - MAC addresses
140
class SemVer(Validator): ...    # semver() - semantic versioning
141

142
# Version information
143
__version__: str                # Package version string
144

145
# Validator registry
146
DefaultValidators: dict         # Dictionary of all available validators
147
```
148

149
[Built-in Validators](./validators.md)
150

151
### Exception Handling
152

153
Error handling and testing utilities for comprehensive validation workflows and error reporting.
154

155
```python { .api }
156
class YamaleError(ValueError):
157
    def __init__(self, results): ...
158
    message: str
159
    results: list
160

161
class YamaleTestCase(TestCase):
162
    def validate(self, validators=None): ...
163
    schema: str
164
    yaml: str | list  
165
    base_dir: str
166
```
167

168
[Exception Handling](./exceptions.md)
169

170
### Command Line Interface
171

172
Command-line tools for validating YAML files in scripts and automated workflows.
173

174
```bash
175
yamale [options] [PATH ...]
176
```
177

178
[Command Line Interface](./cli.md)