0
# Format Validation
1

2
Extensible format checking system supporting built-in formats and custom format validators. Format validation is optional in JSON Schema but provides additional validation capabilities for string values.
3

4
## Capabilities
5

6
### FormatChecker
7

8
The main class for format validation, supporting both built-in and custom format validators.
9

10
```python { .api }
11
class FormatChecker:
12
    """
13
    A format property checker for JSON Schema format keyword validation.
14
    
15
    Attributes:
16
    - checkers: Dictionary mapping format names to checker functions
17
    """
18
    
19
    def __init__(self, formats=None):
20
        """
21
        Initialize format checker.
22
        
23
        Parameters:
24
        - formats: Iterable of format names to include (default: all available)
25
        """
26
    
27
    def check(self, instance, format):
28
        """
29
        Check if instance conforms to the given format.
30
        
31
        Parameters:
32
        - instance: Value to check
33
        - format: Format name to validate against
34
        
35
        Returns:
36
        - bool: True if valid, False if invalid or format unknown
37
        """
38
    
39
    def checks(self, format, raises=()):
40
        """
41
        Decorator to register a format checking function.
42
        
43
        Parameters:
44
        - format: Format name to register
45
        - raises: Exception types that indicate format errors
46
        
47
        Returns:
48
        - decorator: Function decorator
49
        """
50
    
51
    @classmethod
52
    def cls_checks(cls, format, raises=()):
53
        """
54
        Class method decorator for registering format checkers.
55
        
56
        Deprecated: Use instance-based checks() method instead.
57
        
58
        Parameters:
59
        - format: Format name to register
60
        - raises: Exception types that indicate format errors
61
        
62
        Returns:
63
        - decorator: Function decorator
64
        """
65
```
66

67
### Built-in Format Checkers
68

69
Pre-configured format checkers for each JSON Schema draft version.
70

71
```python { .api }
72
# Format checkers for each draft
73
draft202012_format_checker: FormatChecker
74
draft201909_format_checker: FormatChecker  
75
draft7_format_checker: FormatChecker
76
draft6_format_checker: FormatChecker
77
draft4_format_checker: FormatChecker
78
draft3_format_checker: FormatChecker
79
```
80

81
### Built-in Format Validation Functions
82

83
Individual format checking functions available for custom use.
84

85
```python { .api }
86
def is_email(instance):
87
    """
88
    Check if instance is a valid email address.
89
    
90
    Parameters:
91
    - instance: Value to check
92
    
93
    Returns:
94
    - bool: True if valid email format
95
    """
96

97
def is_ipv4(instance):
98
    """
99
    Check if instance is a valid IPv4 address.
100
    
101
    Parameters:
102
    - instance: Value to check
103
    
104
    Returns:
105
    - bool: True if valid IPv4 address
106
    """
107

108
def is_ipv6(instance):
109
    """
110
    Check if instance is a valid IPv6 address.
111
    
112
    Parameters:
113
    - instance: Value to check
114
    
115
    Returns:
116
    - bool: True if valid IPv6 address
117
    """
118

119
def is_regex(instance):
120
    """
121
    Check if instance is a valid regular expression.
122
    
123
    Parameters:
124
    - instance: Value to check
125
    
126
    Returns:
127
    - bool: True if valid regex pattern
128
    """
129

130
def is_date(instance):
131
    """
132
    Check if instance is a valid date string (YYYY-MM-DD).
133
    
134
    Parameters:
135
    - instance: Value to check
136
    
137
    Returns:
138
    - bool: True if valid date format
139
    """
140

141
def is_uuid(instance):
142
    """
143
    Check if instance is a valid UUID.
144
    
145
    Parameters:
146
    - instance: Value to check
147
    
148
    Returns:
149
    - bool: True if valid UUID format
150
    """
151

152
def is_draft3_time(instance):
153
    """
154
    Check if instance is a valid time string (Draft 3 format).
155
    
156
    Parameters:
157
    - instance: Value to check
158
    
159
    Returns:
160
    - bool: True if valid time format
161
    """
162
```
163

