Skip to main content

Data Contracts Technical Reference

Architecture Overview​

Data Contracts in the Qarion platform are formal, versioned declarations of data interfaces. They enforce stability between Producers and Consumers by defining schemas and Service Level Agreements (SLAs).

The architecture treats contracts as First-Class Citizens in the governance graph, sitting between a DataProduct and its consumers.

Key Principles​

The architecture is built on two key principles. First, Schema-as-Code means schemas are stored as JSON structures (compatible with Avro and JsonSchema) to facilitate automated validation. Second, SLA Enforcement ensures that SLAs are treated as numeric thresholds monitored by the Quality Engine, rather than just text-based descriptions.

Data Model​

Entity Relationship Diagram (ERD)​

Core Entities​

DataContract (Table: data_contracts)​

From app/models/contract.py.

The DataContract entity is defined by a unique id (UUID) and several foreign keys and descriptors. product_id links to the governed data product, while producer_id and consumer_id identify the owning and consuming teams respectively. The schema_definition field stores the agreed-upon structure as nullable JSON. SLA parameters include sla_value (integer threshold) and sla_unit (defaulting to 'minutes'). Additionally, quality_threshold sets the minimum passing percentage for quality checks (default 100), and status tracks the lifecycle state (draft, active, deprecated).

Service Layer​

ContractService​

The service orchestrating contract lifecycle.

API Methods​

create_contract(product_id: UUID, schema: Dict, sla: SlaDTO) -> DataContract

This method handles the creation of a new contract. It performs Schema Validation by parsing the provided schema JSON, raising a SchemaValidationError if the format is invalid. The contract serves with a default Status of draft.

activate_contract(contract_id: UUID)

Activation transitions the contract's state to active. Planned functionality includes Snapshotting, which will create a snapshot of the current product schema to serve as a baseline version.

check_sla_compliance(contract_id: UUID)

This method evaluates SLA compliance through a multi-step logic. First, it fetches the latest QualityCheck results for the linked DataProduct. It then calculates current "Freshness" by comparing the current time against the Last_Load_Time. Finally, it compares this value against the sla_value and sla_unit to return a ComplianceStatus (PASS or FAIL).

Quality Engine Integration​

Data Contracts drive the Quality Engine in three ways. First, the quality_threshold field acts as a gate for compliance. Second, the system triggers specialized Contract Breach Alerts if the Quality Engine detects a drop below this threshold. Finally, Routing logic ensures these alerts are directed specifically to the producer_id team for resolution.