Composition

A design can include two kinds of thing it doesn't define itself:

nbd: designs

devices:
- design: nbd:devices/Cisco_9300_24
  template_vars:
    name: SW-01
    site: '{{ parent.site }}'

• An item with design: includes the named design's objects where the item is. template_vars sets its variables: see Variables.
• The name after nbd: must match a catalogue name exactly, case included. So that a reference typed in the wrong case can't name a different design, the catalogue refuses a name that differs only in case from one it already holds.
• nbd:<name> includes the catalogue's current version of the design. nbd:<name>@<version> pins one: a version label such as @1.2.0, or a content hash or the first seven or more characters of one, as shown on the design's page. A pinned design renders the same way whenever you plan it, whatever is pushed under that name later; an unpinned one follows the catalogue, and each plan records which version it used.
• Every design a design includes must be in the catalogue before it. Adding one whose nbd: designs are missing is refused, naming them, and so is one that pins a version the design hasn't got.
• A design that other designs include can't be deleted while they do. A version that other designs are pinned to can't be removed or relabelled while they are.

dtl: types

device_type, module_type and rack_type can name a file in the NetBox Device Type Library:

device_type: 'dtl:device-types/Cisco/C9300-24T.yaml@fdf12828'

• The path is the file's path in the library.
• The @ suffix, a commit (@fdf12828) or a tag (@v2.0.0), is required. A design renders the same way whenever you plan it, whatever changes in the library later.
• The type brings in its manufacturer, and the components the library defines for it: a device type's interfaces, console ports, console server ports, power ports, power outlets, front and rear ports, device bays and module bays; a module type's interfaces. A power outlet is fed from the power port the file names, and a cable can end on any of the ports.
• Its values arrive as NetBox would store them, so they're never refused at render.

Some of what the library can define isn't brought in yet, among it the mapping of a front port to its rear port: see Limitations.

Types by URL

device_type, module_type and rack_type can also name a type's YAML file by https:// URL, for a library of your own in the Device Type Library's format. The URL's path must name a revision that can't change: a commit hash, or a tag (/refs/tags/v1.2/, or the tag itself as the ref segment of a GitHub raw URL). A URL on a branch such as main is refused when the design is saved, as an unpinned dtl: reference is, because the type it points at could change under every design that uses it. The design's dependency tree lists each such type with its revision, linking to the URL.