Schema Drift and Validation

Schema Drift and Validation ensures that infrastructure data models in Infrahub remain consistent with committed baselines and compliant with defined rules. The system provides tools to detect changes in the live Infrahub JSON schema compared to a local reference and validates infrastructure objects against these schema definitions.

This module acts as a quality gate within the development workflow, preventing undocumented schema changes from affecting downstream automation. It integrates with the infrahubctl CLI to provide end-users with interactive validation and drift detection capabilities.

Schema Drift Detection

Schema drift detection identifies discrepancies between the properties of a live Infrahub instance and a committed baseline file. This process monitors added or removed schema properties, allowing developers to update canonical key orderings or configurations when the server-side schema evolves.

Drift Check Workflow

The drift check process fetches live properties from the Infrahub API and compares them against a local baseline stored in infrahub_sdk/ctl/schema_properties.json.

The diagram shows the logic flow for identifying discrepancies between live and baseline schema properties.
Sources: tasks.py:339-361, infrahub_sdk/ctl/schema_drift.py:27-58

Key Drift Management Tasks

Schema Validation Architecture

Validation ensures that infrastructure objects—defined in YAML or JSON files—conform to the Infrahub data model. The SDK implements validation at two levels: local input validation within the CLI and server-side validation during object creation or updates.

Validation Components

The validation logic utilizes Pydantic models and specialized processors to handle infrastructure data.

The class relationship shows how object files are processed and validated against the schema.
Sources: dev/specs/001-end-user-cli/research.md:R4, infrahub_sdk/schema/validate.py

Validation Procedures

1. Load Object File: The system reads files from disk using ObjectFile.load_from_disk().
2. Process Data: The InfrahubObjectFileData model parses the apiVersion, kind, and data array.
3. Local Validation: The CLI validates that attribute and relationship names exist in the schema.
4. Relationship Resolution: Validation checks if relationship values (UUIDs or HFIDs) are correctly formatted.

Sources: dev/specs/001-end-user-cli/research.md:R4, dev/specs/001-end-user-cli/tasks.md:T028

CLI Integration

The infrahubctl command provides the user interface for validation operations. It handles error reporting by mapping validation failures to actionable exit codes and descriptive messages.

CLI Validation Principles

• Don't Pre-validate Server Logic: The CLI limits local validation to input structure and basic field existence, deferring complex domain rules to the server.
• Actionable Errors: Validation errors suggest similar valid attribute or relationship names if a user provides an incorrect field.
• Exit Codes: Destructive validation failures or invalid inputs trigger specific exit codes (e.g., exit code 1 for input errors).

Sources: dev/constitution.md:III, dev/specs/001-end-user-cli/tasks.md:T023, T028, dev/specs/001-marketplace-api-update/tasks.md:T004

Validation Command Examples

# Validation logic derived from the ctl/validate.py module
async def validate_schema_file(client, file_path: Path):
    # Load and validate the content of an object file
    obj_file = ObjectFile(file_path)
    content = obj_file.validate_content()
    
    # Process the validated content
    await obj_file.process(client)

Sources: infrahub_sdk/ctl/validate.py, dev/specs/001-end-user-cli/research.md:R4

Summary

Schema Drift and Validation provides a critical safety mechanism for the Infrahub Python SDK. By detecting schema drift through the schema-drift-check task and enforcing data integrity via the ObjectFile processing pipeline, the system ensures that infrastructure code remains compatible with the server-side data model. This layered approach—combining baseline monitoring with robust input validation—minimizes integration errors and maintains automation stability.