Schema Management
Relevant source files
The following files were used as context for generating this wiki page:
Schema Management provides the mechanisms to define, discover, load, and validate the data models within Infrahub. It ensures that infrastructure data adheres to specific types, attributes, and relationships defined by the user. The system supports local validation of schema files and remote synchronization with an Infrahub instance.
Sources: dev/specs/001-end-user-cli/spec.md:204-207, infrahub_sdk/ctl/schema.py:33-40
Architecture and Data Flow
Schema management operates as a tiered architecture where local schema definitions (YAML) are validated and then loaded into the Infrahub server. The infrahubctl CLI acts as the primary interface for users to interact with these schemas.
The flow shows how a user interacts with the CLI to parse, validate, and synchronize schemas with the remote server.
Sources: infrahub_sdk/ctl/schema.py:168-185, dev/specs/001-end-user-cli/research.md:46-51
Schema Components
The schema is composed of several key entities that define the structure of infrastructure data:
- Kind: A type definition (e.g.,
InfraDevice,IpamIPAddress) containing a namespace, name, and description. - Attribute: A named property on a Kind with a specific type and optional constraints.
- Relationship: A connection between two Nodes, defined by cardinality and direction.
- Generic: A generic type definition that can be implemented by concrete node kinds.
Sources: dev/specs/001-end-user-cli/spec.md:209-215, infrahub_sdk/ctl/schema.py:465-475
Schema Metadata Table
| Component | Field | Description |
|---|---|---|
| NodeSchema | kind | The unique identifier for the object type. |
| NodeSchema | namespace | The grouping for the schema definition. |
| Attribute | kind | The data type of the attribute. |
| Attribute | optional | Boolean indicating if the field is mandatory. |
| Relationship | peer | The target Kind of the connection. |
| Relationship | cardinality | Defines if the relationship is one-to-one or one-to-many. |
Sources: infrahub_sdk/ctl/schema.py:448-478
Core Operations
Validation and Loading
The load command processes YAML schema files and synchronizes them with the server. Before sending data, the SDK performs local validation to identify syntax or contract violations.
- Parsing: Loads YAML files from disk into
SchemaFileobjects. - Validation: Executes
validate_schemato check for local errors. - Transmission: Sends the payload to
client.schema.load. - Convergence: Optionally waits for the schema to sync across all workers using
SCHEMA_HASH_SYNC_STATUS.
Sources: infrahub_sdk/ctl/schema.py:168-208, infrahub_sdk/ctl/schema.py:53-65
This diagram illustrates the sequence from local file parsing to the server-side load response.
Sources: infrahub_sdk/ctl/schema.py:177-195
Schema Discovery
Users can explore available schemas using discovery commands. This allows for self-service exploration of the data model without external documentation.
- List: Use
infrahubctl schema listto view all available kinds, filtered by namespace or name. - Show: Use
infrahubctl schema show <kind>to inspect detailed attributes and relationships for a specific type.
Sources: dev/specs/001-end-user-cli/spec.md:120-134, infrahub_sdk/ctl/schema.py:406-440
Formatting and Canonicalization
The format command ensures schema files follow a consistent, opinionated key ordering. This minimizes diff noise in version control systems.
- Reordering: Keys within nodes, attributes, and relationships are reordered to a canonical sequence.
- Cleaning: Optional
--strip-defaultsremoves redundant keys that match schema default values. - Sorting: Optional
--sort-by-order-weightreorders attributes based on their defined weight.
Sources: infrahub_sdk/ctl/schema.py:535-560, infrahub_sdk/ctl/schema.py:603-610
Drift Detection
The system monitors drift between the live Infrahub JSON schema and a committed baseline. The schema-drift-check task identifies added or removed properties, allowing maintainers to update canonical key ordering in schema_format.py.
Sources: tasks.py:346-368
Summary
Schema Management provides the foundation for data integrity within the SDK. By combining local validation, canonical formatting, and robust discovery tools, it enables developers to maintain a consistent and well-documented infrastructure data model. The integration with infrahubctl makes these tools accessible for both interactive exploration and automated CI/CD pipelines.