Managing Schemas Skill
Relevant source files
The following files were used as context for generating this wiki page:
The Managing Schemas Skill provides expert guidance for designing, building, and modifying Infrahub data models. It enables AI assistants to create and validate YAML schema definitions comprising nodes, generics, attributes, relationships, and extensions. The skill prioritizes branch-first changes to ensure that migrations against loaded data remain isolated and reviewable before merging into the default branch.
Sources: skills/infrahub-managing-schemas/SKILL.md:1-26, dev/knowledges/architecture.md:37-51
This skill acts as a navigator for developers, directing them to modular rules and production patterns. It emphasizes reusing existing marketplace schemas to avoid reinventing established domains and provides a strict workflow for applying changes to a live Infrahub instance.
Sources: skills/infrahub-managing-schemas/SKILL.md:124-171, dev/knowledges/infrahub-concepts.md:9-13
Schema Components and Structure
Infrahub schemas define the structure of infrastructure data through three primary components: generics, nodes, and extensions. Every schema file must include the $schema comment for IDE validation and specify the version.
Sources: skills/infrahub-managing-schemas/SKILL.md:46-59
Data Model Entities
| Component | Description |
|---|---|
| Generics | Abstract base definitions providing shared attributes and relationships for other nodes to inherit. |
| Nodes | Concrete object types (e.g., Device, VLAN) that represent infrastructure data. |
| Extensions | Blocks that add attributes or relationships to existing nodes defined in other schema files. |
| Attributes | Data fields on a node (e.g., Text, Number, Dropdown, Boolean). |
| Relationships | Bidirectional links between nodes, categorized as Attribute, Component, Parent, or Generic. |
| Sources: skills/infrahub-managing-schemas/SKILL.md:46-59, dev/knowledges/infrahub-concepts.md:9-38 |
The following diagram illustrates the relationship hierarchy and inheritance model within an Infrahub schema.
Workflow for Schema Management
The skill enforces a specific multi-step workflow to ensure data integrity and proper synchronization with the Infrahub server.
Sources: skills/infrahub-managing-schemas/SKILL.md:173-228
Step-by-Step Execution
- Requirements Gathering: Identify node types, attributes, and relationships.
- Marketplace Search: Check the Infrahub Marketplace using
infrahubctl marketplace get <ns>/<name>before modeling from scratch. - Rule Application: Apply naming conventions, attribute defaults, and bidirectional relationship identifiers.
- YAML Construction: Build the schema starting with
$schemaandversion: "1.0". - Downstream Audit: Verify if nodes need
CoreArtifactTargetinheritance orgenerate_templateflags for other project features. - Formatting: Run
infrahubctl schema formatto maintain canonical key order. - Validation and Branch Rollout: Use
infrahubctl schema check --branch <name>andinfrahubctl schema load --branch <name>.
Sources: skills/infrahub-managing-schemas/SKILL.md:173-228, skills/infrahub-common/rules/_sections.md:1-12
The sequence diagram below represents the interaction between the developer, the CLI, and the Infrahub server during a schema update.
Rule Categories and Constraints
Rules are modular best practices organized by priority and prefix. They prevent common mistakes such as mismatched identifiers or deprecated attribute types.
Sources: skills/infrahub-managing-schemas/SKILL.md:31-44, skills/infrahub-managing-schemas/rules/_sections.md:1-68
Critical and High Priority Rules
| Category | Prefix | Constraint / Requirement |
|---|---|---|
| Branch-First | workflow- | Changes must occur on a branch to prevent global data migrations without review. |
| Naming | naming- | Namespaces must be ^[A-Z][a-z0-9]+$; attributes must be ^[a-z0-9_]+$. |
| Relationships | relationship- | Both sides of a relationship must share the exact same identifier. |
| Attributes | attribute- | Use Text instead of the deprecated String. Dropdown choices must be objects. |
| Uniqueness | uniqueness- | Attribute fields in constraints must use the __value suffix. |
| Display | display- | Nodes must define human_friendly_id and display_label for UI identification. |
| Sources: skills/infrahub-managing-schemas/SKILL.md:31-44, skills/infrahub-managing-schemas/rules/_sections.md:1-68, dev/knowledges/infrahub-concepts.md:46-55 |
Designing for Downstream Consumers
A valid schema must account for how other Infrahub features utilize the defined nodes. Adding inheritance or flags early avoids expensive migrations after data is loaded.
Sources: skills/infrahub-managing-schemas/SKILL.md:61-94
| Feature Requirement | Schema Implementation |
|---|---|
| Artifact/Generator Target | inherit_from: [..., CoreArtifactTarget] |
| File Storage (PDF/Images) | inherit_from: [..., CoreFileObject] |
| Cloneable Templates | generate_template: true |
| Shared Default Values | generate_profile: true |
| Custom Sidebar Menu | include_in_menu: false (avoids duplication) |
| Sources: skills/infrahub-managing-schemas/SKILL.md:73-89 |
Conclusion
The Managing Schemas Skill ensures that data models are scalable, valid, and compatible with the broader Infrahub ecosystem. By following the branch-first workflow and adhering to strict naming and relationship rules, developers avoid silent data model bugs and ensure seamless integration with downstream artifacts and the UI.
Sources: skills/infrahub-managing-schemas/SKILL.md:91-94, skills/infrahub-managing-schemas/rules/_sections.md:1-12