Skip to main content

​
Overview

Schemas in Infrahub define the structure of your data model using YAML files. A schema consists of nodes (entities), attributes (properties), and relationships that connect nodes together.

​
Schema File Structure

Every schema file follows this basic structure: 
# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/schema/latest.json
---
version: "1.0"
generics:
  # Generic (reusable) schema definitions
nodes:
  # Specific node definitions
The yaml-language-server comment enables autocomplete and validation in editors that support the YAML Language Server.

​
Creating a Basic Node

1

Define the node structure

Create a node with basic metadata:
version: "1.0"
nodes:
  - name: Device
    namespace: Infra
    description: "Network device"
    label: "Device"
    icon: "mdi:server"
    default_filter: name__value
    display_label: "{{ name__value }}"
    include_in_menu: true
Key properties:
  • name: Node identifier (combined with namespace for uniqueness)
  • namespace: Organizational grouping
  • description: Human-readable explanation
  • label: Display name in UI
  • icon: UI icon (supports Material Design Icons)
  • default_filter: Default field for filtering/searching
  • display_label: Jinja2 template for display
  • include_in_menu: Show in navigation menu
2

Add attributes

Define the node’s properties:
attributes:
  - name: name
    kind: Text
    unique: true
    order_weight: 1000
  - name: description
    kind: Text
    optional: true
    order_weight: 1200
  - name: status
    kind: Dropdown
    choices:
      - name: active
        label: Active
        description: "Fully operational"
        color: "#7fbf7f"
      - name: maintenance
        label: Maintenance
        description: "Under maintenance"
        color: "#ffd27f"
    default_value: "active"
  - name: port_count
    kind: Number
    optional: true
Attribute kinds:
  • Text: String values
  • TextArea: Multi-line text
  • Number: Numeric values
  • Boolean: True/false
  • Dropdown: Predefined choices
  • DateTime: Date and time
  • IPHost: IP address
  • IPNetwork: IP network/prefix
3

Configure attribute options

Common attribute properties:
  • optional: Allow null values (default: false)
  • unique: Enforce uniqueness (default: false)
  • read_only: Prevent modifications (default: false)
  • default_value: Default when creating objects
  • order_weight: Display order (lower = higher priority)
  • enum: List of allowed values for Text fields
attributes:
  - name: role
    kind: Text
    enum: ["core", "edge", "access"]
    default_value: "access"
  - name: serial_number
    kind: Text
    unique: true
    optional: true

​
Creating Generic Schemas

Generics are reusable schema definitions that other nodes can inherit from: 
generics:
  - name: Generic
    namespace: Organization
    label: Organization
    description: "An organization represents a legal entity"
    default_filter: name__value
    icon: "mdi:domain"
    human_friendly_id: ["name__value"]
    attributes:
      - name: name
        kind: Text
        unique: true
      - name: description
        kind: Text
        optional: true
    relationships:
      - name: tags
        peer: BuiltinTag
        cardinality: many
        kind: Attribute
        optional: true
Nodes can then inherit from this generic: 
nodes:
  - name: Manufacturer
    namespace: Organization
    description: "Device Manufacturer"
    inherit_from:
      - OrganizationGeneric
    relationships:
      - name: devices
        peer: InfraDevice
        cardinality: many
        optional: true

​
Schema Metadata Options

# Define how objects are identified
human_friendly_id: ["name__value"]
# Or composite IDs
human_friendly_id: ["site__name__value", "name__value"]

​
Advanced Attribute Features

attributes:
  - name: status
    kind: Dropdown
    choices:
      - name: active
        label: Active
        description: "Fully operational and currently in service"
        color: "#7fbf7f"
      - name: provisioning
        label: Provisioning
        description: "In the process of being set up"
        color: "#ffff7f"
      - name: drained
        label: Drained
        description: "Temporarily taken out of service"
        color: "#bfbfbf"
    default_value: "active"

​
Text with Enum Values

attributes:
  - name: lacp_mode
    kind: Text
    enum: ["Active", "Passive", "Disabled"]
    default_value: "Active"

​
Number with Constraints

attributes:
  - name: vlan_id
    kind: Number
    parameters:
      min_value: 1
      max_value: 4094

​
Complete Example

Here’s a complete schema file for network devices: 
# yaml-language-server: $schema=https://schema.infrahub.app/infrahub/schema/latest.json
---
version: "1.0"
nodes:
  - name: Device
    namespace: Network
    description: "Network Device"
    label: "Device"
    icon: "mdi:server"
    default_filter: name__value
    human_friendly_id: ["name__value"]
    display_label: "{{ name__value }}"
    order_by:
      - name__value
    include_in_menu: true
    attributes:
      - name: name
        kind: Text
        unique: true
        order_weight: 1000
      - name: description
        kind: Text
        optional: true
      - name: type
        kind: Text
        enum: ["router", "switch", "firewall"]
      - name: status
        kind: Dropdown
        choices:
          - name: active
            label: Active
            color: "#7fbf7f"
          - name: maintenance
            label: Maintenance
            color: "#ffd27f"
        default_value: "active"
      - name: management_ip
        kind: IPHost
        optional: true
      - name: serial_number
        kind: Text
        unique: true
        optional: true
    relationships:
      - name: site
        peer: LocationSite
        cardinality: one
        kind: Attribute
        optional: false
      - name: interfaces
        peer: NetworkInterface
        cardinality: many
        kind: Component
        optional: true
      - name: tags
        peer: BuiltinTag
        cardinality: many
        kind: Attribute
        optional: true

​
Best Practices

Namespace Organization

Group related nodes under common namespaces (e.g., Infra, Location, Organization)

Unique Identifiers

Always define unique attributes for primary identifiers like name or composite keys

Human-Friendly IDs

Use human_friendly_id to create readable object identifiers instead of UUIDs

Display Labels

Configure display_label with Jinja2 templates for meaningful object representation

​
Next Steps

Import Schema

Learn how to load your schema into Infrahub

Define Relationships

Connect nodes together with relationships

Schema Validation

Understand validation rules and constraints

Computed Attributes

Add dynamic calculated fields

Build docs developers (and LLMs) love

Get started for freeTalk to us