The stix-validator library provides methods and data types to help perform STIX Best Practices validation.
Warning
The STIX Best Practices validation capabilities are under active development and do not cover all STIX Best Practices.
The following code examples demonstrate different ways you can utilize the STIX Best Practices validation capabilities in stix-validator.
The stix-validator sdv.validate_best_practices
method can be used to validate STIX XML files or file-like objects against STIX Best Practices.
import sdv
# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')
# Print the result!
print results.is_valid
The sdv.validate_best_practices
method acts as a proxy to the .STIXBestPracticeValidator
class and is equivalent to the following:
from sdv.validators import STIXBestPracticeValidator
# Create the validator instance
validator = STIXBestPracticeValidator()
# Validate 'stix-content.xml` STIX document
results = validator.validate('stix-content.xml')
# Print the results!
print results.is_valid
The examples above pass the 'stix-content.xml'
filename into sdv.validate_profile
and .STIXProfileValidator.validate
, but these methods can also accept file-like objects (such as files on disk or StringIO
instances), etree._Element
instances, or etree._ElementTree
instances. Neato!
The following sections explain how to retrieve STIX Best Practices validation errors from the .BestPracticeValidationResults
class.
STIX Best Practices validation results are communicated via the .BestPracticeValidationResults
, .BestPracticeWarningCollection
, and .BestPracticeWarning
classes.
The sdv.validate_best_practices
and .STIXBestPracticeValidator.validate
methods both return an instance of .BestPracticeValidationResults
.
To determine if a document was valid, users only need to inspect the is_valid
property:
import sdv
# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')
# Print the result!
print results.is_valid
If the is_valid
property is False
, users can inspect the errors
property to retrieve specific validation errors, or iterate over the BestPracticeValidationResults
class directly.
The errors
property on .BestPracticeValidationResults
contains a list of .BestPracticeWarningCollection
instances, which hold details about the validation errors and methods for accessing those details.
Every deviation from STIX Best Practices within an instance document is represented as an instance of .BestPracticeWarning
. These violations are categorized and collected within instances of .BestPracticeWarningCollection
instances, which are each assigned names, such as "Missing Titles"
, or "Duplicate IDs"
.
The errors
property on .BestPracticeValidationResults
contains a list of .BestPracticeWarningCollection
instances, which hold details about the validation errors and methods for accessing those details.
import sdv
# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')
# If 'stix-content.xml' is invalid, print each error
if not results.is_valid:
for coll in results.errors:
print_best_practice_collection(coll) # User-defined print method
The example above iterates over the result.errors
property, and calls a user-defined, print_best_practice_collection()
.
This function could be defined as the following:
def print_best_practice_collection(coll):
"""
Prints BestPracticeWarningCollection info to stdout.
"""
# Print the Best Practice Warning collection name
print coll.name
# Print the line and XML tag for each non-conformant node in the
# warning collection.
for warning in coll:
print warning.line, warning.tag
Users wanting to work with dictionaries or pass around JSON blobs can make use of the .BestPracticeValidationResults.as_dict()
and .BestPracticeValidationResults.as_json()
methods.
import sdv
# Check the 'stix-content.xml' document for STIX Best Practices conformance
results = sdv.validate_best_practices('stix-content.xml')
# Retrieve results as dictionary
result_dictionary = results.as_dict() # returns {'result': True} if valid
# Retrieve results as JSON
result_json = results.as_json() # returns '{"result": true}' JSON if valid