Schema Evolution
Types and operations for domain-neutral schema-to-schema evolution checks, including freeze rule enforcement and backward-compatibility analysis. Provides result types for diff summaries and error types for violations and breaking changes.
Schema Evolution Results
ci.transparency.cwe.types.schema_evolution.results
Schema evolution result types and composable operations.
This mirrors the Standards/CWE pattern: immutable dataclasses that compose base building blocks (ValidationCounts, MessageCollection) and helper functions that return new instances via dataclasses.replace.
__all__ = ['SchemaDiff', 'SchemaEvolutionResult', 'set_versions', 'set_diff', 'record_violation', 'record_breaking_change', 'record_compat_issue', 'mark_check_passed', 'get_schema_evolution_summary']
module-attribute
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.
SchemaDiff
dataclass
Structural diff between two schema versions.
added_count
property
Return the number of items added in the schema diff.
changed_count
property
Return the number of items changed in the schema diff.
removed_count
property
Return the number of items removed in the schema diff.
total_changes
property
Return the total number of changes (added, removed, changed) in the schema diff.
SchemaEvolutionResult
dataclass
Aggregate result of a schema evolution (freeze/compatibility) check.
breaking_change_count
property
Return the number of breaking changes recorded in the schema evolution result.
compatibility_issue_count
property
Return the number of compatibility issues recorded in the schema evolution result.
has_breaking_changes
property
Return True if there are any breaking changes recorded.
has_compat_issues
property
Return True if there are any compatibility issues recorded.
is_successful
property
True if no validation failures and no error messages.
violation_count
property
Return the number of violations recorded in the schema evolution result.
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).
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_message(messages, level, text)
_inc_validation(counts, *, passed=0, failed=0)
get_schema_evolution_summary(result)
Generate a summary dictionary of the schema evolution result.
Parameters
result : SchemaEvolutionResult The schema evolution result to summarize.
Returns
dict[str, object] A dictionary containing summary statistics and details about the schema evolution.
mark_check_passed(result, message=None)
Increment 'passed' when a check succeeds.
record_breaking_change(result, message)
Record a breaking change; also a validation failure.
record_compat_issue(result, message, *, treat_as_failure=False)
Record a compatibility issue. By default it's a warning; can be hardened.
record_violation(result, message)
Record a freeze-rule violation (may or may not be breaking).
set_diff(result, diff)
Set the schema diff in a SchemaEvolutionResult and add an info message summarizing the diff counts.
Parameters
result : SchemaEvolutionResult The schema evolution result to update. diff : SchemaDiff The schema diff to set.
Returns
SchemaEvolutionResult A new SchemaEvolutionResult instance with the updated diff and info message.
set_versions(result, *, old_version, new_version)
Set the old and new version identifiers in a SchemaEvolutionResult.
Parameters
result : SchemaEvolutionResult The schema evolution result to update. old_version : str | None The old version identifier. new_version : str | None The new version identifier.
Returns
SchemaEvolutionResult A new SchemaEvolutionResult instance with updated version fields.
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 Evolution Errors
ci.transparency.cwe.types.schema_evolution.errors
Schema evolution (freeze/compatibility) error types using enhanced base classes.
These mirror our domain patterns (like CWE/Standards) and use the flatter base errors. We compose all evolution-specific details into the base fields (validation_rule, field_path, file_path) and a single validation_context string, so formatting stays consistent and stable across domains.
__all__ = ['SchemaBreakingChangeError', 'SchemaCompatibilityError', 'SchemaFreezeError', 'SchemaFreezeViolationError']
module-attribute
SchemaBreakingChangeError
SchemaCompatibilityError
SchemaFreezeError
SchemaFreezeViolationError
ValidationError
Bases: BaseTransparencyError
Base exception for validation operations.
Convenient base for schema validation, rule checking, and other validation-related errors.
options: show_source: false show_signature: true group_by_category: true filters: - "!^*"