0
# Schematics
1

2
A Python library for data validation and transformation using structured models. Schematics provides a type system for defining data structures with field-level validation, format conversion, and comprehensive error handling - enabling developers to build robust APIs, data processors, and validation systems without database dependencies.
3

4
## Package Information
5

6
- **Package Name**: schematics
7
- **Language**: Python
8
- **Installation**: `pip install schematics`
9

10
## Core Imports
11

12
```python { .api }
13
from schematics.models import Model
14
```
15

16
Common for working with field types:
17

18
```python { .api }
19
from schematics.types import StringType, IntType, DateTimeType, ListType, ModelType
20
```
21

22
For error handling:
23

24
```python { .api }
25
from schematics.exceptions import ValidationError, ConversionError
26
```
27

28
## Basic Usage
29

30
```python { .api }
31
from schematics.models import Model
32
from schematics.types import StringType, IntType, DateTimeType, EmailType
33

34
# Define a data model
35
class User(Model):
36
    name = StringType(required=True, max_length=100)
37
    email = EmailType(required=True)
38
    age = IntType(min_value=0, max_value=120)
39
    created_at = DateTimeType()
40

41
# Create an instance and validate data
42
user_data = {
43
    'name': 'John Doe',
44
    'email': 'john@example.com',
45
    'age': 30
46
}
47

48
user = User(user_data)
49
user.validate()  # Raises ValidationError if invalid
50

51
# Convert to different formats
52
native_dict = user.to_native()      # Python objects  
53
primitive_dict = user.to_primitive() # JSON-serializable
54

55
# Export with field filtering
56
filtered = user.export(fields=['name', 'email'])
57
```
58

59
## Architecture
60

61
Schematics uses a field-based type system built around several core concepts:
62

63
- **Model**: Container class defining data structure with fields and validation rules
64
- **Field Types**: Typed field classes handling conversion, validation, and serialization  
65
- **Validation System**: Multi-level validation with field and model-level rules
66
- **Export System**: Flexible data serialization with filtering and format control
67
- **Exception Hierarchy**: Structured error handling with detailed validation feedback
68

69
This design enables schematics to serve as a validation layer for APIs, data pipelines, configuration systems, and any application requiring structured data handling without database coupling.
70

71
## Capabilities
72

73
### Model System
74

75
Core model definition and data management functionality including model creation, field registration, data import/export, and validation orchestration.
76

77
```python { .api }
78
class Model:
79
    def __init__(self, raw_data=None, **context)
80
    def validate(self, **context)
81
    def import_data(self, raw_data, **context)  
82
    def export(self, fields=None, exclude=None, **context)
83
    def to_native(self)
84
    def to_primitive(self)
85
```
86

87
[Model System](./models.md)
88

89
### Basic Field Types
90

91
Essential field types for common data including strings, numbers, dates, booleans, and specialized types like UUIDs and hashes with comprehensive validation options.
92

93
```python { .api }
94
class StringType(BaseType):
95
    def __init__(self, regex=None, max_length=None, min_length=None, **kwargs)
96

97
class IntType(BaseType):
98
    def __init__(self, min_value=None, max_value=None, **kwargs)
99
    
100
class DateTimeType(BaseType):
101
    def __init__(self, formats=None, **kwargs)
102
    
103
class BooleanType(BaseType):
104
    def __init__(self, **kwargs)
105
```
106

107
[Basic Field Types](./basic-types.md)
108

109
### Compound Field Types
110

111
Advanced field types for complex data structures including lists, dictionaries, nested models, and polymorphic model fields with recursive validation.
112

113
```python { .api }
114
class ListType(BaseType):
115
    def __init__(self, field, min_size=None, max_size=None, **kwargs)
116
    
117
class DictType(BaseType):
118
    def __init__(self, field=None, **kwargs)
119
    
120
class ModelType(BaseType):
121
    def __init__(self, model_class, **kwargs)
122
    
123
class PolyModelType(BaseType):
124
    def __init__(self, model_spec, **kwargs)
125
```
126

127
[Compound Field Types](./compound-types.md)
128

129
### Network Field Types
130

131
Specialized field types for network-related data including URLs, email addresses, IP addresses, and MAC addresses with protocol-specific validation.
132

133
```python { .api }
134
class URLType(BaseType):
135
    def __init__(self, verify_exists=False, **kwargs)
136
    
137
class EmailType(BaseType):
138
    def __init__(self, **kwargs)
139
    
140
class IPAddressType(BaseType):
141
    def __init__(self, **kwargs)
142
```
143

144
[Network Field Types](./network-types.md)
145

146
### Exception System
147

148
Comprehensive exception hierarchy for handling validation errors, conversion failures, and data processing issues with detailed error information and field-level granularity.
149

150
```python { .api }
151
class ValidationError(FieldError):
152
    def __init__(self, message, **kwargs)
153
    
154
class ConversionError(FieldError):
155
    def __init__(self, message, **kwargs)
156
    
157
class DataError(BaseError):
158
    def __init__(self, errors, partial_data=None, **kwargs)
159
```
160

161
[Exception System](./exceptions.md)
162

163
### Dynamic Fields
164

165
Advanced field functionality including serializable computed fields, calculated properties, and dynamic field generation for flexible data modeling.
166

167
```python { .api }
168
def serializable(func=None, **field_kwargs)
169
def calculated(func, **field_kwargs)
170

171
class Serializable:
172
    def __init__(self, **kwargs)
173
```
174

175
[Dynamic Fields](./dynamic-fields.md)
176

177
### Utilities and Helpers
178

179
Utility classes and functions supporting Schematics functionality including role-based field filtering, validation helpers, and collection utilities.
180

181
```python { .api }
182
class Role(Set):
183
    def __init__(self, function, fields)
184

185
def import_string(import_name)
186
def listify(value)
187
def get_ident()
188
class Constant(int)
189
```
190

191
[Utilities and Helpers](./utilities.md)
192

193
### Contrib Modules
194

195
Additional field types and utilities provided as contrib modules including MongoDB integration, enum support, and state machine functionality.
196

197
```python { .api }
198
class ObjectIdType(BaseType):  # MongoDB ObjectId support
199
    def __init__(self, auto_fill=False, **kwargs)
200

201
class EnumType(BaseType):  # Python enum support  
202
    def __init__(self, enum, use_values=False, **kwargs)
203

204
class Machine:  # Simple state machine
205
    def __init__(self, data, *args)
206
```
207

208
[Contrib Modules](./contrib-modules.md)
209

210
## Types
211

212
```python { .api }
213
# Export control constants
214
NATIVE: int = 0        # Native Python objects
215
PRIMITIVE: int = 1     # JSON-serializable primitives  
216
DROP: int = 0         # Drop/exclude fields
217
NONEMPTY: int = 1     # Only non-empty fields
218
NOT_NONE: int = 2     # Only non-None fields
219
DEFAULT: int = 10     # Default export behavior
220
ALL: int = 99         # Export all fields
221

222
# Context and validation types
223
class Context:
224
    def __init__(self, **kwargs)
225
    
226
class ValidationContext:
227
    def __init__(self, **kwargs)
228

229
# Special value representing undefined field state
230
class Undefined:
231
    """Sentinel value representing undefined/unset field state."""
232
    pass
233
```