Dot Notation vs Bracket Notation in Ansible and Jinja

Problem

Both dot notation and bracket notation are valid in Ansible and Jinja expressions. Without a clear rule, codebases drift into a mixture of styles such as item.name, item['groups'], and item[var_name].

This inconsistency makes code harder to scan and review. It also creates noise in examples and documentation, because readers have to infer whether the change in syntax is meaningful or merely stylistic.

Context

The Ansible documentation commonly uses dot notation in examples, such as item.name, item.groups, item.key, and item.value.role.

Jinja supports both foo.bar and foo['bar']. However, bracket notation is more flexible because it also supports dynamic keys such as foo[var_name].

In current C2 Platform Ansible code, bracket notation is used in many places and is effectively the existing house style. This guideline defines the preferred future direction: use dot notation by default for fixed keys, while recognizing that existing code is still largely standardized on bracket notation.

Solution

1. Prefer dot notation for fixed keys.
2. Use bracket notation only when dot notation cannot express the lookup safely or correctly.
3. Use bracket notation for dynamic keys, for example item[var_name].
4. Avoid mixing dot and bracket notation in the same task or file without a clear reason.
5. When editing existing C2 Platform code, prioritize local consistency unless you are intentionally refactoring a broader block to the new preferred style.

Benefits

• Aligns new code more closely with common Ansible examples.
• Makes expressions easier to type because dot notation uses fewer and simpler keystrokes than bracket notation.
• Fits the C2 Platform lazy naming convention , which prefers easier typing over unnecessary complexity.
• Preserves bracket notation for the cases where it is genuinely needed.

Alternatives (Optional)

Using bracket notation everywhere is valid and matches much of the current C2 Platform codebase, but it is more verbose and should not remain the preferred style for new code.

Examples and Implementation

Prefer dot notation for fixed keys

- name: Configure Apache vhost
  ansible.builtin.debug:
    msg: "{{ item.servername }} -> {{ item.documentroot }}"
  loop: "{{ apache_vhosts }}"

For fixed keys, dot notation is shorter and easier to scan.

Use bracket notation for dynamic keys

- name: Show selected vhost field
  ansible.builtin.debug:
    msg: "{{ item[field_name] }}"
  loop: "{{ apache_vhosts }}"

Here bracket notation is required because the key is stored in field_name.

Avoid mixing styles without a reason

- name: Avoid mixed notation
  ansible.builtin.debug:
    msg: "{{ item.servername }} -> {{ item['documentroot'] }}"
  loop: "{{ apache_vhosts }}"

This style is valid but not recommended. Use one style consistently unless the expression requires bracket notation.

Additional Information

• Keep Variable and Identifier Names Short and Consistent: Prefer short, consistent names that reduce noise without making variables or identifiers unclear.
• Loops — Ansible Community Documentation 
• Using variables — Ansible Community Documentation 
• Variables — Jinja Template Designer Documentation