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 |
| MEDIUM |
File Formatting |
format- |
Canonical key order; infrahubctl schema format (offline) |
| 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:
| Signal |
Cheaper layer |
See rule |
| Building any domain from scratch (the marketplace publishes far more than DCIM / location / org — routing, security, compute, and many more) |
Search the whole marketplace and reuse a published schema: infrahubctl marketplace get <ns>/<name> then inherit_from |
yagni-reuse-existing-marketplace-schema |
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 |
| Several sibling nodes repeating the same attributes and relationships |
Extract a generic and inherit_from it |
yagni-duplicate-shape-not-extracted-to-generic |
| Defining custom IP address / prefix / VLAN nodes |
inherit_from the built-in primitive (BuiltinIPAddress, BuiltinIPPrefix, IpamVLAN) |
yagni-custom-domain-primitives-instead-of-builtin |
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 |
| A Profile carrying a single value that never varies across objects |
An attribute default_value — a Profile only earns its cost when values vary or are re-tuned centrally |
yagni-profile-over-default |
| Reaching for an Object Template to share live values, or a Profile to clone a node's child components |
Match the tool to intent: a Profile shares live values, an Object Template clones structure |
yagni-template-profile-confusion |
Enabling generate_profile / generate_template before any Profile or template will use it |
Enable the flag when the defaults/cloning workflow actually exists |
yagni-unused-generate-flag |
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.
- 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.
- 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 3.
- 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.
- 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.
- 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-33description: >-4 Creates, validates, formats, and modifies Infrahub schema YAML files — nodes, generics, attributes, relationships, and extensions. Also checks the Infrahub Marketplace for an existing published schema to reuse before modelling a domain from scratch.5 TRIGGER when: designing data models, adding schema nodes, validating schema definitions, planning schema migrations, looking for an existing/off-the-shelf schema or checking the marketplace for a domain (DCIM, location, routing, etc.), modeling file objects / attachments / uploads (storing PDFs, diagrams, images, certificates, documents as Infrahub objects), formatting or tidying schema files, normalising / canonicalising schema key order, cleaning up noisy schema diffs where every edit reshuffles keys, or running `infrahubctl schema format` (including as a CI gate).6 DO NOT TRIGGER when: populating data objects, writing checks/generators/transforms, querying live data.7allowed-tools:8 - Read9 - Write10 - Edit11 - Bash12argument-hint: "[namespace] [node-names...]"13metadata:14 source: https://skillmd.com/skills/opsmill/infrahub-managing-schemas-315 version: 1.2.816 author: OpsMill17---1819# Infrahub Schema Creator2021## Overview2223Expert guidance for designing and building Infrahub24schemas. Schemas are YAML files defining nodes (concrete25types), generics (abstract base types), attributes,26relationships, and extensions.2728## Project Context2930Existing schemas in this project:31!`find . -name "*.yml" -path "*/schemas/*" -o -name "*schema*" -name "*.yml" 2>/dev/null | head -20`3233Infrahub config (if present):34!`cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"`3536If invoked with arguments (e.g., `/infrahub:managing-schemas Ipam Vlan VlanGroup`),37use the first argument as the namespace and remaining arguments as node names.3839## When to Use4041- Designing new data models or schema nodes42- Adding attributes or relationships to existing schemas43- Setting up hierarchical location trees or component/parent patterns44- Configuring display properties (human_friendly_id, display_label)45- Migrating or refactoring existing schemas46- Debugging schema validation errors4748## Rule Categories4950| Priority | Category | Prefix | Description |51| -------- | -------- | ------ | ----------- |52| CRITICAL | Branch-First Changes | `workflow-` | Load schema onto a branch, not the default branch |53| CRITICAL | Naming | `naming-` | Namespace, node, attribute naming |54| CRITICAL | Relationships | `relationship-` | IDs, peers, component/parent, on_delete |55| HIGH | Attributes | `attribute-` | Defaults, dropdowns, computed Jinja2, branch-agnostic, deprecated |56| HIGH | Hierarchy | `hierarchy-` | Hierarchical generics, parent/children |57| HIGH | Display | `display-` | human_friendly_id, order_weight, menu placement |58| MEDIUM | Extensions | `extension-` | Cross-file via extensions block, artifact targets |59| MEDIUM | Uniqueness | `uniqueness-` | Constraint format, __value suffix |60| MEDIUM | Migration | `migration-` | Add/remove attributes, state: absent |61| MEDIUM | File Formatting | `format-` | Canonical key order; `infrahubctl schema format` (offline) |62| HIGH | Validation | `validation-` | Load-time string-length caps (description / label / identifier), common error messages, pre-check checklist |6364## Schema File Basics6566```yaml67---68# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/schema/latest.json69version: "1.0"7071generics: # Abstract base definitions (shared attributes/relationships)72 - ...73nodes: # Concrete object types74 - ...75extensions: # Add attributes/relationships to existing nodes from other files76 nodes:77 - ...78```7980Always include the `$schema` comment for IDE validation.81Only `version` is required at the top level.8283## Designing for Downstream Consumers8485A schema node rarely lives alone. Before finalizing it,86walk through how it will be used by other parts of the87project and add the inheritance / configuration that88those features require:8990| If the node will... | Add to the schema | See |91| ------------------- | ----------------- | --- |92| 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) |93| 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) |94| 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) |95| Be cloneable as an object template (node + its component children) | `generate_template: true` | [rules/extension-object-template.md](./rules/extension-object-template.md) |96| Provide shared default values across many instances | `generate_profile: true` (+ Profile instances) | [rules/extension-object-profile.md](./rules/extension-object-profile.md) |97| 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) |98| 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) |99100This audit is the difference between a schema that101"validates" and one that "actually works in the broader102project." Skipping it forces a schema migration once the103downstream feature is wired up — at which point the data104is already loaded.105106When the task spans multiple skills (schemas + transforms,107schemas + menus, etc.), load both skills' rules together108rather than treating the boundaries as exclusive.109110## Design for the cheaper layer111112A schema choice can remove the need for Python or113denormalized data downstream. The schema is the cheapest114place to get this right — fixing it later means a115migration on already-loaded data. Before adding a field or116node, check whether a built-in or structural feature117already covers it:118119| Signal | Cheaper layer | See rule |120| ------ | ------------- | -------- |121| Building any domain from scratch (the marketplace publishes far more than DCIM / location / org — routing, security, compute, and many more) | Search the whole marketplace and reuse a published schema: `infrahubctl marketplace get <ns>/<name>` then `inherit_from` | [yagni-reuse-existing-marketplace-schema](../infrahub-auditing-repo/rules/yagni-reuse-existing-marketplace-schema.md) |122| 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) |123| 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) |124| 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) |125| 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) |126| A Profile carrying a single value that never varies across objects | An attribute `default_value` — a Profile only earns its cost when values vary or are re-tuned centrally | [yagni-profile-over-default](../infrahub-auditing-repo/rules/yagni-profile-over-default.md) |127| Reaching for an Object Template to share live values, or a Profile to clone a node's child components | Match the tool to intent: a Profile shares live values, an Object Template clones structure | [yagni-template-profile-confusion](../infrahub-auditing-repo/rules/yagni-template-profile-confusion.md) |128| Enabling `generate_profile` / `generate_template` before any Profile or template will use it | Enable the flag when the defaults/cloning workflow actually exists | [yagni-unused-generate-flag](../infrahub-auditing-repo/rules/yagni-unused-generate-flag.md) |129130These are the schema-side counterparts to the "Before131writing Python" guidance in the checks, transforms, and132generators skills. The repo auditor flags them as advisory133cost-to-fix findings; catching them at design time avoids134both the finding and the later migration.135136## Workflow137138Follow these steps when creating or modifying a schema:1391401. **Gather requirements** — Identify the node types,141 their attributes, and how they relate to each other.142 Ask about hierarchies, dropdowns, and display needs.1432. **Check the marketplace first** — Before modelling144 *any* domain from scratch, search the whole Infrahub145 Marketplace and reuse a published schema when one146 covers it: `infrahubctl marketplace get147 <namespace>/<name>`, then `inherit_from` the pulled148 generics and add only site-specific attributes.149 Discovery, collections (`-c`), the airgap fallback,150 and the required SDK version live in151 [../infrahub-common/marketplace-reference.md](../infrahub-common/marketplace-reference.md).1523. **Read relevant rules** — Read153 [rules/naming-conventions.md](./rules/naming-conventions.md)154 for naming constraints,155 [rules/attribute-defaults-and-types.md](./rules/attribute-defaults-and-types.md)156 for attribute kinds and defaults, and157 [rules/relationship-identifiers.md](./rules/relationship-identifiers.md)158 for bidirectional relationship setup.1594. **Build the schema YAML** — Start with the `$schema`160 comment and `version: "1.0"`. Define generics first161 (if any), then nodes. Apply naming, display, and162 relationship rules from step 3.1635. **Audit downstream consumers** — Walk the table in164 "Designing for Downstream Consumers" above. If any165 node will become an artifact or generator target, add166 `CoreArtifactTarget` to its `inherit_from` now, per167 [rules/extension-artifact-target.md](./rules/extension-artifact-target.md).168 Adding it later forces a schema migration on loaded data.1696. **Configure display properties** — Set170 `human_friendly_id`, `display_label`, and171 `order_weight` per172 [rules/display-human-friendly-id.md](./rules/display-human-friendly-id.md)173 and [rules/display-order-weight.md](./rules/display-order-weight.md).1747. **Format the file** — Put the keys in the canonical175 order before committing so diffs stay small. Run176 `infrahubctl schema format` when your `infrahubctl`177 provides it (offline, no server); otherwise author the178 order by hand. See179 [rules/format-schema-files.md](./rules/format-schema-files.md).1808. **Validate and roll out on a branch** — Run181 `infrahubctl schema check` to fix errors per182 [validation.md](./validation.md) and183 [rules/validation-common-errors.md](./rules/validation-common-errors.md).184 Then apply the change on a dedicated branch, not the185 default branch (`main` by convention, but it can be186 renamed): `infrahubctl branch create <name>` →187 `schema check --branch <name>` →188 `schema load --branch <name>`, and merge via a proposed189 change once it looks right. A schema load runs190 migrations against loaded data immediately, so on a191 shared server the default branch gives no preview and no192 per-step undo — the branch does. See193 [rules/workflow-branch-first.md](./rules/workflow-branch-first.md).194 The default branch is only reasonable on a local195 throwaway instance.196197## Production Patterns Worth Knowing198199Seven recurring patterns — computed Jinja2 attributes,200cascade-vs-no-action deletes, menu visibility,201branch-agnostic identity, artifact targets, object202templates, and file objects — are documented at the top203of [examples.md](./examples.md). Read those before204finalizing a schema; each pattern is easy to miss205when building from scratch and expensive to retrofit206after data is loaded.207208## Supporting References209210- **[reference.md](./reference.md)** -- Complete property211 tables for nodes, generics, attributes, relationships212- **[examples.md](./examples.md)** -- Full schema patterns213 from production repos214- **[validation.md](./validation.md)** -- `infrahubctl`215 commands, migration strategies, pre-validation checklist216- **[../infrahub-common/infrahub-yml-reference.md](../infrahub-common/infrahub-yml-reference.md)**217 -- .infrahub.yml project configuration218- **[../infrahub-common/marketplace-reference.md](../infrahub-common/marketplace-reference.md)**219 -- reusing published marketplace schemas and collections220 (`infrahubctl marketplace get` / `list` / `search` / `show`, airgap)221- **[../infrahub-common/rules/](../infrahub-common/rules/)** -- Shared rules222 (git integration, caching) across all skills223- **[../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)**224 -- Skill content first; how to consult `docs.infrahub.app`225 on a genuine gap (e.g. deleting nodes)226- **[rules/](./rules/)** -- Individual rules by category227 prefix