0
# Results and Output
1

2
Structured result classes and output formatting functions for handling validation outcomes, including error reporting, success indicators, and formatted console output with color coding.
3

4
## Capabilities
5

6
### FileValidationResults Class
7

8
Container for validation results when validating files, including file-level information and individual object validation results.
9

10
```python { .api }
11
class FileValidationResults:
12
    """
13
    Results for file validation operations.
14
    
15
    Parameters:
16
    - is_valid (bool): Whether the overall validation result is valid (default: False)
17
    - filepath (str, optional): Which file was validated
18
    - object_results (List[ObjectValidationResults], optional): Individual object validation results
19
    - fatal (Exception, optional): A non-validation-related fatal error
20
    
21
    Properties:
22
    - object_result: Get the object result object, assuming there is only one
23
    - object_results: Get all object results
24
    - is_valid: Returns True if validation was successful and False otherwise
25
    
26
    Methods:
27
    - as_dict(): Return a dictionary representation
28
    - log(): Print (log) these file validation results
29
    - as_json(): Returns a JSON representation of this class instance
30
    """
31
    
32
    def __init__(self, is_valid=False, filepath=None, object_results=None, fatal=None):
33
        pass
34
    
35
    @property
36
    def object_result(self):
37
        """Get the single object result (for files with one STIX object)."""
38
        pass
39
    
40
    @property
41
    def object_results(self):
42
        """Get all object results."""
43
        pass
44
    
45
    def as_dict(self):
46
        """Return dictionary representation of results."""
47
        pass
48
    
49
    def log(self):
50
        """Print these file validation results."""
51
        pass
52
    
53
    def as_json(self):
54
        """Return JSON representation of results."""
55
        pass
56
```
57

58
**Example Usage:**
59

60
```python
61
from stix2validator import validate_file
62

63
# Validate a file and examine results
64
results = validate_file("threat_indicators.json")
65

66
print(f"File: {results.filepath}")
67
print(f"Valid: {results.is_valid}")
68

69
# Access individual object results
70
if results.object_results:
71
    for obj_result in results.object_results:
72
        print(f"Object {obj_result.object_id}: {obj_result.is_valid}")
73
        if obj_result.errors:
74
            for error in obj_result.errors:
75
                print(f"  Error: {error}")
76

77
# For single-object files, use object_result property
78
if results.object_result:
79
    single_result = results.object_result
80
    print(f"Single object validation: {single_result.is_valid}")
81

82
# Convert to dictionary for serialization
83
result_dict = results.as_dict()
84
print(f"Result dict: {result_dict}")
85

86
# Log results with formatting
87
results.log()
88
```
89

90
### ObjectValidationResults Class
91

92
Container for validation results of individual STIX objects, including detailed error and warning information.
93

94
```python { .api }
95
class ObjectValidationResults:
96
    """
97
    Results for individual STIX object validation.
98
    
99
    Parameters:
100
    - is_valid (bool): The validation result (default: False)
101
    - object_id (str, optional): ID of the STIX object
102
    - errors (List[str], optional): List of validation error messages
103
    - warnings (List[str], optional): List of validation warning messages
104
    
105
    Properties:
106
    - errors: A list of SchemaError validation errors
107
    - is_valid: Returns True if validation was successful and False otherwise
108
    
109
    Methods:
110
    - as_dict(): A dictionary representation of the ObjectValidationResults instance
111
    - log(): Print (log) these object validation results
112
    - as_json(): Returns a JSON representation of this class instance
113
    """
114
    
115
    def __init__(self, is_valid=False, object_id=None, errors=None, warnings=None):
116
        pass
117
    
118
    def as_dict(self):
119
        """Return dictionary representation of object results."""
120
        pass
121
    
122
    def log(self):
123
        """Print these object validation results."""
124
        pass
125
    
126
    def as_json(self):
127
        """Return JSON representation of results."""
128
        pass
129
```
130

131
**Example Usage:**
132