164
### Conditional Format Validation Functions
165

166
Format validation functions available when optional dependencies are installed:
167

168
```python { .api }
169
# Network and URI validation (requires rfc3986-validator or rfc3987)
170
def is_uri(instance):
171
    """Check if instance is a valid URI (requires rfc3986-validator or rfc3987)."""
172

173
def is_uri_reference(instance):
174
    """Check if instance is a valid URI reference (requires rfc3986-validator or rfc3987)."""
175

176
def is_iri(instance):
177
    """Check if instance is a valid IRI (requires rfc3987 or rfc3987-syntax)."""
178

179
def is_iri_reference(instance):
180
    """Check if instance is a valid IRI reference (requires rfc3987 or rfc3987-syntax)."""
181

182
# Hostname validation (requires fqdn and idna)
183
def is_host_name(instance):
184
    """Check if instance is a valid hostname (requires fqdn)."""
185

186
def is_idn_host_name(instance):
187
    """Check if instance is a valid internationalized hostname (requires idna)."""
188

189
# Date/time validation (requires rfc3339-validator)
190
def is_datetime(instance):
191
    """Check if instance is a valid RFC 3339 date-time (requires rfc3339-validator)."""
192

193
def is_time(instance):
194
    """Check if instance is a valid time string (requires rfc3339-validator)."""
195

196
# JSON Pointer validation (requires jsonpointer)
197
def is_json_pointer(instance):
198
    """Check if instance is a valid JSON Pointer (requires jsonpointer)."""
199

200
def is_relative_json_pointer(instance):
201
    """Check if instance is a valid relative JSON Pointer (requires jsonpointer)."""
202

203
# Other format validation (requires various packages)
204
def is_css21_color(instance):
205
    """Check if instance is a valid CSS 2.1 color (requires webcolors)."""
206

207
def is_uri_template(instance):
208
    """Check if instance is a valid URI template (requires uri-template)."""
209

210
def is_duration(instance):
211
    """Check if instance is a valid ISO 8601 duration (requires isoduration)."""
212
```
213

214
## Usage Examples
215

216
### Basic Format Validation
217

218
```python
219
from jsonschema import Draft202012Validator, FormatChecker, ValidationError
220

221
schema = {
222
    "type": "object",
223
    "properties": {
224
        "email": {"type": "string", "format": "email"},
225
        "website": {"type": "string", "format": "uri"},
226
        "created": {"type": "string", "format": "date-time"}
227
    }
228
}
229

230
# Create validator with format checking
231
format_checker = FormatChecker()
232
validator = Draft202012Validator(schema, format_checker=format_checker)
233

234
# Valid data
235
valid_data = {
236
    "email": "user@example.com",
237
    "website": "https://example.com",
238
    "created": "2023-12-25T10:30:00Z"
239
}
240

241
try:
242
    validator.validate(valid_data)
243
    print("Valid!")
244
except ValidationError as e:
245
    print(f"Format error: {e.message}")
246

247
# Invalid format
248
invalid_data = {
249
    "email": "not-an-email",
250
    "website": "not-a-uri",
251
    "created": "not-a-datetime"
252
}
253

254
errors = list(validator.iter_errors(invalid_data))
255
for error in errors:
256
    print(f"Format error: {error.message}")
257
```
258

259
### Custom Format Validation
260

