Object Specifications
Relevant source files
The following files were used as context for generating this wiki page:
Object Specifications define the structural and behavioral requirements for infrastructure data within the Infrahub Python SDK. These specifications ensure that developers interact with infrastructure data as native Python objects while maintaining strict type safety and backward compatibility.
The specification system governs how objects are queried, created, modified, and deleted via the SDK and the infrahubctl CLI. It relies on a layered architecture where API interaction and domain rules reside in the SDK, while the CLI serves as a presentation layer.
Sources: dev/constitution.md:12-16, dev/constitution.md:58-63
Architecture and Core Principles
The Object Specification system adheres to non-negotiable architectural principles to maintain stability for downstream consumers like Ansible collections and external applications.
Dual API Parity
Every public feature must exist in both InfrahubClient (async) and InfrahubClientSync (sync). Both clients must share matching method names, signatures, and behaviors.
Sources: dev/constitution.md:21-25, tasks.py:34-40
Type Safety and Models
The SDK uses Pydantic v2 models to define data boundaries. All function signatures require type hints, and errors must utilize a specific typed exception hierarchy rooted at infrahub_sdk.exceptions.Error.
Sources: dev/constitution.md:72-76, dev/constitution.md:78-82
The diagram shows the relationship between the SDK clients, the data models, and the error handling structure.
Sources: dev/constitution.md:58-65, dev/constitution.md:78-83
Data Operations (CRUD)
Object specifications define the functional requirements for interacting with infrastructure nodes. These operations are categorized by their priority and impact on the system.
Sources: dev/specs/001-end-user-cli/spec.md:12-15
Query and Discovery
Users retrieve data using the get command. The system supports list views for object kinds and detail views for specific identifiers.
- Filtering: Supports attribute-based filtering (e.g.,
name__value="spine01"). - Formating: Outputs data in Table, JSON, CSV, or Infrahub Object YAML formats.
- Discovery: The
schema listandschema showcommands allow users to inspect available kinds, attributes, and constraints.
Sources: dev/specs/001-end-user-cli/spec.md:20-30, dev/specs/001-end-user-cli/spec.md:94-105
Creation and Modification
Object specifications allow for both inline attribute setting and file-based batch operations.
- Attribute Setting: Uses the
--setflag for both attributes and relationships. - Relationship Handling: Relationships accept Human-Friendly IDs (HFIDs) or UUIDs. Multi-component HFIDs are supported via JSON array syntax.
- Validation: The system validates inputs against the schema and rejects invalid fields with clear error messages.
Sources: dev/specs/001-end-user-cli/spec.md:46-55, dev/specs/001-end-user-cli/spec.md:123-128
Key Entities and Definitions
The specification system identifies four primary entities that form the basis of the data model.
| Entity | Description |
|---|---|
| Kind | A type definition in the schema (e.g., InfraDevice) containing namespace, name, and attributes. |
| Node | An instance of a Kind stored in Infrahub, possessing an ID and specific values. |
| Attribute | A named property on a Kind with a specific type and optional constraints. |
| Relationship | A typed connection between two Nodes defined by cardinality and direction. |
| Sources: dev/specs/001-end-user-cli/spec.md:155-163 |
Request Prioritization
The SDK supports request prioritization via an X-Priority header. This allows the server to distinguish between interactive and background worker tasks.
- Priority Levels: Defined by a
Priorityenum (e.g., high, normal, low). - Inheritance: Batch mode and raw blob transfers inherit the client's default priority.
- Overrides: Pagination loops forward the specified priority to every individual page request.
Sources: specs/ihs-259-sdk-x-priority-header/alignment-check.md:23-28, specs/ihs-259-sdk-x-priority-header/alignment-check.md:31-35
This diagram illustrates the flow of a prioritized request from an application through the SDK to the API.
Sources: specs/ihs-259-sdk-x-priority-header/alignment-check.md:23-26
Template and Artifact Composition
Object specifications extend to template rendering through Jinja2 filters. These filters allow for dynamic composition of infrastructure artifacts.
Filter Contexts
To ensure security, filters are restricted by ExecutionContext.
- CORE: High-security context; blocks sub-artifact content filters.
- WORKER: Allows artifact content inlining for rendering tasks.
- LOCAL: General execution context.
Sources: dev/specs/infp-504-artifact-composition/tasks.md:24-30
Specialized Filters
artifact_content: Inlines rendered sub-artifact content via storage ID.file_object_content: Inlines text-based file objects while rejecting binary data.from_json/from_yaml: Chained filters that parse string content into structured data.
Sources: dev/specs/infp-504-artifact-composition/tasks.md:38-48, dev/specs/infp-504-artifact-composition/tasks.md:65-75
Conclusion
Object Specifications serve as the contract ensuring infrastructure data remains consistent across the Infrahub ecosystem. By enforcing dual API parity, strict type safety, and context-aware rendering, the SDK provides a stable foundation for automated network infrastructure management.
Sources: dev/constitution.md:10-16, dev/constitution.md:104-108