Ansible/scripts/docs/INVENTORY_HIERARCHY.md

AIM inventory hierarchy discovery

AIM 3.3.0rc8 / service API 1.0. inventory_hierarchy_v1 is a read-only, additive discovery capability. It exists so interfaces can present AIM's actual inventory group/subgroup structure without duplicating Ansible-inventory parsing.

Public operation

Python:

result = AimService().inventory_hierarchy('CUSTOMER')

Machine interface:

printf '%s\n' '{"api_version":"1.0","operation":"inventory_hierarchy","customer":"CUSTOMER"}' | aimctl request

Query capabilities.inventory_hierarchy before relying on this operation.

The result has this shape:

{
  "api_version": "1.0",
  "schema": "inventory_hierarchy_v1",
  "customer": "CUSTOMER",
  "hosts": ["direct-customer-host.example"],
  "groups": [
    {
      "name": "windows",
      "path": ["windows"],
      "hosts": ["win01.example"],
      "children": [
        {
          "name": "servers",
          "path": ["windows", "servers"],
          "hosts": ["win02.example"],
          "children": []
        }
      ]
    }
  ]
}

hosts on each node means direct membership in that node, not recursively expanded membership. A client can render descendants without guessing whether a host came from the parent or a subgroup. Group nesting is preserved to a bounded 64 levels / 10,000 group nodes; malformed mappings, aliases/cycles or larger structures fail as invalid source rather than being silently flattened.

Safety and execution boundary

Only customer/group names, group paths and inventory host names are returned. Variables, addresses, credentials, Vault values, connection settings and group vars are not part of this tree. list_hosts remains the flat host/address/platform metadata operation.

The hierarchy is presentation/discovery metadata only. It does not add group patterns to RunRequest, change --limit, authorize targets, or skip preparation and review. Execution still accepts explicit host names and Core revalidates them against current inventory/catalog compatibility.

Interfaces should not persist a competing hierarchy or derive execution authority from a previously fetched tree. Fetch current hierarchy when presenting inventory, then prepare the final explicit host request through Core.