133
```python
134
from stix2validator import validate_string
135

136
# Validate a STIX object string
137
stix_json = '''
138
{
139
    "type": "indicator",
140
    "spec_version": "2.1",
141
    "id": "indicator--12345678-1234-1234-1234-123456789012",
142
    "created": "2023-01-01T00:00:00.000Z",
143
    "modified": "2023-01-01T00:00:00.000Z",
144
    "pattern": "[file:hashes.MD5 = 'invalid-hash']",
145
    "labels": ["malicious-activity"]
146
}
147
'''
148

149
result = validate_string(stix_json)
150

151
# Examine object validation results
152
print(f"Object ID: {result.object_id}")
153
print(f"Valid: {result.is_valid}")
154

155
# Check for errors and warnings
156
if result.errors:
157
    print("Errors:")
158
    for error in result.errors:
159
        print(f"  - {error}")
160

161
if result.warnings:
162
    print("Warnings:")
163
    for warning in result.warnings:
164
        print(f"  - {warning}")
165

166
# Convert to structured data
167
result_data = result.as_dict()
168
json_data = result.as_json()
169

170
# Log with formatting
171
result.log()
172
```
173

174
### ValidationErrorResults Class
175

176
Special result container for handling validation exceptions and fatal errors during the validation process.
177

178
```python { .api }
179
class ValidationErrorResults:
180
    """
181
    Results for validation errors and exceptions.
182
    
183
    Parameters:
184
    - error (Exception): An Exception instance raised by validation code
185
    
186
    Properties:
187
    - is_valid: Always False
188
    - error: The string representation of the Exception being passed in
189
    - exception: The exception which produced these results
190
    
191
    Methods:
192
    - as_dict(): Return a dictionary representation
193
    - as_json(): Returns a JSON representation of this class instance
194
    """
195
    
196
    def __init__(self, error):
197
        pass
198
    
199
    @property
200
    def is_valid(self):
201
        """Always returns False for error results."""
202
        return False
203
    
204
    def as_dict(self):
205
        """Return dictionary representation of error results."""
206
        pass
207
    
208
    def as_json(self):
209
        """Return JSON representation of error results."""
210
        pass
211
```
212

213
### Output Formatting Functions
214

215
Functions for controlling and formatting validation output, including color-coded console output and verbosity control.
216

217
```python { .api }
218
def print_results(results):
219
    """
220
    Print results (the results of validation) to stdout with color coding.
221
    
222
    Parameters:
223
    - results (Union[List[FileValidationResults], List[ObjectValidationResults]]): 
224
      A list of validation result instances
225
    
226
    Returns:
227
    None
228
    
229
    Description:
230
    Formats and prints validation results with color coding:
231
    - Green for successful validation
232
    - Yellow for warnings
233
    - Red for errors and failures
234
    """
235

236
def set_level(verbose_output=False):
237
    """
238
    Set the output level for the application.
239
    
240
    Parameters:
241
    - verbose_output (bool): Enable verbose output mode (default: False)
242
    
243
    Returns:
244
    None
245
    
246
    Description:
247
    Controls output verbosity. When False, only results or fatal errors
248
    are printed. When True, includes informational messages and detailed
249
    error descriptions.
250
    """
251

252
def set_silent(silence_output=False):
253
    """
254
    Set the silent flag for the application.
255
    
256
    Parameters:
257
    - silence_output (bool): Enable silent mode (default: False)
258
    
259
    Returns:
260
    None
261
    
262
    Description:
263
    When True, suppresses all output to stdout. Useful for programmatic
264
    usage where only return values are needed.
265
    """
266

267
def error(msg):
268
    """
269
    Print a message to stderr prepended by '[X]'.
270
    
271
    Parameters:
272
    - msg (str): The error message to print
273
    
274
    Returns:
275
    None
276
    """
277

278
def info(msg):
279
    """
280
    Print a message to stdout, prepended by '[-]'.
281
    
282
    Parameters:
283
    - msg (str): The message to print
284
    
285
    Returns:
286
    None
287
    
288
    Description:
289
    Only prints if the application is running in verbose mode.
290
    Returns immediately in non-verbose mode.
291
    """
292
```
293

294
**Example Usage:**
295

