We have to distinct but closely related issues in the current op mode definitions:
- There are cases when a normal node coexists with a tag node at the same level, like in clear interfaces.
- We have commands where variably-named "tags" coexist with keywords at the same level, like in show interfaces ethernet detail (keyword) and show interfaces ethernet eth0.
The first problem makes it very difficult to produce a machine-readable JSON cache for generating documentation and implementing a new command lookup algorithm, since there can be two nodes at the same level with the same name but different semantics. A lookup algorithm needs to fish out nodes with the same names and try to find out which one it needs to use.
Worse yet, without an invariant like "every node name at the same level must be unique", there is no way to prevent accidental redefinition of an existing node in the same file — a possible failure mode for a distracted developer editing a long file.
The second problem has two effects.
First, it also complicates the definition structure and requires normal nodes to coexist with tag nodes, and sometimes (like in clear interfaces) even demands that the normal node and the tag node need to have children with the same names, to implement commands like clear interfaces ethernet counters and clear interfaces ethernet eth0 counters.
Second, it's problematic for commands where argument names can be completely arbitrary. The only reason why show interfaces ethernet detail can exist is that Ethernet interfaces cannot be named detail. For entities like IPsec or BGP peers that don't have any constraints on their names (including brief, detail, and JSON), that paradigm breaks down.
If we want to implement a new operational mode command lookup method and generate documentation from definitions, we need to address both problems and ensure that all names at the same level are unique and that every command word is either a keyword from a fixed set or an arbitrary name, but never both.