Schema
Types and operations for domain-neutral JSON schema management, validation, and version control. Handles schema loading, constraint validation, and reference analysis.
Schema Results
ci.transparency.cwe.types.schema.results
Domain-neutral schema result types and operations using composition.
Immutable dataclasses for tracking schema loading and validation. Mirrors the CWE/Standards shape (LoadingCounts, ValidationCounts, MessageCollection, FileCollection, DuplicateCollection), so higher-level workflows can consume a consistent interface.
__all__ = ['SchemaLoadingResult', 'SchemaValidationResult', 'SchemaDocumentDict', 'SchemasDict', 'ValidationResultsDict', 'ValidationDetailsDict', 'SeverityCountsDict', 'LoadingSummaryDict', 'ValidationSummaryDict', 'add_schema', 'track_invalid_schema_file', 'track_skipped_schema_file', 'validate_schema_document', 'record_schema_validation', 'get_schema_loading_summary', 'get_schema_validation_summary', 'add_message', 'increment_loading', 'increment_validation', 'add_processed_file', 'add_failed_file', 'add_skipped_file', 'add_duplicate']
module-attribute
LoadingSummaryDict = dict[str, Any]
SchemasDict = dict[str, SchemaDocumentDict]
SeverityCountsDict = dict[str, int]
ValidationDetailsDict = dict[str, list[str]]
ValidationResultsDict = dict[str, bool]
ValidationSummaryDict = dict[str, Any]
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.
SchemaDocumentDict
Bases: TypedDict
Minimal shape of a single schema document.
SchemaLoadingResult
dataclass
Result of loading/parsing schema documents (batch-friendly).
is_successful
property
Return True if loading was successful and there are no error messages.
Returns
bool True if loading was successful and there are no error messages, False otherwise.
loaded_schema_ids
property
Return a sorted list of loaded schema IDs.
schema_count
property
Return the number of loaded schemas.
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)
Return the schema document for the given schema_id, or None if not found.
Parameters
schema_id : str The identifier of the schema to retrieve.
Returns
SchemaDocumentDict or None The schema document if found, otherwise None.
has_schema(schema_id)
Check if a schema with the given ID exists in the loaded schemas.
Parameters
schema_id : str The identifier of the schema to check.
Returns
bool True if the schema exists, False otherwise.
SchemaValidationResult
dataclass
Result of validating instances/documents against schemas.
is_successful
property
Return True if validation was successful and there are no error messages.
Returns
bool True if validation was successful and there are no error messages, False otherwise.
validated_count
property
Return the number of validated schemas.
validation_rate
property
Return the rate of successful validations as a float between 0 and 1.
Returns
float The fraction of schemas that passed validation.
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_failed()
Return a list of schema IDs that failed validation.
Returns
list[str] List of schema IDs where validation did not pass.
get_passed()
Return a list of schema IDs that passed validation.
Returns
list[str] List of schema IDs where validation passed.
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 item to the DuplicateCollection in an immutable fashion.
Parameters
duplicates : DuplicateCollection The current collection of duplicates. item_id : str The identifier of the duplicate item. file_path : Path The path of the file where the duplicate was found.
Returns
DuplicateCollection A new DuplicateCollection with the duplicate item added.
add_failed_file(files, file_path)
Add a failed file to the FileCollection in an immutable fashion.
Parameters
files : FileCollection The current collection of files. file_path : Path The path of the file to add as failed.
Returns
FileCollection A new FileCollection with the failed file added.
add_message(messages, level, message)
Immutable message append.
add_processed_file(files, file_path)
Add a processed file to the FileCollection in an immutable fashion.
Parameters
files : FileCollection The current collection of files. file_path : Path The path of the file to add as processed.
Returns
FileCollection A new FileCollection with the processed file added.
add_schema(result, schema_id, schema_doc, *, file_path=None)
Add a loaded schema (dedup, files, messages, counts).
add_skipped_file(files, file_path)
Add a skipped file to the FileCollection in an immutable fashion.
Parameters
files : FileCollection The current collection of files. file_path : Path The path of the file to add as skipped.
Returns
FileCollection A new FileCollection with the skipped file added.
get_schema_loading_summary(result)
Generate a summary dictionary of schema loading results.
Parameters
result : SchemaLoadingResult The result object containing schema loading details.
Returns
LoadingSummaryDict A dictionary summarizing loading statistics and outcomes.
get_schema_validation_summary(result)
Generate a summary dictionary of schema validation results.
Parameters
result : SchemaValidationResult The result object containing validation details.
Returns
ValidationSummaryDict A dictionary summarizing validation statistics and outcomes.
increment_loading(counts, *, ok=0, failed=0)
Increment the loading counts immutably by the specified ok and failed values.
Parameters
counts : LoadingCounts The current loading counts. ok : int, optional Number of successful loads to add (default is 0). failed : int, optional Number of failed loads to add (default is 0).
Returns
LoadingCounts A new LoadingCounts instance with updated counts.
increment_validation(counts, *, passed=0, failed=0)
Increment the validation counts immutably by the specified passed and failed values.
Parameters
counts : ValidationCounts The current validation counts. passed : int, optional Number of successful validations to add (default is 0). failed : int, optional Number of failed validations to add (default is 0).
Returns
ValidationCounts A new ValidationCounts instance with updated counts.
record_schema_validation(result, schema_id, *, ok, errors=None, warnings=None, infos=None)
Adapt external validator messages and push them in here without re-validating content.
If an external validator already produced messages, push them in here without re-validating content.
track_invalid_schema_file(result, file_path, reason)
Record a file that failed to load as a schema.
track_skipped_schema_file(result, file_path, reason)
Record a file that was skipped during schema loading.
validate_schema_document(result, schema_id, schema_doc)
Minimal structural checks (domain-neutral).
Designed so engines that call jsonschema, fastjsonschema, etc. can still pipe their messages into the same result container.
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: show_source: false show_signature: true group_by_category: true filters: - "!^*"
Schema Errors
ci.transparency.cwe.types.schema.errors
Domain-neutral schema error types.
Lightweight hierarchy that adds schema context (name/version/path) on top of base loading/validation errors. Keeps slots for low overhead and reuses your BaseLoadingError formatting contract.
__all__ = ['SchemaCircularReferenceError', 'SchemaConstraintError', 'SchemaDataValidationError', 'SchemaError', 'SchemaFieldValidationError', 'SchemaFormatError', 'SchemaLoadingError', 'SchemaNotFoundError', 'SchemaParsingError', 'SchemaReferenceError', 'SchemaValidationError', 'SchemaVersionError']
module-attribute
LoadingError
ParsingError
SchemaCircularReferenceError
Bases: SchemaValidationError
Schema contains circular references.
get_context_parts()
Return a list of context parts describing the circular reference error.
Includes the reference chain if available.
SchemaConstraintError
Bases: SchemaValidationError
Schema constraint validation failed.
get_context_parts()
Return a list of context parts describing the constraint error.
Includes constraint name, expected value, and violated rule if available.
SchemaDataValidationError
Bases: SchemaValidationError
Instance data validation against schema failed.
get_context_parts()
Return a list of context parts describing the data validation error.
Returns
list[str] List of context strings including validation path, expected type, and actual value if available.
SchemaError
Bases: LoadingError
Base exception for schema operations with schema context.
get_context_parts()
Return a list of context parts describing the schema error.
Includes schema name and version if available.
SchemaFieldValidationError
Bases: SchemaValidationError
Field-level validation against schema failed.
get_context_parts()
Return a list of context parts describing the field validation error.
Includes field path, field name, and constraint type if available.
SchemaFormatError
Bases: SchemaLoadingError
Schema format is invalid or malformed.
get_context_parts()
Return a list of context parts describing the schema format error.
Includes format issue details if available.
SchemaLoadingError
SchemaNotFoundError
SchemaParsingError
SchemaReferenceError
Bases: SchemaValidationError
Schema $ref could not be resolved.
get_context_parts()
Return a list of context parts describing the reference error.
Includes reference path and target if available.
SchemaValidationError
SchemaVersionError
Bases: SchemaLoadingError
Schema version is not supported or invalid.
get_context_parts()
Return a list of context parts describing the schema version error.
Includes supported versions if available.
options: show_source: false show_signature: true group_by_category: true filters: - "!^*"