Declare the location hierarchy

Every inventory has a location hierarchy: an ordered list of levels, and every location as a path of names, one per level. Each contribution maps the source fields that hold its location to these levels. Census gives each entity one location in the hierarchy, and consumers filter by location with location=eu/par1.

[inventories.devices.location]
levels = ["region", "site", "rack"]
locations = [
  "eu", "eu/par1", "eu/par1/r01", "eu/par1/r02",
  "us", "us/nyc1", "us/nyc1/r01",
]
priority = ["netbox", "infrahub"]          # optional

[[inventories.devices.contributions]]
id = "infrahub"
# ...
[inventories.devices.contributions.location]
site = "site.node.name.value"

[inventories.devices.contributions.location_values.site]
"PAR-1" = "par1"

[[inventories.devices.contributions]]
id = "netbox"
# ...
[inventories.devices.contributions.location]
site = "site.slug"
rack = "rack.name"

Declare levels and locations

• levels lists at least one level, from the top down. Level names follow the same rule as field names: a lowercase letter, then lowercase letters, digits and _.
• locations lists every location as a path of 1 to len(levels) names joined by /. The first name is at the first level, and so on.
• Every location's parent is declared too: eu/par1/r01 needs eu/par1, which needs eu.
• A name is unique among its siblings only, so two sites can each have a rack r01.
• Names cannot contain / and cannot start or end with whitespace.

Adding a location is a configuration change and needs a restart.

Map a contribution's location

A contribution's location table maps each level it knows to a source field path. A contribution can map only some levels, for example only the site.

Census reads each mapped level, translates the name with location_values if the table has it (compared apart from letter case and surrounding whitespace), then looks for the declared location whose names match every supplied level, at the depth of the deepest supplied level.

Match	Outcome	Location from this contribution
Exactly one declared location	as_reported, or mapped if a name was translated	That location
No declared location	unmapped	Unknown
Several declared locations	ambiguous	Unknown

A contribution that supplies only the rack r01 matches both eu/par1/r01 and us/nyc1/r01, so the result is ambiguous. Map the site too, so that the match is unique.

Location names are compared exactly after translation: the source must supply par1, or location_values must translate its spelling.

How Census picks one location per entity

The location follows the same priority rules as a field, and a lower-priority contribution can make it more specific when its location lies inside the winner's location. Choose which source supplies each field gives an example.

What consumers read

• GET /v1/inventories/{id}/locations returns the levels and the locations as a tree.
• Each entity has a location path, or null.
• location=eu/par1 returns the entities at eu/par1 and below it.
• The diagnostics list a location that matches no declared location as unmapped with the field location, and a location that matches several as ambiguous_location. Each item has the names the source reported and the path of each level.