296
```python
297
from stix2validator import validate_file, print_results, set_level, set_silent
298
from stix2validator.output import error, info
299

300
# Configure output settings
301
set_level(verbose_output=True)  # Enable verbose mode
302
# set_silent(silence_output=True)  # Or enable silent mode
303

304
# Validate multiple files
305
file_results = []
306
files = ["indicators.json", "malware.json", "threat_report.json"]
307

308
for filename in files:
309
    try:
310
        result = validate_file(filename)
311
        file_results.append(result)
312
        
313
        # Custom result processing
314
        if result.is_valid:
315
            info(f"Successfully validated {filename}")
316
        else:
317
            error(f"Validation failed for {filename}")
318
            
319
    except Exception as e:
320
        error(f"Could not validate {filename}: {e}")
321

322
# Print all results with color coding
323
print_results(file_results)
324

325
# Manual result formatting
326
for result in file_results:
327
    print(f"\n=== {result.filepath} ===")
328
    if result.is_valid:
329
        print("✓ VALID")
330
    else:
331
        print("✗ INVALID")
332
        for obj_result in result.object_results:
333
            if obj_result.errors:
334
                print(f"Object {obj_result.object_id}:")
335
                for error_msg in obj_result.errors:
336
                    print(f"  • {error_msg}")
337
```
338

339
## Advanced Result Processing
340

341
### Batch Result Analysis
342

343
```python
344
from stix2validator import run_validation, ValidationOptions
345

346
# Run batch validation
347
options = ValidationOptions(
348
    files=["stix_data/"],
349
    recursive=True,
350
    version="2.1"
351
)
352

353
results = run_validation(options)
354

355
# Analyze batch results
356
total_files = len(results)
357
valid_files = sum(1 for r in results if r.is_valid)
358
invalid_files = total_files - valid_files
359

360
print(f"Validation Summary:")
361
print(f"  Total files: {total_files}")
362
print(f"  Valid files: {valid_files}")
363
print(f"  Invalid files: {invalid_files}")
364
print(f"  Success rate: {(valid_files/total_files)*100:.1f}%")
365

366
# Detailed error analysis
367
error_types = {}
368
for result in results:
369
    if not result.is_valid:
370
        for obj_result in result.object_results:
371
            for error in obj_result.errors:
372
                error_type = str(error).split(':')[0]
373
                error_types[error_type] = error_types.get(error_type, 0) + 1
374

375
print(f"\nError Type Distribution:")
376
for error_type, count in sorted(error_types.items()):
377
    print(f"  {error_type}: {count}")
378
```
379

380
### Result Serialization
381

382
```python
383
import json
384
from stix2validator import validate_file
385

386
# Validate and serialize results
387
result = validate_file("threat_data.json")
388

389
# Convert to dictionary for storage
390
result_dict = result.as_dict()
391

392
# Save to file
393
with open("validation_result.json", "w") as f:
394
    json.dump(result_dict, f, indent=2)
395

396
# Or use built-in JSON serialization
397
json_result = result.as_json()
398
print(json_result)
399

400
# Load and process saved results
401
with open("validation_result.json", "r") as f:
402
    loaded_result = json.load(f)
403
    
404
if loaded_result["is_valid"]:
405
    print("Previous validation was successful")
406
else:
407
    print("Previous validation failed:")
408
    for obj in loaded_result.get("object_results", []):
409
        for error in obj.get("errors", []):
410
            print(f"  - {error}")
411
```
412

413
### Custom Result Handlers
414

415
```python
416
from stix2validator import validate_string, ValidationOptions
417
from stix2validator.output import set_silent
418

419
class ValidationResultHandler:
420
    def __init__(self):
421
        self.results = []
422
        self.error_count = 0
423
        self.warning_count = 0
424
    
425
    def handle_result(self, result):
426
        self.results.append(result)
427
        
428
        if hasattr(result, 'object_results'):
429
            # File result
430
            for obj_result in result.object_results:
431
                self.error_count += len(obj_result.errors or [])
432
                self.warning_count += len(obj_result.warnings or [])
433
        else:
434
            # Object result
435
            self.error_count += len(result.errors or [])
436
            self.warning_count += len(result.warnings or [])
437
    
438
    def summary(self):
439
        return {
440
            "total_validations": len(self.results),
441
            "total_errors": self.error_count,
442
            "total_warnings": self.warning_count
443
        }
444

445
# Use custom handler
446
set_silent(True)  # Disable standard output
447
handler = ValidationResultHandler()
448

449
stix_objects = [
450
    '{"type": "indicator", ...}',
451
    '{"type": "malware", ...}',
452
    '{"type": "threat-actor", ...}'
453
]
454

455
for stix_json in stix_objects:
456
    result = validate_string(stix_json)
457
    handler.handle_result(result)
458

459
print(handler.summary())
460
```