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
| Priority |
Category |
Prefix |
Description |
| CRITICAL |
Branch-First Changes |
workflow- |
Load schema onto a branch, not the default branch |
| CRITICAL |
Naming |
naming- |
Namespace, node, attribute naming |
| CRITICAL |
Relationships |
relationship- |
IDs, peers, component/parent, on_delete |
| HIGH |
Attributes |
attribute- |
Defaults, dropdowns, computed Jinja2, branch-agnostic, deprecated |
| HIGH |
Hierarchy |
hierarchy- |
Hierarchical generics, parent/children |
| HIGH |
Display |
display- |
human_friendly_id, order_weight, menu placement |
| MEDIUM |
Extensions |
extension- |
Cross-file via extensions block, artifact targets |
| MEDIUM |
Uniqueness |
uniqueness- |
Constraint format, __value suffix |
| MEDIUM |
Migration |
migration- |
Add/remove attributes, state: absent |
| HIGH |
Validation |
validation- |
Load-time string-length caps (description / label / identifier), common error messages, pre-check checklist |
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:
- Gather requirements — Identify the node types,
their attributes, and how they relate to each other.
Ask about hierarchies, dropdowns, and display needs.
- 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.
- 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 2.
- 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.
- 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.
- 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
1---2name: infrahub-managing-schemas-23description: "Creates, validates, and modifies Infrahub schema YAML files — nodes, generics, attributes, relationships, and extensions. TRIGGER when: designing data models, adding schema nodes, validating schema definitions, planning schema migrations, modeling file objects / attachments / uploads (storing PDFs, diagrams, images, certificates, documents as Infrahub objects). DO NOT TRIGGER when: populating data objects, writing checks/generators/transforms, querying live data."4---56# Infrahub Schema Creator78## Overview910Expert guidance for designing and building Infrahub11schemas. Schemas are YAML files defining nodes (concrete12types), generics (abstract base types), attributes,13relationships, and extensions.1415## Project Context1617Existing schemas in this project:18!`find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -20`1920Infrahub config (if present):21!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`2223If invoked with arguments (e.g., `/infrahub:managing-schemas Ipam Vlan VlanGroup`),24use the first argument as the namespace and remaining arguments as node names.2526## When to Use2728- Designing new data models or schema nodes29- Adding attributes or relationships to existing schemas30- Setting up hierarchical location trees or component/parent patterns31- Configuring display properties (human_friendly_id, display_label)32- Migrating or refactoring existing schemas33- Debugging schema validation errors3435## Rule Categories3637| Priority | Category | Prefix | Description |38| -------- | -------- | ------ | ----------- |39| CRITICAL | Branch-First Changes | `workflow-` | Load schema onto a branch, not the default branch |40| CRITICAL | Naming | `naming-` | Namespace, node, attribute naming |41| CRITICAL | Relationships | `relationship-` | IDs, peers, component/parent, on_delete |42| HIGH | Attributes | `attribute-` | Defaults, dropdowns, computed Jinja2, branch-agnostic, deprecated |43| HIGH | Hierarchy | `hierarchy-` | Hierarchical generics, parent/children |44| HIGH | Display | `display-` | human_friendly_id, order_weight, menu placement |45| MEDIUM | Extensions | `extension-` | Cross-file via extensions block, artifact targets |46| MEDIUM | Uniqueness | `uniqueness-` | Constraint format, __value suffix |47| MEDIUM | Migration | `migration-` | Add/remove attributes, state: absent |48| HIGH | Validation | `validation-` | Load-time string-length caps (description / label / identifier), common error messages, pre-check checklist |4950## Schema File Basics5152```yaml53---54# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/schema/latest.json55version: "1.0"5657generics: # Abstract base definitions (shared attributes/relationships)58 - ...59nodes: # Concrete object types60 - ...61extensions: # Add attributes/relationships to existing nodes from other files62 nodes:63 - ...64```6566Always include the `$schema` comment for IDE validation.67Only `version` is required at the top level.6869## Designing for Downstream Consumers7071A schema node rarely lives alone. Before finalizing it,72walk through how it will be used by other parts of the73project and add the inheritance / configuration that74those features require:7576| If the node will... | Add to the schema | See |77| ------------------- | ----------------- | --- |78| Be the target of an artifact (group member referenced by an `artifact_definition`) | `inherit_from: [..., CoreArtifactTarget]` on the concrete node | [rules/extension-artifact-target.md](./rules/extension-artifact-target.md) |79| Be the target of a generator (group member referenced by a `generator_definition`) | `inherit_from: [..., CoreArtifactTarget]` on the concrete node | [rules/extension-artifact-target.md](./rules/extension-artifact-target.md) |80| Appear in a custom sidebar menu | `include_in_menu: false` so the auto-menu doesn't duplicate the manual entry | [../infrahub-managing-menus/rules/schema-integration.md](../infrahub-managing-menus/rules/schema-integration.md) |81| Be cloneable as an object template | `generate_template: true` | [rules/extension-object-template.md](./rules/extension-object-template.md) |82| Store an uploaded file (PDF, image, Visio, KMZ, contract, …) | `inherit_from: [..., CoreFileObject]` on the concrete node | [rules/extension-file-object.md](./rules/extension-file-object.md) |83| Be displayed with a stable name across UI lists and APIs | `human_friendly_id` and `display_label` | [rules/display-human-friendly-id.md](./rules/display-human-friendly-id.md) |8485This audit is the difference between a schema that86"validates" and one that "actually works in the broader87project." Skipping it forces a schema migration once the88downstream feature is wired up — at which point the data89is already loaded.9091When the task spans multiple skills (schemas + transforms,92schemas + menus, etc.), load both skills' rules together93rather than treating the boundaries as exclusive.9495## Design for the cheaper layer9697A schema choice can remove the need for Python or98denormalized data downstream. The schema is the cheapest99place to get this right — fixing it later means a100migration on already-loaded data. Before adding a field or101node, check whether a built-in or structural feature102already covers it:103104| Signal | Cheaper layer | See rule |105| ------ | ------------- | -------- |106| Copying a value onto a node that's reachable by traversing a relationship (`region_code` when `device.location.region.code` exists) | An indirect relationship traversal; let consumers follow the link | [yagni-denormalized-vs-indirect-relationship](../infrahub-auditing-repo/rules/yagni-denormalized-vs-indirect-relationship.md) |107| Several sibling nodes repeating the same attributes and relationships | Extract a generic and `inherit_from` it | [yagni-duplicate-shape-not-extracted-to-generic](../infrahub-auditing-repo/rules/yagni-duplicate-shape-not-extracted-to-generic.md) |108| Defining custom IP address / prefix / VLAN nodes | `inherit_from` the built-in primitive (`BuiltinIPAddress`, `BuiltinIPPrefix`, `IpamVLAN`) | [yagni-custom-domain-primitives-instead-of-builtin](../infrahub-auditing-repo/rules/yagni-custom-domain-primitives-instead-of-builtin.md) |109| An `Attribute` + `cardinality: one` relationship with no inverse on the peer | Declare the matching inverse so consumers filter in the query, not in Python | [yagni-missing-inverse-forces-python-filter](../infrahub-auditing-repo/rules/yagni-missing-inverse-forces-python-filter.md) |110111These are the schema-side counterparts to the "Before112writing Python" guidance in the checks, transforms, and113generators skills. The repo auditor flags them as advisory114cost-to-fix findings; catching them at design time avoids115both the finding and the later migration.116117## Workflow118119Follow these steps when creating or modifying a schema:1201211. **Gather requirements** — Identify the node types,122 their attributes, and how they relate to each other.123 Ask about hierarchies, dropdowns, and display needs.1242. **Read relevant rules** — Read125 [rules/naming-conventions.md](./rules/naming-conventions.md)126 for naming constraints,127 [rules/attribute-defaults-and-types.md](./rules/attribute-defaults-and-types.md)128 for attribute kinds and defaults, and129 [rules/relationship-identifiers.md](./rules/relationship-identifiers.md)130 for bidirectional relationship setup.1313. **Build the schema YAML** — Start with the `$schema`132 comment and `version: "1.0"`. Define generics first133 (if any), then nodes. Apply naming, display, and134 relationship rules from step 2.1354. **Audit downstream consumers** — Walk the table in136 "Designing for Downstream Consumers" above. If any137 node will become an artifact or generator target, add138 `CoreArtifactTarget` to its `inherit_from` now, per139 [rules/extension-artifact-target.md](./rules/extension-artifact-target.md).140 Adding it later forces a schema migration on loaded data.1415. **Configure display properties** — Set142 `human_friendly_id`, `display_label`, and143 `order_weight` per144 [rules/display-human-friendly-id.md](./rules/display-human-friendly-id.md)145 and [rules/display-order-weight.md](./rules/display-order-weight.md).1466. **Validate and roll out on a branch** — Run147 `infrahubctl schema check` to fix errors per148 [validation.md](./validation.md) and149 [rules/validation-common-errors.md](./rules/validation-common-errors.md).150 Then apply the change on a dedicated branch, not the151 default branch (`main` by convention, but it can be152 renamed): `infrahubctl branch create <name>` →153 `schema check --branch <name>` →154 `schema load --branch <name>`, and merge via a proposed155 change once it looks right. A schema load runs156 migrations against loaded data immediately, so on a157 shared server the default branch gives no preview and no158 per-step undo — the branch does. See159 [rules/workflow-branch-first.md](./rules/workflow-branch-first.md).160 The default branch is only reasonable on a local161 throwaway instance.162163## Production Patterns Worth Knowing164165Seven recurring patterns — computed Jinja2 attributes,166cascade-vs-no-action deletes, menu visibility,167branch-agnostic identity, artifact targets, object168templates, and file objects — are documented at the top169of [examples.md](./examples.md). Read those before170finalizing a schema; each pattern is easy to miss171when building from scratch and expensive to retrofit172after data is loaded.173174## Supporting References175176- **[reference.md](./reference.md)** -- Complete property177 tables for nodes, generics, attributes, relationships178- **[examples.md](./examples.md)** -- Full schema patterns179 from production repos180- **[validation.md](./validation.md)** -- `infrahubctl`181 commands, migration strategies, pre-validation checklist182- **[../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**183 -- .infrahub.yml project configuration184- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules185 (git integration, caching) across all skills186- **[rules/](./rules/)** -- Individual rules by category187 prefix