Infrahub Managing Schemas

Infrahub Schema Creator

Overview

Expert guidance for designing and building Infrahub schemas. Schemas are YAML files defining nodes (concrete types), generics (abstract base types), attributes, relationships, and extensions.

Project Context

Existing schemas in this project: !find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -20

Infrahub config (if present): !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

If invoked with arguments (e.g., /infrahub:managing-schemas Ipam Vlan VlanGroup), use the first argument as the namespace and remaining arguments as node names.

When to Use

• Designing new data models or schema nodes
• Adding attributes or relationships to existing schemas
• Setting up hierarchical location trees or component/parent patterns
• Configuring display properties (human_friendly_id, display_label)
• Migrating or refactoring existing schemas
• Debugging schema validation errors

Rule Categories

Schema File Basics

---
# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/schema/latest.json
version: "1.0"

generics:      # Abstract base definitions (shared attributes/relationships)
  - ...
nodes:         # Concrete object types
  - ...
extensions:    # Add attributes/relationships to existing nodes from other files
  nodes:
    - ...

Always include the $schema comment for IDE validation. Only version is required at the top level.

Designing for Downstream Consumers

A schema node rarely lives alone. Before finalizing it, walk through how it will be used by other parts of the project and add the inheritance / configuration that those features require:

This audit is the difference between a schema that "validates" and one that "actually works in the broader project." Skipping it forces a schema migration once the downstream feature is wired up — at which point the data is already loaded.

When the task spans multiple skills (schemas + transforms, schemas + menus, etc.), load both skills' rules together rather than treating the boundaries as exclusive.

Design for the cheaper layer

A schema choice can remove the need for Python or denormalized data downstream. The schema is the cheapest place to get this right — fixing it later means a migration on already-loaded data. Before adding a field or node, check whether a built-in or structural feature already covers it:

These are the schema-side counterparts to the "Before writing Python" guidance in the checks, transforms, and generators skills. The repo auditor flags them as advisory cost-to-fix findings; catching them at design time avoids both the finding and the later migration.

Workflow

Follow these steps when creating or modifying a schema:

1. Gather requirements — Identify the node types, their attributes, and how they relate to each other. Ask about hierarchies, dropdowns, and display needs.
2. Check the marketplace first — Before modelling any domain from scratch, search the whole Infrahub Marketplace and reuse a published schema when one covers it: infrahubctl marketplace get <namespace>/<name>, then inherit_from the pulled generics and add only site-specific attributes. Discovery, collections (-c), the airgap fallback, and the required SDK version live in ../infrahub-common/marketplace-reference.md.
3. Read relevant rules — Read rules/naming-conventions.md for naming constraints, rules/attribute-defaults-and-types.md for attribute kinds and defaults, and rules/relationship-identifiers.md for bidirectional relationship setup.
4. Build the schema YAML — Start with the $schema comment and version: "1.0". Define generics first (if any), then nodes. Apply naming, display, and relationship rules from step 3.
5. Audit downstream consumers — Walk the table in "Designing for Downstream Consumers" above. If any node will become an artifact or generator target, add CoreArtifactTarget to its inherit_from now, per rules/extension-artifact-target.md. Adding it later forces a schema migration on loaded data.
6. Configure display properties — Set human_friendly_id, display_label, and order_weight per rules/display-human-friendly-id.md and rules/display-order-weight.md.
7. Format the file — Put the keys in the canonical order before committing so diffs stay small. Run infrahubctl schema format when your infrahubctl provides it (offline, no server); otherwise author the order by hand. See rules/format-schema-files.md.
8. Validate and roll out on a branch — Run infrahubctl schema check to fix errors per validation.md and rules/validation-common-errors.md. Then apply the change on a dedicated branch, not the default branch (main by convention, but it can be renamed): infrahubctl branch create <name> → schema check --branch <name> → schema load --branch <name>, and merge via a proposed change once it looks right. A schema load runs migrations against loaded data immediately, so on a shared server the default branch gives no preview and no per-step undo — the branch does. See rules/workflow-branch-first.md. The default branch is only reasonable on a local throwaway instance.

Production Patterns Worth Knowing

Seven recurring patterns — computed Jinja2 attributes, cascade-vs-no-action deletes, menu visibility, branch-agnostic identity, artifact targets, object templates, and file objects — are documented at the top of examples.md. Read those before finalizing a schema; each pattern is easy to miss when building from scratch and expensive to retrofit after data is loaded.

Supporting References

• reference.md -- Complete property tables for nodes, generics, attributes, relationships
• examples.md -- Full schema patterns from production repos
• validation.md -- infrahubctl commands, migration strategies, pre-validation checklist
• ../infrahub-common/infrahub-yml-reference.md -- .infrahub.yml project configuration
• ../infrahub-common/marketplace-reference.md -- reusing published marketplace schemas and collections (infrahubctl marketplace get / list / search / show, airgap)
• ../infrahub-common/rules/ -- Shared rules (git integration, caching) across all skills
• ../infrahub-common/rules/workflow-information-priority.md -- Skill content first; how to consult docs.infrahub.app on a genuine gap (e.g. deleting nodes)
• rules/ -- Individual rules by category prefix