CWE Schema
Types and operations for CWE schema management, validation, and version control. Handles schema loading, constraint validation, and freeze operations for version locking.
Schema Results
ci.transparency.cwe.types.cwe.schema.results
CWE schema result types for loading and validation using composition.
Domain-specific result holders used by CWE schema loading/parsing and CWE instance-vs-schema validation. Built using composition of base building blocks for clean separation of concerns.
Design principles
- Composition-based: uses base building blocks for reusable functionality
- Consistent shape across loading and validation operations
- Minimal memory footprint with frozen dataclasses
- Type-safe: follows Python 3.12+ and pyright strict conventions
- Friendly to functional updates and transformations
Core CWE schema results
- CweSchemaLoadingResult: Outcome of loading/parsing CWE schemas
- CweSchemaValidationResult: Outcome of validating CWE data against a schema
__all__ = ['CweSchemaLoadingResult', 'CweSchemaValidationResult', 'CweSchemaItemDict', 'CweSchemaDataDict', 'LoadingSummaryDict', 'ValidationSummaryDict', 'SchemaCollection', 'add_cwe_schema', 'track_invalid_schema_file', 'track_skipped_schema_file', 'set_schema_metadata', 'create_successful_validation', 'create_failed_validation', 'add_validation_error', 'add_validation_warning', 'get_cwe_schema_loading_summary', 'get_cwe_schema_validation_summary']
module-attribute
CweSchemaDataDict = dict[str, CweSchemaItemDict]
LoadingSummaryDict = dict[str, Any]
ValidationSummaryDict = dict[str, Any]
CweSchemaItemDict
Bases: TypedDict
Typed structure for CWE schema data.
CweSchemaLoadingResult
dataclass
Result of loading/parsing CWE schemas using composition.
Composes base building blocks for clean separation of concerns.
Attributes
schemas : CweSchemaDataDict Dictionary of loaded CWE schema data. loading : LoadingCounts Statistics about loading success and failures. messages : MessageCollection Collection of error, warning, and info messages. files : FileCollection Tracking of processed, failed, and skipped files. schema_metadata : SchemaCollection Schema-specific metadata and file type tracking. duplicates : DuplicateCollection Tracking of duplicate schema IDs and their associated files.
is_successful
property
Return True if loading is successful and there are no error messages.
loaded_schema_ids
property
All loaded schema IDs (sorted for stable output).
schema_count
property
Return the number of schemas loaded.
schema_name
property
Schema name from metadata.
schema_version
property
Schema version from metadata.
add_error(msg)
Add error message (added by decorator).
add_info(msg)
Add info message (added by decorator).
add_warning(msg)
Add warning message (added by decorator).
get_schema(schema_id)
Get schema data by ID.
has_schema(schema_id)
Check if a schema ID was loaded.
CweSchemaValidationResult
dataclass
Result of validating CWE data against a schema using composition.
Attributes
validation : ValidationCounts Statistics about validation success and failures. messages : MessageCollection Collection of error, warning, and info messages. schema_metadata : SchemaCollection Schema-specific metadata. cwe_id : str | None CWE identifier being validated. field_path : str | None Path to the field being validated. is_schema_valid : bool Whether the validation passed.
is_successful
property
Return True if validation is successful and there are no error messages.
schema_name
property
Schema name from metadata.
schema_version
property
Schema version from metadata.
validation_target
property
Get a description of what was validated.
add_error(msg)
Add error message (added by decorator).
add_info(msg)
Add info message (added by decorator).
add_warning(msg)
Add warning message (added by decorator).
DuplicateCollection
dataclass
Tracks duplicate IDs and their associated file paths.
Attributes
duplicate_ids : dict[str, list[Path]] Dictionary mapping duplicate IDs to lists of file paths where duplicates were found.
duplicate_count
property
Return the number of duplicate IDs tracked in the collection.
Returns
int The number of duplicate IDs.
has_duplicates
property
Return True if there are any duplicate IDs, otherwise False.
FileCollection
dataclass
Tracks processed, failed, and skipped files.
Attributes
processed_files : list[Path] list of files that have been processed. failed_files : list[Path] list of files that failed to process. skipped_files : list[Path] list of files that were skipped.
failed_file_count
property
Return the number of failed files.
processed_file_count
property
Return the number of processed files.
skipped_file_count
property
Return the number of skipped files.
total_files
property
Return the total number of files (processed, failed, skipped).
LoadingCounts
dataclass
Tracks the number of successfully loaded and failed items.
Attributes
loaded_count : int Number of items successfully loaded. failed_count : int Number of items that failed to load.
is_successful
property
Return True if there are no failed validations, otherwise False.
success_rate
property
Return the rate of successful loads as a float between 0 and 1.
total_attempted
property
Return the total number of attempted loads (successful + failed).
MessageCollection
dataclass
Collects error, warning, and info messages.
Attributes
errors : list[str] list of error messages. warnings : list[str] list of warning messages. infos : list[str] list of informational messages.
error_count
property
Return the number of error messages.
has_errors
property
Return True if there are any error messages, otherwise False.
has_warnings
property
Return True if there are any warning messages, otherwise False.
info_count
property
Return the number of informational messages.
total_messages
property
Return the total number of messages (errors, warnings, infos).
warning_count
property
Return the number of warning messages.
SchemaCollection
dataclass
Tracks schema metadata and statistics.
Could be reused for any domain that works with schemas.
file_type_count
property
Number of different file types processed.
has_schema_metadata
property
True if schema name and version are available.
add_file_type(file_type)
Add or increment a file type count.
with_metadata(schema_name, schema_version)
Return new collection with updated schema metadata.
ValidationCounts
dataclass
Tracks the number of passed and failed validations.
Attributes
passed_count : int Number of items that passed validation. failed_count : int Number of items that failed validation.
is_successful
property
Return True if there are no failed validations, otherwise False.
pass_rate
property
Return the rate of passed validations as a float between 0 and 1.
total_validated
property
Return the total number of validated items (passed + failed).
_add_duplicate(duplicates, item_id, file_path)
Add a duplicate ID with its file path.
_add_failed_file(files, file_path)
Add a failed file.
_add_file_type(schema_metadata, file_type)
Add or increment a file type count.
_add_message(messages, level, message)
Add a message to the message collection.
_add_processed_file(files, file_path)
Add a processed file.
_add_skipped_file(files, file_path)
Add a skipped file.
_increment_loading_counts(counts, *, succeeded=0, failed=0)
Increment loading counts.
_increment_validation_counts(counts, *, passed=0, failed=0)
Increment validation counts.
add_cwe_schema(result, schema_id, schema_data, *, file_path=None)
Add successfully loaded CWE schema to the result.
add_validation_error(result, error_message)
Add an error to the validation result.
add_validation_warning(result, warning_message)
Add a warning to the validation result.
create_failed_validation(*, error_messages=None, warning_messages=None, schema_name=None, schema_version=None, cwe_id=None, field_path=None)
Create a failed validation result.
create_successful_validation(*, schema_name=None, schema_version=None, cwe_id=None, field_path=None, info_message=None)
Create a successful validation result.
get_cwe_schema_loading_summary(result)
Generate CWE schema loading summary.
get_cwe_schema_validation_summary(result)
Generate CWE schema validation summary.
set_schema_metadata(result, schema_name, schema_version)
Set schema metadata for the loading result.
track_invalid_schema_file(result, file_path, reason)
Track an invalid CWE schema file.
track_skipped_schema_file(result, file_path, reason)
Track a skipped CWE schema file.
with_message_methods(cls)
Add message methods to result classes.
Decorator that adds add_error(), add_warning(), and add_info() methods to any result class with a MessageCollection field.
options: showsource: false show_signature: true group_by_category: true filters: - "!^"
Schema Errors
ci.transparency.cwe.types.cwe.schema.errors
CWE schema error types using enhanced base classes.
Domain-specific error hierarchy for CWE schema operations. Each error inherits from exactly one enhanced base error class and leverages the flexible context system for schema-specific information.
Design principles
- Single inheritance: each error extends exactly one base error class
- Context-rich: uses the flexible context system for schema details
- Consistent: maintains uniform error formatting across all errors
- Minimal: leverages base class functionality rather than duplicating code
Usage patterns
- File operations → FileError, LoadingError, ParsingError
- Validation operations → ValidationError
- General schema operations → BaseTransparencyError
Typical usage
from ci.transparency.cwe.types.cwe.schema import CweSchemaValidationError
raise CweSchemaValidationError( "Schema validation failed", schema_name="cwe-v2.0", field_path="relationships[0].id", file_path="cwe-79.yaml" )
Output: "Schema validation failed | Schema: cwe-v2.0 | Field: relationships[0].id | File: cwe-79.yaml"
__all__ = ['CweSchemaCircularReferenceError', 'CweSchemaConstraintError', 'CweSchemaDataValidationError', 'CweSchemaError', 'CweSchemaFieldValidationError', 'CweSchemaFormatError', 'CweSchemaLoadingError', 'CweSchemaNotFoundError', 'CweSchemaParsingError', 'CweSchemaReferenceError', 'CweSchemaValidationError', 'CweSchemaVersionError']
module-attribute
BaseTransparencyError
Bases: Exception
Enhanced base exception for all transparency operations.
Provides flexible context tracking for common error patterns without requiring all errors to specify every possible context field.
get_context_parts()
Get contextual information parts for error formatting.
Returns context in order of importance: 1. Operation identification (phase, operation, stage) 2. Progress information (processed/total counts) 3. Resource information (timeouts, limits) 4. File/item context 5. Validation context 6. Error flow context (abort reason, error code)
Returns:
| Type | Description |
|---|---|
list[str]
|
List of context strings (e.g., ["Phase: validation", "Progress: 150/500"]) |
CweSchemaCircularReferenceError
CweSchemaConstraintError
CweSchemaDataValidationError
CweSchemaError
Bases: BaseTransparencyError
General CWE schema error for operations that don't fit specific categories.
CweSchemaFieldValidationError
CweSchemaFormatError
CweSchemaLoadingError
CweSchemaNotFoundError
CweSchemaParsingError
CweSchemaReferenceError
CweSchemaValidationError
CweSchemaVersionError
FileError
Bases: BaseTransparencyError
Base exception for file-based operations.
Convenient base for file loading, parsing, and other file-related errors.
LoadingError
ParsingError
ValidationError
Bases: BaseTransparencyError
Base exception for validation operations.
Convenient base for schema validation, rule checking, and other validation-related errors.
options: showsource: false show_signature: true group_by_category: true filters: - "!^"