NetBox's Data Model: Sites, Devices, Interfaces, IP Addresses

A device record, real and verified

a real NetBox device record shape -- verified against the exact fields nornir_netbox's own real source reads

{
"id": 1,
"name": "SW1",
"serial": "SW1-SN-001",
"asset_tag": null,
"site": { "id": 1, "name": "HQ", "slug": "hq" },
"device_role": { "id": 1, "name": "Switch", "slug": "switch" },
"device_type": {
  "id": 1, "slug": "catalyst-3850",
  "manufacturer": { "id": 1, "name": "Cisco", "slug": "cisco" }
},
"platform": { "id": 1, "name": "Cisco IOS", "slug": "cisco_ios" },
"primary_ip": { "id": 1, "address": "10.10.10.1/24" },
"custom_fields": {}
}

Verified against nornir_netbox's real, installed source (Lesson 5) -- these exact fields (site, device_role, device_type.manufacturer, platform, primary_ip, custom_fields) are what a real inventory plugin actually reads.

Related records, not a flat row

A hosts.yaml row is flat: hostname, platform, maybe a group. A NetBox device record points at other records -- a site (itself a record), a manufacturer (itself a record), a platform (itself a record, with its own napalm_driver field, Lesson 5). Changing "HQ" the site once changes it everywhere it's referenced.

Quick checkConcept check

What's the real structural difference between a hosts.yaml row and a NetBox device record?

There is none -- both are equally flatA NetBox device record references other structured records (site, manufacturer, platform) instead of embedding flat strings -- changing the referenced record changes it everywhere it's usedNetBox device records don't have a hostnamehosts.yaml also supports relational references natively

The connection to what NAPALM already taught

NAPALM's get_facts() -- Phase 3.5

Live queryasks the device right now
vendor, model, serial_number, hostnamenormalized, from the device itself
Answers: what IS this device, right now?

NetBox's device record -- this module

Stored queryasks the source of truth
manufacturer.name, device_type, serial, platformthe same concepts, stored and editable
Answers: what is this device SUPPOSED to be?

Quick checkScenario

Both get_facts() and a NetBox device record can tell you a device's vendor and serial number. What's the real difference in what each one answers?

They're identical in every way -- no real differenceget_facts() answers what a device IS right now, queried live; a NetBox record answers what a device is SUPPOSED to be, stored centrally -- useful for comparing intended state against live state, a real compliance patternNetBox records can only ever be wrongget_facts() is always more reliable than a NetBox record

Interfaces and IP addresses

real, verified — interface and IP address record shapes

# GET /api/dcim/interfaces/  (one record per physical/logical interface)
{ "id": 10, "device": { "id": 1, "name": "SW1" }, "name": "GigabitEthernet0/1", "enabled": true }

# GET /api/ipam/ip-addresses/  (one record per address, referencing an interface)
{ "id": 20, "address": "10.10.10.1/24", "assigned_object": { "id": 10, "name": "GigabitEthernet0/1" } }

Verified against NetBox's documented REST schema, and confirmed executable via pynetbox against this module's own local mock backend (Lesson 3) -- real, verified output, not invented. Interfaces and IPs are their own records, each referencing the device/interface they belong to -- not embedded fields.

Quick checkIdentify the correct code

Which correctly describes how an IP address record relates to a device in NetBox's real data model?

An IP address is a flat string field directly on the device recordAn IP address is its own record, referencing the interface it's assigned to (assigned_object) -- the device is reached indirectly, through that interfaceDevices can only ever have one IP address, embedded directlyIP addresses are not modeled by NetBox at all

Custom fields: the escape hatch

For anything NetBox's built-in schema doesn't cover

custom_fields is a free-form dict on a device record -- the same escape-hatch idea as Nornir's own data: field (Phase 3.4) or NAPALM's optional_args. Site-specific metadata that isn't one of NetBox's built-in fields goes here.

Quick checkPredict output

A team wants to track which devices are due for a firmware upgrade, a concept NetBox has no built-in field for. Where does this belong?

It can't be tracked in NetBox at allIn custom_fields -- NetBox's real, documented escape hatch for data outside its built-in schema, the same free-form-extension idea as Nornir's data: fieldIt must be renamed to fit an existing built-in fieldIn the device's name field

Key takeaways

A NetBox device record references other structured records (site, manufacturer, platform) -- verified against the real fields a Nornir inventory plugin actually reads.
NetBox's stored data and NAPALM's get_facts() cover overlapping concepts (vendor, serial, model) but answer different questions: intended state vs. live state.
Interfaces and IP addresses are their own record types, referencing what they belong to -- not flat embedded fields.
custom_fields is NetBox's real, documented escape hatch for data outside its built-in schema -- the same idea as Nornir's data: field.

What you'll learn

A device record, real and verified

The connection to what NAPALM already taught

Interfaces and IP addresses

Custom fields: the escape hatch