Meaning of _top dictionary and intended usage.

[DanPartelly]

What is the meaning of _top dictionary in *.yml data models ? Ive seen it used to augment foreign data , for example add specific STP data to a node_vlan type. Like here:

https://github.com/ipspace/netlab/blob/dev/netsim/modules/stp.yml#L42

Is there anything else to it ? Any gotchas ?

[ipspace]

• The system defaults are collected from a large number of files that are included into the topology-defaults.yml: https://github.com/ipspace/netlab/blob/dev/netsim/topology-defaults.yml
• Data from those included files is placed "somewhere" within the defaults tree based on the file name like the modules:

  netlab/netsim/topology-defaults.yml

  Line 19 in 5281e81

  - modules/*.yml

  or the file name and the parent key(s) like the devices:

  netlab/netsim/topology-defaults.yml

  Line 29 in 5281e81

  devices:

• That makes it impossible (for example) for the stp.yml file to set anything outside of the defaults.stp dictionary

However, we might need that (as you discovered), so we need an option to say "although most of the stuff goes into its expected place, these things really should go to the top of the defaults dictionary", thus the _top key. It literally means "insert the value of this key into defaults dictionary". It's a bit more complex as we have to merge individual keys -- see

netlab/netsim/utils/read.py

Line 66 in 5281e81

if '_top' in yaml_data: # Do we have to modify parent defaults outside of include scope?

for details -- but that's the gist of it.

As for gotchas: anyone can change anything anywhere in the defaults settings (and there are subtle things like "you cannot merge scalars or lists, only dicts"), so we have to be a bit careful while merging PRs.

[DanPartelly]

@ipspace Thanks a lot for this detailed answer!