261
```python
262
from jsonschema import FormatChecker, Draft202012Validator
263

264
# Create custom format checker
265
format_checker = FormatChecker()
266

267
@format_checker.checks('phone')
268
def is_phone_number(instance):
269
    """Check if instance is a valid phone number."""
270
    if not isinstance(instance, str):
271
        return False
272
    # Simple phone validation (customize as needed)
273
    import re
274
    pattern = r'^\+?1?-?\.?\s?\(?([0-9]{3})\)?[-\.\s]?([0-9]{3})[-\.\s]?([0-9]{4})$'
275
    return bool(re.match(pattern, instance))
276

277
@format_checker.checks('ssn', raises=ValueError)
278
def is_ssn(instance):
279
    """Check if instance is a valid SSN."""
280
    if not isinstance(instance, str):
281
        return False
282
    import re
283
    pattern = r'^\d{3}-\d{2}-\d{4}$'
284
    if not re.match(pattern, instance):
285
        raise ValueError("Invalid SSN format")
286
    return True
287

288
# Use custom formats in schema
289
schema = {
290
    "type": "object",
291
    "properties": {
292
        "phone": {"type": "string", "format": "phone"},
293
        "ssn": {"type": "string", "format": "ssn"}
294
    }
295
}
296

297
validator = Draft202012Validator(schema, format_checker=format_checker)
298

299
# Test custom formats
300
test_data = {
301
    "phone": "+1-555-123-4567",
302
    "ssn": "123-45-6789"
303
}
304

305
validator.validate(test_data)  # Should pass
306
```
307

308
### Selective Format Checking
309

310
```python
311
from jsonschema import FormatChecker, Draft202012Validator
312

313
# Create format checker with only specific formats
314
format_checker = FormatChecker(['email', 'date', 'ipv4'])
315

316
schema = {
317
    "type": "object",
318
    "properties": {
319
        "email": {"type": "string", "format": "email"},
320
        "date": {"type": "string", "format": "date"},
321
        "ip": {"type": "string", "format": "ipv4"},
322
        "uri": {"type": "string", "format": "uri"}  # This won't be checked
323
    }
324
}
325

326
validator = Draft202012Validator(schema, format_checker=format_checker)
327

328
data = {
329
    "email": "user@example.com",
330
    "date": "2023-12-25", 
331
    "ip": "192.168.1.1",
332
    "uri": "not-a-valid-uri"  # No error - format not enabled
333
}
334

335
validator.validate(data)  # Passes because 'uri' format not checked
336
```
337

338
### Using Built-in Format Functions
339

340
```python
341
from jsonschema._format import is_email, is_ipv4, is_date
342

343
# Direct format checking
344
print(is_email("user@example.com"))    # True
345
print(is_email("invalid-email"))       # False
346

347
print(is_ipv4("192.168.1.1"))         # True
348
print(is_ipv4("999.999.999.999"))     # False
349

350
print(is_date("2023-12-25"))          # True
351
print(is_date("invalid-date"))        # False
352
```
353

354
### Format Validation with Error Details
355

356
```python
357
from jsonschema import Draft202012Validator, FormatChecker, ValidationError
358

359
format_checker = FormatChecker()
360
schema = {"type": "string", "format": "email"}
361
validator = Draft202012Validator(schema, format_checker=format_checker)
362

363
try:
364
    validator.validate("not-an-email")
365
except ValidationError as e:
366
    print(f"Format validation failed: {e.message}")
367
    print(f"Validator: {e.validator}")  # 'format'
368
    print(f"Format: {e.validator_value}")  # 'email'
369
    print(f"Instance: {e.instance}")  # 'not-an-email'
370
```
371

372
### Available Built-in Formats
373

374
Common formats supported by the built-in format checkers:
375

376
- **email**: Email address validation
377
- **uri**: URI validation  
378
- **uri-reference**: URI reference validation
379
- **iri**: Internationalized Resource Identifier
380
- **iri-reference**: IRI reference validation
381
- **ipv4**: IPv4 address validation
382
- **ipv6**: IPv6 address validation
383
- **hostname**: Hostname validation
384
- **idn-hostname**: Internationalized hostname
385
- **date**: Full date (YYYY-MM-DD)
386
- **time**: Time of day
387
- **date-time**: Date and time
388
- **duration**: Duration string
389
- **uuid**: UUID validation
390
- **regex**: Regular expression pattern
391
- **json-pointer**: JSON Pointer validation
392
- **relative-json-pointer**: Relative JSON Pointer
393
- **uri-template**: URI template validation
394

395
Format availability may vary by draft version and optional dependencies.