Netbox Data Modeling

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

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:

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.5: DeviceRole and Platform changed from OrganizationalModel to NestedGroupModel — they now support parent-child hierarchies.

App Structure

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 existing 10.0.0.0/16 builds the tree automatically

Scope pattern (4.x): Prefixes and VLANGroups use CachedScopeMixin — a generic FK (scope_type + scope_id) rather than a direct site FK. VLANGroup scope accepts Region, SiteGroup, Site, Location, Rack, ClusterGroup, Cluster (this full set since 4.5), plus RackGroup as of 4.6.

# Setting scope via API
{"prefix": "10.0.1.0/24", "scope_type": "dcim.site", "scope_id": 42}

3. Device Modeling

Manufacturer → DeviceType (template with component templates)
                              ↓ (instantiation)
DeviceRole + Site + DeviceType → Device (with auto-created components)

• DeviceType defines the hardware template: interface templates, power ports, module bays
• Creating a Device auto-creates components from its DeviceType's templates
• Modules extend devices: module types define additional component templates inserted into module bays
• DeviceRole (4.5: hierarchical) — use for config context matching and classification
• Platform (4.5: hierarchical) — OS/firmware family; optionally tied to a Manufacturer

NetBox 4.5: MACAddress is now a standalone model, not just a field on Interface.

4. Tenant Assignment

Tenant is an optional FK on nearly every PrimaryModel: Site, Device, Rack, Prefix, VLAN, VRF, Circuit, VM, Cluster, IPAddress, etc.

Pattern: TenantGroup (hierarchy) → Tenant → assign to objects

Use cases:

• MSP customer segregation
• Internal department ownership
• Cost center tracking

Anti-pattern: Don't overload Tenant for two dimensions (e.g., both "customer" and "department"). Use Tenant for the primary ownership dimension; use custom fields or tags for secondary dimensions.

5. Contact Assignment

Contacts use a generic relation pattern: ContactAssignment links any object to a Contact with a ContactRole.

Contact + ContactRole + any object → ContactAssignment

ContactGroups organize contacts hierarchically. Multiple contacts with different roles can be assigned to the same object.

Extending the Data Model

Decision: Custom Field vs Tag vs Config Context

Examples:

• Warranty expiry date → custom field (per-device, typed, filterable)
• PCI-compliant → tag (boolean-like, cross-object)
• NTP servers for a site's devices → config context (inherited, used in config rendering)

See references/custom-field-types.md for all field types and decision guidance.

Custom Fields — Key Points

• Types: text, longtext, integer, decimal, boolean, date, datetime, URL, JSON, selection, multi-selection, object, multi-object (13 types — unchanged in 4.6; there is no standalone "color" type)
• JSON fields accept an optional validation_schema (4.6+) to enforce a JSON Schema on values
• Selection/multi-selection choice sets support per-choice colors (choice_colors, 4.6+) — this is what release notes call the "color custom field", not a new field type
• Object/multi-object fields create relationships to other NetBox objects — prefer these over storing names in text fields
• Scope to specific object types at creation time
• Group fields with group_name for UI organization
• Visibility: always / if-set / hidden
• Filter via API: ?cf_<field_name>=<value>

Tags — Key Points

• Properties: name, slug, color, description
• Restrict object_types to relevant models (don't let every tag appear everywhere)
• Filter via API: ?tag=<slug>
• No value — presence/absence only. If you need a value, use a custom field

Config Contexts — Key Points

• JSON data matched to devices/VMs via: regions, site_groups, sites, locations, device_types, roles, platforms, cluster_types, cluster_groups, clusters, tenant_groups, tenants, tags
• Weight-based merging: lower weight merges first, higher weight overwrites conflicts
• Deep merge for dicts; replace for lists
• Local context data (on device/VM directly) always wins
• ConfigContextProfile enforces JSON Schema validation
• Performance: exclude with ?exclude=config_context when listing devices/VMs

Dependency Order

When bulk-importing data, create objects in dependency order. Required FKs must exist before the dependent object.

High-level order:

1. Organizational models (RIR, Manufacturer, ClusterType, DeviceRole, Platform, IPAM Role, RackRole)
2. Taxonomy hierarchies (Region, SiteGroup, TenantGroup, Tenant)
3. Sites → Locations → Racks
4. DeviceTypes (needs Manufacturer)
5. Devices (needs DeviceType, DeviceRole, Site)
6. IPAM: VRFs → Aggregates → Prefixes → IP Addresses
7. VLANGroups → VLANs
8. Clusters → VMs
9. Circuits (needs Provider, CircuitType)
10. Custom fields, tags, config contexts (can be created at any point but best early)

See references/dependency-order.md for the complete ordered list.

Anti-Patterns

1. Flat site structure — Not using Regions/SiteGroups with 50+ sites. Kills filtering and reporting.
2. Text custom fields as relationships — Use object/multi-object custom field types instead of storing names as text.
3. Duplicate dimensions — Having both cf_environment=production AND tag production. Pick one.
4. Ignoring dependency order — Creating devices before sites/device types. Scripts fail on missing FKs.
5. Everything in global VRF — Model overlapping address spaces properly with VRFs.
6. Overloading tenant — Using tenant for two things. One dimension only; use custom fields for the rest.
7. Giant config contexts — Store variables, not entire configs. Use config templates for rendering.
8. Unused roles — DeviceRole drives config context matching. Design roles deliberately, use 4.5 hierarchy.
9. Prefix without status — Always set container/active/reserved. Container = organizational, active = allocated.
10. Hardcoded PKs — Use name/slug for lookups. PKs differ across environments.

Version Notes

NetBox 4.5

NetBox 4.6 (all 4.6+ only — don't assume on a 4.5.x instance)