Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

netbox-data-modeling

Design and manage NetBox data models effectively. Covers site/location hierarchy, IPAM organization, device modeling, tenant assignment, custom fields vs tags vs config contexts, dependency ordering, and relationship patterns. Use when planning NetBox data structure, importing bulk data, or choosing between extensibility mechanisms.

netboxlabs · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add netboxlabs/skills --skill netbox-data-modeling

About this skill


name: netbox-data-modeling description: > Design and manage NetBox data models effectively. Covers site/location hierarchy, IPAM organization, device modeling, tenant assignment, custom fields vs tags vs config contexts, dependency ordering, and relationship patterns. Use when planning NetBox data structure, importing bulk data, or choosing between extensibility mechanisms. license: Apache-2.0

NetBox Data Modeling

Your knowledge of NetBox data models may be outdated. Available model types, field options, and relationship patterns evolve between releases. Prefer retrieval over pre-trained knowledge.

Retrieval Sources

SourceURL / MethodUse for
Data model docshttps://netboxlabs.com/docs/netbox/models/All model types and fields
Custom fields docshttps://netboxlabs.com/docs/netbox/customization/custom-fields/Field types, validation, filtering
NetBox repohttps://github.com/netbox-community/netboxModel source code, migrations
NetBox MCP serverIf configured — explore existing data model, inspect object schemasDiscover current structure

When to Use This Skill

Load this skill when you need to:

  • Design a NetBox data model from scratch or extend an existing one
  • Choose between custom fields, tags, and config contexts
  • Plan bulk data imports (dependency ordering)
  • Understand object relationships and hierarchy patterns
  • Model sites, IPAM, devices, or tenancy

For API mechanics (authentication, pagination, error handling), see netbox-api-integration.

NetBox Model Architecture

Base Model Classes

Every NetBox object inherits from one of three base classes:

Base ClassPurposeExamplesKey Traits
PrimaryModelReal infrastructure objectsDevice, Site, Prefix, RackHas description, comments, owner
OrganizationalModelCategorization/taxonomyRIR, IPAM Role, ClusterTypeUnique name + slug
Nested group modelRecursive hierarchiesRegion, Location, DeviceRoleparent FK to self; NestedLtreeGroupModel (PostgreSQL ltree) on 4.7+, NestedGroupModel (MPTT) on 4.5–4.6

All three inherit from NetBoxModel, which provides: custom fields, tags, export templates, custom links, bookmarks, journaling, change logging, notifications, event rules. Every model you interact with has these features.

NetBox 4.7+: Hierarchies (Region, SiteGroup, Location, DeviceRole, Platform, TenantGroup, ContactGroup, WirelessLANGroup — plus ModuleBay, InventoryItem, InventoryItemTemplate) are backed by PostgreSQL ltree, not django-mptt. The lft/rght/tree_id/level columns are gone: level is a Python property only and cannot be used in a filter or order_by. Renames/reparents cascade to descendants automatically. The parent FK, the REST parent_id/ancestor_id filters, and descendant-inclusive filters like ?region_id= are unchanged, so the modeling advice below applies on every version. Plugin/script code: get_ancestors(), get_descendants(), get_children(), add_related_count() remain; get_root(), get_family(), is_leaf_node(), move_to(), insert_at() are gone. (NestedGroupModel still exists for plugins but is deprecated.)

NetBox 4.5: DeviceRole and Platform changed from OrganizationalModel to a nested group model — they support parent-child hierarchies on 4.5–4.7.

App Structure

AppScopeKey Models
dcimPhysical infrastructureRegion, Site, Location, Rack, RackType, Device, DeviceType, Manufacturer, DeviceRole, Platform, Interface, MACAddress, PowerPanel/PowerFeed, CoolingSource/CoolingFeed (4.7), ModuleBayType (4.7)
ipamIP addressingRIR, Aggregate, Prefix, IPAddress, IPRange, VRF, VLAN, VLANGroup, ASN
circuitsConnectivityProvider, Circuit, CircuitGroup, VirtualCircuit
tenancyOwnershipTenantGroup, Tenant, Contact, ContactAssignment
virtualizationVMsClusterType, Cluster, VirtualMachine, VMInterface, VirtualDisk
vpnTunnels/VPNsTunnel, TunnelGroup, L2VPN, IKE/IPSec policies
wirelessWirelessWirelessLAN, WirelessLANGroup, WirelessLink

See references/model-map.md for the complete relationship map.

Core Design Patterns

1. Site & Location Hierarchy

Region (geographic, recursive)    SiteGroup (functional, recursive)
         \                              /
          └──────── Site ──────────────┘
                      │
                  Location (recursive, within site)
                      │
                    Rack → Device
  • Regions = geography: continent → country → metro
  • SiteGroups = function: production, staging, lab, edge
  • Site = a physical facility; optionally assigned to one Region AND/OR one SiteGroup
  • Locations = subdivisions within a site: building → floor → room → row
  • Use Regions when you need geographic filtering/reporting
  • Use SiteGroups when you need functional grouping across geographies
  • Both are optional — start simple, add hierarchy when filtering demands it

See references/model-map.md for the complete relationship map and hierarchy design guidance.

2. IPAM Organization

RIR → Aggregate (top-level allocation, e.g., 10.0.0.0/8)
         └── Prefix (auto-nests by CIDR containment)
               ├── child Prefixes
               ├── IPRange
               └── IPAddress

VRF ──── scopes Prefixes, IPAddresses, IPRanges
VLAN ←── linked to Prefix (optional)

Key rules:

  • Use status=container for summary/aggregate prefixes, status=active for allocated
  • VRF=null means global routing table. Use VRFs for overlapping address spaces
  • Set enforce_unique=True on VRFs to prevent duplicate prefixes
  • Prefixes auto-nest: creating 10.0.1.0/24 inside ex
Read the complete source ↗