feat: draft for schema library v2

[BaptisteGi]

Schema Library v2.0

Version 2.0 is a full pass over the base DCIM and IPAM schemas and most extensions, rather than an incremental update. It combines two kinds of work: closing data-modeling gaps found in an audit of the previous schema — VRF route targets that could only hold one target, interfaces with no valid default MTU, two competing topology and location models, inconsistent use of Dropdown versus plain-text enums, typos in published attribute names, among others — and adding capabilities the library didn't have before, such as tracking swappable device modules and power supplies, assigning IP aggregates to a registry, and scoping tenancy to devices and prefixes. Because so much of the base and extension schemas changed shape as part of that cleanup, v2.0 is not compatible with schemas or data built on v1.x: loading it as-is over an existing v1.x deployment will fail or silently drop data on the attributes and relationships listed below, so plan a migration rather than an in-place upgrade.

Warning

Breaking changes in this release

This release changes attribute and relationship names, types, and cardinalities across base/dcim.yml, base/ipam.yml, base/location.yml, and most extensions. Loading v2.0 over data created with v1.x schemas requires migrating that data first.

Highlights

• Track modules and power supplies as inventory on a device. The previous extensions/modules shipped no ready-to-use node types, only a generic to build on. extensions/device_module now ships a working Module/ModuleType pair tied to a DcimModuleBay slot, and extensions/device_psu_module adds a PSU flavor with wattage and hot-swap attributes. See Track modules and power supplies as inventory on a device.
• Assign top-level IP space to a registry. There was no way to record which RIR (or private authority) assigned a given block of address space. The new extensions/aggregate extension adds an Aggregate node tied to an RIR node. See Assign IP aggregates to a registry.
• Model racks and standalone sites without a full location hierarchy. Racks were only available nested inside the four-tier location_minimal hierarchy. extensions/rack and extensions/location_site split racks and sites into their own extensions, so either can be loaded independently. See Model racks and standalone sites independently of a full location hierarchy.
• Scope tenancy to devices, prefixes, and locations. The experimental tenancy schema only linked a tenant to buildings and circuits. extensions/tenancy (promoted out of experimental) wires a Tenant directly to devices, prefixes, IP addresses, and hosted locations. See Scope tenancy to devices, prefixes, and hosted locations.
• Model VRFs, interfaces, and VLANs closer to industry standards. Route targets, interface MTU/role/status choices, and VLAN/QinQ modeling all had known modeling errors or inconsistencies. See Align VRFs, interfaces, and VLANs with industry standards.

Track modules and power supplies as inventory on a device

Devices with swappable hardware — fan trays, line cards, power supplies — can now be modeled as installed modules rather than static device attributes.

What changed:

• extensions/device_module (replacing extensions/modules) adds a DcimModuleBay node representing a physical slot on a device, and a ready-to-use Module/ModuleType pair that installs into a bay. A module can only be tracked once it is installed in a bay; spares awaiting installation are not modeled.
• extensions/device_psu_module (new, depends on extensions/device_module) adds a PSU-specific module type with wattage (Number) and hotswappable (Boolean) attributes.
• extensions/modules_linecards and extensions/modules_routing_engine now depend on extensions/device_module instead of the removed extensions/modules.
• extensions/patch_panel no longer defines its own DcimPatchPanelModule node; a patch panel's modules are now tracked through the same DcimModuleBay mechanism as any other device.

Assign IP aggregates to a registry

Top-level address space can now be tracked back to the registry or private authority that assigned it, rather than only appearing as a role on a generic prefix.

What changed:

• extensions/aggregate (new) adds an Aggregate node for top-level IPv4/IPv6 blocks, and an RIR node (with an is_private flag) that an aggregate points to.

Model racks and standalone sites independently of a full location hierarchy

A rack or a site can now be loaded on its own, without pulling in the rest of a country/metro/site hierarchy.

What changed:

• extensions/rack (new) splits LocationRack out of extensions/location_minimal into its own extension, and relates it to a site through an explicit site/racks relationship rather than hierarchical nesting. It adds status, serial_number, and asset_tag attributes that the rack did not have before.
• extensions/location_site (new) adds a standalone LocationSite node (facility, physical address, timezone, status) with no region or country tier above it. It defines the same Location.Site node as extensions/location_minimal, so load one or the other, not both.
• extensions/location_minimal's hierarchy changes from Country → Metro → Site → Rack to Region → Country → Site (the Metro tier is removed, a Region tier is added above Country, and Rack moves to its own extension as described above).

Scope tenancy to devices, prefixes, and hosted locations

A tenant can now own the devices, address space, and locations it's responsible for directly, instead of only circuits and buildings.

What changed:

• extensions/tenancy (promoted from experimental/tenancy, and rebuilt) wires a Tenant node to DcimGenericDevice (devices), IpamPrefix (prefixes), IpamIPAddress (addresses), and LocationHosting (locations). It no longer depends on extensions/circuit; extending tenancy onto circuits or other optional nodes is documented as a pattern you apply yourself in tenancy.yml.

Align VRFs, interfaces, and VLANs with industry standards

Several base and extension schemas are retyped or restructured to match industry standards, and to fix values that couldn't previously be expressed at all.

What changed:

• IpamVRF.import_rt and export_rt change from cardinality: one to cardinality: many, so a VRF can import or export more than one route target — the corresponding IpamRouteTarget relationship splits into import_vrf/export_vrf.
• DcimInterface's default mtu of 1514 (the full Ethernet frame size) is removed from the shared generic; InterfacePhysical now sets a default of 1500 (the IP payload size) directly. InterfaceVirtual no longer carries an mtu attribute.
• DcimInterface.role drops the lag choice (LAG is already modeled by InterfaceLag) and renames cust to customer. DcimInterface.status drops deleted and outage and is now mandatory.
• QinQ moves from a qinq_role Dropdown patched onto the generic IpamVLAN (extensions/qinq/qinq.yaml) to dedicated IpamSVLAN and IpamCVLAN node types (extensions/qinq/qinq.yml — note the corrected .yml extension) built on a new GenericVLAN base. A CVLAN's name is computed from its parent SVLAN and VLAN ID.
• IpamL2Domain is replaced by IpamVLANGroup, scoped to a location the same way extensions/aggregate scopes to an RIR.
• extensions/topology's schema is removed; experimental/topology remains the only topology model in the library.
• SNMP community/client enums (SnmpCommunityV2.access, SnmpCommunityV3.auth_protocol/privacy_protocol) and BGPSession.session_type change from kind: Text with an enum: list to kind: Dropdown, and their stored values change case (e.g. EXTERNAL → external, Read-Only → read_only).

Bug fixes

• RoutingBGPSession.import_routing_policies/export_routing_policies pointed to the generic RoutingPolicy peer and reused the same relationship identifiers (bgp__import_policies/bgp__export_policies) as the equivalent relationships on RoutingBGPPeerGroup. Both now point to RoutingPolicyBGP and use distinct identifiers, so a session's routing policies no longer risk being conflated with a peer group's.
• IpamIPAddress.interface and InterfaceLayer3.ip_addresses are now linked with a matching identifier, so the two sides resolve as one relationship instead of being treated as unrelated.

Minor changes

Documentation

• Regenerated the schema reference docs (docs/docs/reference/*.mdx) for every base and extension schema to reflect the v2.0 model, and added dedicated reference pages for aggregate, device_module, device_psu_module, location_site, and rack.
• Added a standard header to every base and extension schema file noting that it's a starting point, not a finished production model, and pointing to docs.infrahub.app or OpsMill for architectural review.

Developer Experience

• Added a load_demo_ipam_dcim invoke task that loads the base schema plus a curated set of extensions (aggregate, cable, circuit, compute, cluster, hosting_cluster, lag, location_minimal, vlan, qinq, rack, vrf) for a demo environment.

Reliability

• extensions/firewall_policer moves to experimental/firewall_policer.

Full changelog

Added

• extensions/aggregate — Aggregate and RIR nodes for top-level IP address space. (#75)
• extensions/device_module — DcimModuleBay, Module, and ModuleType nodes, replacing extensions/modules. (#75)
• extensions/device_psu_module — PSU-specific module type with wattage and hotswappable. (#75)
• extensions/rack — standalone LocationRack, split out of extensions/location_minimal. (#75)
• extensions/location_site — standalone LocationSite with no region/country hierarchy. (#75)
• extensions/tenancy — promoted from experimental/tenancy, wired to devices, prefixes, addresses, and hosted locations. (#75)
• DcimCircuit.commit_rate, DcimCircuitEndpoint.side, IpamVRF.enforce_unique, IpamIPAddress.status/role, SnmpCommunity.devices, SnmpClient.ip_address. (#75)
• tasks/schemas.py: load_demo_ipam_dcim invoke task. (#75)

Changed

• IpamVRF.import_rt/export_rt — cardinality: one to many. (#75)
• DcimInterface.mtu — default 1514 to 1500, moved from the shared generic to InterfacePhysical only. (#75)
• DcimInterface.role/status choices reduced and renamed (cust→customer, lag removed; deleted/outage removed). (#75)
• DcimDevice.status choices — drained removed, reserved/deprecated added. (#75)
• extensions/qinq — rebuilt around IpamSVLAN/IpamCVLAN; file renamed qinq.yaml → qinq.yml. (#75)
• IpamL2Domain → IpamVLANGroup, scoped via the new IpamVLANGroupScope mixin. (#75)
• extensions/location_minimal hierarchy — Country → Metro → Site → Rack to Region → Country → Site; Site.facility_id → facility. (#75)
• DcimCircuit.circuit_type choices — upstream replaced by internet_access, point_to_point added. (#75)
• DcimCircuitEndpoint.name — now a computed attribute (circuit ID + side), replacing free text. (#75)
• VRRPGroup.group → vrid (Text to Number); VRRPGroup.ip_address → ip_addresses. (#75)
• hosting_cluster's cluster_type → technology; cloud-specific choices (aws, gcp) replaced by public_cloud. (#75)
• BGPSession.session_type, SNMP community/client enums — Text+enum to Dropdown, values changed to lowercase/snake_case. (#75)
• extensions/firewall_policer moved to experimental/firewall_policer. (#75)
• extensions/topology schema removed (superseded by experimental/topology). (#75)
• LocationGeneric/LocationHosting — shortname removed; human_friendly_id switches to name. (#75)
• IpamPrefix — organization, location, gateway relationships removed in favor of the new scope relationship (IpamPrefixScope); role choices fully replaced ({loopback, management, public, server, supernet, technical, loopback-vtep} → {management, link, customer, supernet, backbone}). (#75)

Fixed

• DcimCircuit.enpoints → endpoints typo. (#75)
• DcimInterface.role cust → customer typo/abbreviation. (#75)
• RoutingBGPSession routing-policy relationships retyped to RoutingPolicyBGP with distinct identifiers, no longer colliding with RoutingBGPPeerGroup's. (#75)
• IpamIPAddress.interface / InterfaceLayer3.ip_addresses given a matching identifier so both sides resolve as one relationship. (#75)

[cloudflare-workers-and-pages]

Deploying schema-library with    Cloudflare Pages

Latest commit:	893be13
Status:	✅  Deploy successful!
Preview URL:	https://2cf805ce.schema-library.pages.dev
Branch Preview URL:	https://bgi-schema-library-v2.schema-library.pages.dev

View logs