From 6d6d4c102bf5058109e779f9aa12540aab0f3c80 Mon Sep 17 00:00:00 2001 From: Matt Vitale Date: Wed, 26 Nov 2025 08:55:23 -0500 Subject: [PATCH 1/5] Add additional data model variables --- docs/dev/data_model.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/dev/data_model.md b/docs/dev/data_model.md index 768c33c76a..51525b5042 100644 --- a/docs/dev/data_model.md +++ b/docs/dev/data_model.md @@ -20,6 +20,10 @@ Example: Imagine the extra programming logic needed to consume structured data w | Capture Group | Usage Description | |----------------------------------|:------------------| +| `ACCESS_GROUP_IN` | access group for IPv4 addresses, inbound | +| `ACCESS_GROUP_OUT` | access group for IPv4 addresses, outbound | +| `ACCESS_GROUP_V6_IN` | access group for IPv6 addresses, inbound | +| `ACCESS_GROUP_V6_OUT` | access group for IPv6 addresses, outbound | | `BIA` | use this if the template already has MAC_ADDRESS in use for the active MAC address | | `BUNDLE_NAME` | virtual interface name for etherchannel, LACP, LAG, or port-channel interfaces | | `BUNDLE_PROTOCOL` | virtual interface protocol type (LACP, PAgP) for etherchannel or port-channel interfaces | @@ -30,6 +34,8 @@ Example: Imagine the extra programming logic needed to consume structured data w | `CHASSIS_ID` | often represents CDP or LLDP neighbor chassis ID | | `DESCRIPTION` | often used for port or interface descriptions | | `GATEWAY` | gateway address for a subnet | +| `INNER_VLAN`. | numeric VLAN identifier; used instead of VLAN, VLANID, or TAG | +| `INNER_VLAN_NAME` | VLAN name or description | | `INTERFACE` | full word instead of IFACE, INTF, INTFC, etc | | `IP_ADDRESS` | for a single IP address, often IPv4 | | `IP_ADDRESSES` | for lists of IPv4 addresses, but in the case of some templates there may be a mix of IP protocol versions | @@ -51,7 +57,10 @@ Example: Imagine the extra programming logic needed to consume structured data w | `NEIGHBOR_INTERFACE_DESCRIPTION` | represents CDP or LLDP neighbor (remote host) interface or port descriptions (Note: see NEIGHBOR_INTERFACE) | | `NEIGHBOR_NAME` | often represents neighbor name for CDP or LLDP | | `NETMASK` | for IPv4 dotted quad masks | +| `NETMASKS` | list of IPv4 dotted quad masks | | `NETWORK` | for network numbers or subnet address (without the mask or prefix/slash notation); in place of ROUTE | +| `OUTER_VLAN`. | numeric VLAN identifier; used instead of VLAN, VLANID, or TAG | +| `OUTER_VLAN_NAME` | VLAN name or description | | `PID` | represents Part IDs (PIDs), Stock Keeping Units (SKUs), and in some cases Models or Model Numbers | `PLATFORM` | often represents CDP or LLDP neighbor's platform or model name/number | | `PREFIX_LENGTH` | instead of PREFIX or CIDR for the numbers of a slash notation or CIDR mask | From 8324aab024a6d8885fab1e509f95bc1813f0bc37 Mon Sep 17 00:00:00 2001 From: Matt Vitale Date: Wed, 26 Nov 2025 08:56:18 -0500 Subject: [PATCH 2/5] YAML formatting cleanup --- docs/dev/data_model.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/dev/data_model.md b/docs/dev/data_model.md index 51525b5042..af1311fc35 100644 --- a/docs/dev/data_model.md +++ b/docs/dev/data_model.md @@ -1,22 +1,24 @@ -# Goals +# Data Model: Common Capture Groups + +## Goals - The table below becomes an evolving reference of common capture group names - Normalize common capture groups across templates (including cross-vendor) -# Reasoning +## Reasoning Normalized capture group names enable more predictable structured data across templates where similar data exists. Example: Imagine the extra programming logic needed to consume structured data when capture groups could have two or more names across several templates or several vendors! Yikes! This is why we seek to normalize. -# Considerations +## Considerations - Some capture groups are a single value and others are lists of values despite containing similar data as one another - - Example: single IP address vs list of IP addresses + - Example: single IP address vs list of IP addresses - Normalizing and using standard capture group names will take time, persistence, and patience from the community - Other than new templates, these normalization changes modify the expected template output and are considered "breaking changes" to be included in version releases -# Common Capture Groups +## Common Capture Groups | Capture Group | Usage Description | |----------------------------------|:------------------| From c4a16414d7683a37942a84a2b6bddf974c241251 Mon Sep 17 00:00:00 2001 From: matt852 Date: Fri, 12 Dec 2025 10:33:07 -0500 Subject: [PATCH 3/5] Update docs/dev/data_model.md Co-authored-by: Michael Bear <38406045+mjbear@users.noreply.github.com> --- docs/dev/data_model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/data_model.md b/docs/dev/data_model.md index af1311fc35..c48c649182 100644 --- a/docs/dev/data_model.md +++ b/docs/dev/data_model.md @@ -61,7 +61,7 @@ Example: Imagine the extra programming logic needed to consume structured data w | `NETMASK` | for IPv4 dotted quad masks | | `NETMASKS` | list of IPv4 dotted quad masks | | `NETWORK` | for network numbers or subnet address (without the mask or prefix/slash notation); in place of ROUTE | -| `OUTER_VLAN`. | numeric VLAN identifier; used instead of VLAN, VLANID, or TAG | +| `OUTER_VLAN` | numeric VLAN identifier; used instead of VLAN, VLANID, or TAG | | `OUTER_VLAN_NAME` | VLAN name or description | | `PID` | represents Part IDs (PIDs), Stock Keeping Units (SKUs), and in some cases Models or Model Numbers | `PLATFORM` | often represents CDP or LLDP neighbor's platform or model name/number | From cd626abb51a1eabb55513b889b902efc056299c5 Mon Sep 17 00:00:00 2001 From: matt852 Date: Fri, 12 Dec 2025 10:33:13 -0500 Subject: [PATCH 4/5] Update docs/dev/data_model.md Co-authored-by: Michael Bear <38406045+mjbear@users.noreply.github.com> --- docs/dev/data_model.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/dev/data_model.md b/docs/dev/data_model.md index c48c649182..53702f4a80 100644 --- a/docs/dev/data_model.md +++ b/docs/dev/data_model.md @@ -22,10 +22,10 @@ Example: Imagine the extra programming logic needed to consume structured data w | Capture Group | Usage Description | |----------------------------------|:------------------| -| `ACCESS_GROUP_IN` | access group for IPv4 addresses, inbound | -| `ACCESS_GROUP_OUT` | access group for IPv4 addresses, outbound | -| `ACCESS_GROUP_V6_IN` | access group for IPv6 addresses, inbound | -| `ACCESS_GROUP_V6_OUT` | access group for IPv6 addresses, outbound | +| `ACCESS_GROUP_IN` | inbound access group for IPv4 addresses | +| `ACCESS_GROUP_OUT` | outbound access group for IPv4 addresses | +| `ACCESS_GROUP_V6_IN` | inbound access group for IPv6 addresses | +| `ACCESS_GROUP_V6_OUT` | outbound access group for IPv6 addresses | | `BIA` | use this if the template already has MAC_ADDRESS in use for the active MAC address | | `BUNDLE_NAME` | virtual interface name for etherchannel, LACP, LAG, or port-channel interfaces | | `BUNDLE_PROTOCOL` | virtual interface protocol type (LACP, PAgP) for etherchannel or port-channel interfaces | From 8bd321a2fee22d4ac88620de18e70dd5f1a1e7d6 Mon Sep 17 00:00:00 2001 From: matt852 Date: Fri, 12 Dec 2025 10:33:18 -0500 Subject: [PATCH 5/5] Update docs/dev/data_model.md Co-authored-by: Michael Bear <38406045+mjbear@users.noreply.github.com> --- docs/dev/data_model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/data_model.md b/docs/dev/data_model.md index 53702f4a80..694c3b0cfe 100644 --- a/docs/dev/data_model.md +++ b/docs/dev/data_model.md @@ -36,7 +36,7 @@ Example: Imagine the extra programming logic needed to consume structured data w | `CHASSIS_ID` | often represents CDP or LLDP neighbor chassis ID | | `DESCRIPTION` | often used for port or interface descriptions | | `GATEWAY` | gateway address for a subnet | -| `INNER_VLAN`. | numeric VLAN identifier; used instead of VLAN, VLANID, or TAG | +| `INNER_VLAN` | numeric VLAN identifier; used instead of VLAN, VLANID, or TAG | | `INNER_VLAN_NAME` | VLAN name or description | | `INTERFACE` | full word instead of IFACE, INTF, INTFC, etc | | `IP_ADDRESS` | for a single IP address, often IPv4 |