6 Group model

6.0 Overview

Groups in OSIRIS provide a mechanism to organize and classify resources into meaningful collections without altering the underlying topology graph. Groups are primarily used for:

• Aggregation: Collecting resources by shared attributes (e.g. “all production workloads”, “all devices in on-premise Data Center DC-MXP”, “all resources owned by Software Development Team”)
• Presentation and navigation: Building hierarchical trees, filtered views and organized inventories
• Boundary modeling: Representing organizational, physical, logical, network or security boundaries

Groups complement resources (nodes) and connections (edges) by providing structure and categorization. Groups do not create topological edges; they provide categorization and hierarchical organization. While connections represent explicit relationships between individual resources, groups provide organizational context and multi-dimensional classification.

This chapter defines:

• Group object structure and required fields
• Standard group types and their semantics
• Membership models including hierarchical nesting
• When to use groups versus contains connections
• Group metadata via properties, extensions, tags and status/state

6.1 Group object structure

6.1.1 Overview

A group is a JSON object stored in the topology.groups array (see chapter 3, section 3.4). A group may reference:

• Resources via the members array
• Other groups via the children array (hierarchical nesting)

Groups enable multi-dimensional classification where a single resource can belong to multiple groups simultaneously (e.g. a VM can be in both “production environment” and “web tier” groups).

6.1.2 Required fields

Every group MUST include:

• id (string): Unique identifier for this group within the document
• type (string): Group type using dot notation (see section 6.2)

ID Construction:

Group identifiers are document-scoped: they MUST be unique within a single OSIRIS document but need not be globally unique across other documents or systems.

Groups do not have vendor-assigned “native IDs” since they represent logical or physical collections defined by parsers or infrastructure operators. Producers SHOULD construct group IDs using one of these strategies:

1. Sequential numbering:

{
   "id": "group-001",
   "id": "group-002"
}

2. Descriptive naming (recommended):

{
   "id": "group-aws-vpc-production",
   "id": "group-mxp-datacenter",
   "id": "group-web-tier",
   "id": "group-kubernetes-prod-cluster"
}

3. Type-prefixed descriptive:

{
   "id": "environment-production",
   "id": "datacenter-mxp",
   "id": "vnet-azure-prod"
}

4. Hash-based (for reproducibility):

{
   "id": "group-a1b2c3d4e5f6"
}

5. UUID (for guaranteed uniqueness on large infrastructures):

{
   "id": "550e8400-e29b-41d4-a716-446655440000"
}

Descriptive naming (strategies 2-3) is RECOMMENDED as it improves human readability and debugging while maintaining uniqueness within the document scope.

[!NOTE] Unlike resource IDs which use provider::native-id format to reference vendor systems, group IDs do not require namespace prefixes since groups represent logical or physical collections rather than vendor-managed objects.

6.1.3 Optional fields

Groups MAY include:

• name (string): Human-readable label for the group
• description (string): Free-text description of the group’s purpose or contents
• members (array of strings): Resource IDs that belong to this group (see section 6.3.1)
• children (array of strings): Group IDs nested under this group (see section 6.3.3)
• status (string): Normalized operational status (active|inactive|degraded|retired|unknown)
• state (string): Vendor-specific granular state
• properties (object): Portable group attributes
• extensions (object): Vendor-specific metadata using osiris.<namespace> keys
• tags (object): Key-value labels (string > string)

6.1.4 Minimal group example

Logical environment grouping:

{
  "id": "group-aws-production-web-app",
  "type": "logical.environment",
  "name": "Production environment",
  "members": [
    "aws::i-0abc123def4567890",
    "aws::db-prod-postgres-01",
    "aws::vpc-0abc123"
  ]
}

Additional examples:

Physical datacenter grouping:

{
  "id": "group-mxp-datacenter",
  "type": "physical.datacenter",
  "name": "Milan Datacenter",
  "members": [
    "arista::MXP-SW-LEAF-01",
    "arista::MXP-SW-SPINE-01",
    "dell::MXP-SRV-042"
  ]
}

Hyperscaler (AWS) Network VPC grouping:

{
  "id": "group-aws-vpc-prod",
  "type": "network.vpc",
  "name": "Production VPC",
  "members": [
    "aws::vpc-0abc123",
    "aws::subnet-0abc123",
    "aws::i-0abc123def4567890"
  ]
}

6.1.5 Referential integrity

Each entry in members MUST reference a resource ID present in topology.resources. Each entry in children MUST reference a group ID present in topology.groups.

A group MUST NOT:

• List itself in children (direct self-reference)
• Create cycles in the group hierarchy (indirect self-reference through descendants)

Producers SHOULD validate referential integrity and cycle detection before export.

Consumers MUST handle invalid references gracefully by:

• Emitting warnings for broken references
• Skipping invalid members or children entries
• Rejecting the document in strict validation mode (optional)

6.1.6 Group identity and stability

Group IDs MUST be unique within the document. Group IDs SHOULD remain stable across exports when feasible to enable:

• Change detection when comparing snapshots
• Correlation across multiple topology exports
• Reliable external references from consuming systems

Producers MAY use deterministic ID generation based on:

• Group type
• Group name
• Stable contextual identifiers (e.g. datacenter code, environment name, VPC ID)

Example deterministic ID patterns:

• On-prem site: grp-<site_code> (e.g. grp-MXP)

• Physical datacenter: grp-MXP (datacenter code)

• Physical rack: grp-MXP-F1-R01 (datacenter-floor-rack)

• Logical environment: grp-prod or grp-env-production

• Hyperscalers and Cloud provider network groups: grp-<provider.name>-net-<id>

  • AWS VPC: grp-aws-net-vpc-0abc123def4567890
  • Azure VNet: grp-az-net-vnet-prod-weu-01
  • GCP VPC: grp-gcp-net-vpc-prod-eu-01
  • DigitalOcean VPC: grp-digitalocean-net-vpc-<uuid>
  • Leaseweb Private Network: grp-leaseweb-net-private-<id>

[!NOTE] Providers use different names for private networking constructs (e.g. VPC/VNet/Networks/Private Network). OSIRIS treats these uniformly as “Hyperscalers and Cloud provider network groups”; the concrete provider object IDs remain provider-specific.

[!NOTE] Some producers embed a short provider code in deterministic IDs for readability (e.g. grp-aws-net-...). OSIRIS does not require this. If used, the provider code SHOULD match provider.name where applicable.

Recommended provider codes (non-normative):

• aws (Amazon Web Services)
• az (Microsoft Azure)
• cloudflare (Cloudflare)
• gcp (Google Cloud Platform)
• oci (Oracle Cloud Infrastructure)
• ibm (IBM Cloud)
• tc (Tencent Cloud)
• ali (Alibaba Cloud)

Producers MAY use additional provider codes as needed. Consumers MUST NOT treat this list as exhaustive and MUST accept unknown provider codes.

6.1.7 Field extensibility

Consumers MUST accept groups with unrecognized fields for forward compatibility.

Producers SHOULD place non-standard data under properties or extensions rather than introducing new top-level fields in OSIRIS v1.0.

6.2 Group types

6.2.1 Overview

The type field classifies what the group represents and how it should be interpreted by consumers. Group types use hierarchical dot notation to organize categories and subcategories.

6.2.2 Type format rules

Group type values:

• MUST NOT contain whitespace
• MUST be lowercase
• MUST use dot (.) as the segment separator
• MUST contain at least two segments
• MUST NOT start or end with a dot
• MUST NOT contain consecutive dots (..)

Examples of valid group types:

• logical.environment
• physical.datacenter
• network.vpc
• security.zone
• org.team

Examples of invalid group types:

• Environment (uppercase)
• datacenter (single segment)
• data center (space)
• .datacenter (starts with dot)
• network..vpc (consecutive dots)

6.2.3 Standard group types

OSIRIS defines the following standard group type families. Producers SHOULD use these standard types when applicable rather than creating custom types for common infrastructure concepts.

logical.*

Purpose: Conceptual groupings that reflect application architecture, deployment organization or operational intent.

Recommended types:

• logical.environment: Deployment environments (e.g. production, staging, development, QA)
• logical.application: Application or system groupings (e.g. billing-system, crm, identity-platform)
• logical.service: Individual services or microservices (e.g. api-gateway, auth-service, payments-processor)
• logical.tier: Architectural tiers (e.g. web, application, database, cache)
• logical.workload: Workload classifications (e.g. batch-processing, real-time, analytics)

Example use cases:

• Grouping all production resources for filtering and access control
• Organizing resources by application for cost allocation
• Separating frontend, backend and database tiers in diagrams

physical.*

Purpose: Location-based and facility-based grouping reflecting physical infrastructure organization.

Recommended types:

• physical.datacenter: Data center facilities
• physical.building: Buildings within a campus or multi-building facility
• physical.floor: Floors within a building
• physical.room: Rooms or caged areas
• physical.rack: Equipment racks
• physical.pod: Modular datacenter pods or availability zones

Example use cases:

• Modeling datacenter physical topology
• Organizing resources by geographic location
• Planning capacity and power distribution by rack

network.*

Purpose: Network segmentation and network construct organization.

Recommended types:

• network.vpc or network.vnet: Virtual private clouds or virtual networks
• network.subnet: Network subnets or segments
• network.vlan: VLAN groupings
• network.segment: Generic network segments or security zones
• network.asn: Autonomous System Number groupings (for BGP topology)

[!NOTE] Provider-specific terminology (e.g. AWS VPC vs Azure VNet) can be expressed as:

• Standard type network.vpc with provider details in properties or extensions (recommended)
• Namespaced type osiris.aws.vpc or osiris.azure.vnet (when provider-specific semantics are required)

Common properties for network.asn groups: When using network.asn groups, producers SHOULD include these properties when available:

• asn_number (integer): The AS number (e.g. 3356)
• organization_name (string): Legal name of the ASN organization
• domain (string): Organization’s domain name
• asn_type (string): ASN classification (ISP, Hosting, Education, Government, Business)
• country_code (string): ISO 3166-1 alpha-2 country code from WHOIS records
• registry (string): Regional Internet Registry (ARIN, RIPE, APNIC, LACNIC, AFRINIC)
• cidr_blocks (array of strings): CIDR blocks announced by this ASN
• peering_policy (string): BGP peering policy (open, selective, restrictive, no)

Example use cases:

• Organizing resources by network boundary
• Modeling network segmentation for security analysis
• Grouping resources within the same broadcast domain
• Documenting BGP topology and AS path relationships

security.*

Purpose: Security boundaries, trust zones and compliance groupings.

Recommended types:

• security.zone: Security or trust zones (e.g. DMZ, trusted, untrusted, quarantine)
• security.trust.boundary: Trust domain boundaries
• security.compliance.scope: Compliance boundary groupings (e.g. PCI-DSS scope, HIPAA scope)

Example use cases:

• Modeling zero-trust network architecture
• Documenting compliance boundaries for audit
• Visualizing security zone transitions

org.*

Purpose: Organizational ownership, responsibility and business structure groupings.

Recommended types:

• org.team: Team ownership (e.g. platform-team, sme-team, security-team)
• org.owner: Individual or group ownership
• org.costcenter: Financial cost center allocations
• org.bu: Business unit or department groupings
• org.dept: Business unit or department groupings
• org.project: Project-based groupings

Example use cases:

• Allocating infrastructure costs by team or cost center
• Identifying ownership for incident response
• Organizing resources by business unit for governance

6.2.4 Vendor-specific and custom group types

Vendor-specific or organization-specific group types SHOULD use the namespaced pattern:

osiris.<namespace>.<type>

Examples:

• osiris.aws.account (AWS account boundary)
• osiris.azure.subscription (Azure subscription)
• osiris.gcp.project (GCP project)
• osiris.kubernetes.namespace (Kubernetes namespace)
• osiris.vmware.cluster (VMware vSphere cluster)
• osiris.com.acme.product.line (organization-specific product grouping)

Namespace selection guidance:

• Well-known vendors MAY use simple namespaces (e.g. osiris.aws, osiris.arista)
• Organizations SHOULD use stable identifiers such as reverse domain notation without hyphens, underscores or spaces (e.g. osiris.com.acme, osiris.org.example)

6.2.5 Unknown group types

Consumers MUST accept groups with unknown or unrecognized types. When encountering unknown group types, consumers SHOULD:

• Preserve the group object when re-exporting or transforming documents
• Display the type string verbatim for debugging and manual interpretation
• Allow normal membership resolution and hierarchy traversal
• Treat the group as a generic collection for filtering and presentation

Consumers MUST NOT reject documents containing unknown group types.

6.3 Membership

6.3.1 Members array

The members field is an array of resource IDs:

"members": [
  "aws::i-0abc123def4567890",
  "aws::db-prod-postgres-01",
  "aws::lb-prod-web-001"
]

All member IDs MUST reference valid resource IDs defined elsewhere in the document. Member IDs SHOULD use the same format as resource IDs (typically provider::native-id for resources from vendor systems).

Example in context:

{
  "id": "group-aws-production-web-app",
  "type": "logical.application",
  "name": "Production Web APP Lollipop of Acme Corp",
  "members": [
    "aws::i-0abc123def4567890",
    "aws::i-0def456ghi7890ab",
    "aws::lb-prod-web-001",
    "aws::db-prod-postgres-01"
  ],
  "properties": {
    "tier": "web",
    "availability_zones": ["us-east-1a", "us-east-1b"]
  }
}

Rules:

• members entries MUST be strings
• Each entry MUST reference a valid resource ID from topology.resources
• Producers SHOULD avoid duplicate entries
• Consumers SHOULD treat duplicate entries as a single membership
• Order of the members array MUST NOT be considered semantically meaningful
• Empty members array is valid (group may have children but no direct members)
• Omitting members field is equivalent to an empty array

Membership semantics: Resources listed in members are considered direct members of the group. Membership does not imply any particular relationship between resources within the group (e.g. resources in the same group are not automatically connected).

6.3.2 Multiple memberships

A resource MAY belong to multiple groups simultaneously. This is expected and recommended for multi-dimensional classification.

Example: Multi-dimensional membership

Resource aws::i-0abc123def4567890 can simultaneously belong to:

• group-aws-production-web-app (logical.environment)
• group-web-tier (logical.tier)
• group-billing-application (logical.application)
• group-team-software-development (org.team)
• group-mxp-rack-r01 (physical.rack)

This enables flexible filtering and navigation:

• “Show all production resources” > Filter by group-aws-production-web-app
• “Show all web tier resources” > Filter by group-web-tier
• “Show all resources owned by software development team” > Filter by group-team-software-development
• “Show all resources in rack R01” > Filter by group-mxp-rack-r01

Complete example:

{
  "resources": [
    {
      "id": "aws::i-0abc123def4567890",
      "type": "compute.vm",
      "name": "billing-api-prod-01",
      "description": "Primary EC2 instance hosting the Billing API (production). Serves internal billing requests and exposes HTTPS endpoints behind an Application Load Balancer.",
      "provider": {
        "name": "aws",
        "type": "AWS::EC2::Instance",
        "native_id": "i-0abc123def4567890",
        "region": "us-east-1",
        "account": "123456789012",
        "zone": "us-east-1a"
      },
      "status": "active",
      "state": "running",
      "properties": {
        "instance_type": "t3.large",
        "platform": "linux",
        "private_ip": "10.10.1.10",
        "public_ip": "203.0.113.10",
        "vpc_id": "vpc-hybrid-001",
        "subnet_id": "subnet-prod-web-a"
      },
      "tags": {
        "environment": "production",
        "location": "cloud",
        "tier": "web",
        "application": "billing",
        "managed_by": "terraform"
      }
    },
    {
      "id": "aws::i-0def4567890abc1234",
      "type": "compute.vm",
      "name": "billing-api-prod-02",
      "description": "Secondary EC2 instance hosting the Billing API (production). Used for horizontal scaling and high availability behind the load balancer.",
      "provider": {
        "name": "aws",
        "type": "AWS::EC2::Instance",
        "native_id": "i-0def4567890abc1234",
        "region": "us-east-1",
        "account": "123456789012",
        "zone": "us-east-1b"
      },
      "status": "active",
      "state": "running",
      "properties": {
        "instance_type": "t3.large",
        "platform": "linux",
        "private_ip": "10.10.2.10",
        "public_ip": "203.0.113.11",
        "vpc_id": "vpc-hybrid-001",
        "subnet_id": "subnet-prod-web-b"
      },
      "tags": {
        "environment": "production",
        "location": "cloud",
        "tier": "web",
        "application": "billing",
        "managed_by": "terraform"
      }
    }
  ],
  "groups": [
    {
      "id": "group-aws-production",
      "type": "logical.environment",
      "name": "Production Environment",
      "members": ["aws::i-0abc123def4567890", "aws::i-0def4567890abc1234"]
    },
    {
      "id": "group-web-tier",
      "type": "logical.tier",
      "name": "Web Tier",
      "members": ["aws::i-0abc123def4567890", "aws::i-0def4567890abc1234"]
    },
    {
      "id": "group-billing-application",
      "type": "logical.application",
      "name": "Billing Application",
      "members": ["aws::i-0abc123def4567890", "aws::i-0def4567890abc1234"]
    },
    {
      "id": "group-team-software-development",
      "type": "org.team",
      "name": "Software Development Team",
      "members": ["aws::i-0abc123def4567890", "aws::i-0def4567890abc1234"]
    },
    {
      "id": "group-aws-site-us-east-1",
      "type": "logical.site",
      "name": "AWS us-east-1",
      "members": ["aws::i-0abc123def4567890", "aws::i-0def4567890abc1234"]
    }
  ]
}

6.3.3 Children array (hierarchical nesting)

The children field is an array of group IDs that are nested under this group, enabling hierarchical organization:

"children": ["group-mxp-building-01", "group-mxp-building-02"]

Hierarchical nesting example:

Complete physical datacenter hierarchy:

{
  "groups": [
    {
      "id": "group-mxp-datacenter",
      "type": "physical.datacenter",
      "name": "Milan Datacenter",
      "children": [
        "group-mxp-building-01"
      ]
    },
    {
      "id": "group-mxp-building-01",
      "type": "physical.building",
      "name": "MXP Building 01",
      "children": [
        "group-mxp-floor-f1",
        "group-mxp-floor-f2"
      ]
    },
    {
      "id": "group-mxp-floor-f1",
      "type": "physical.floor",
      "name": "MXP Floor F1",
      "children": [
        "group-mxp-room-105",
        "group-mxp-room-106"
      ]
    },
    {
      "id": "group-mxp-room-105",
      "type": "physical.room",
      "name": "MXP Server Room 105",
      "children": [
        "group-mxp-rack-r01",
        "group-mxp-rack-r02"
      ]
    },
    {
      "id": "group-mxp-rack-r01",
      "type": "physical.rack",
      "name": "MXP Rack R01",
      "members": [
        "arista::MXP-SW-LEAF-01",
        "dell::MXP-SRV-042",
        "dell::MXP-SRV-043"
      ]
    }
  ]
}

Hierarchy visualization:

group-mxp-datacenter (physical.datacenter)
|   +-- group-mxp-building-01 (physical.building)
|       +-- group-mxp-floor-f1 (physical.floor)
|           +-- group-mxp-room-105 (physical.room)
|               +-- group-mxp-rack-r01 (physical.rack)
|                   +-- arista::MXP-SW-LEAF-01
|                   +-- dell::MXP-SRV-042
|                   +-- dell::MXP-SRV-043
|               +-- group-mxp-rack-r02 (physical.rack)
|                   +-- arista::MXP-SW-LEAF-02
|                   +-- dell::MXP-SRV-044
|           +-- group-mxp-room-106 (physical.room)
|               +-- group-mxp-rack-r03 (physical.rack)
|                   +-- arista::MXP-SW-SPINE-01
|       +-- group-mxp-floor-f2 (physical.floor)
|           +-- group-mxp-room-201 (physical.room)
|               +-- group-mxp-rack-f2-r01 (physical.rack)
|                   +-- dell::MXP-SRV-201

This hierarchical structure enables queries like:

• “Show all resources in datacenter MXP” > Traverse from group-mxp-datacenter
• “Show all resources on floor F1” > Traverse from group-mxp-floor-f1
• “Show all resources in rack R01” > Direct members of group-mxp-rack-r01

Rules:

• children entries MUST be strings
• Each entry MUST reference a valid group ID from topology.groups
• Producers SHOULD avoid duplicate entries
• Consumers SHOULD treat duplicate entries as a single child relationship
• Order of the children array MUST NOT be considered semantically meaningful
• Empty children array is valid (leaf groups with no subgroups)
• Omitting children field is equivalent to an empty array

6.3.4 Nesting semantics

Groups MAY form tree structures or directed acyclic graphs (DAGs):

• Tree: Each group has at most one parent
• DAG: Groups may have multiple parents (a rack might belong to both a physical room and a logical availability zone)

A group MAY appear as a child of multiple parent groups (DAG). Consumers computing transitive membership SHOULD deduplicate resource IDs in the resulting effective membership set.

Group nesting MUST NOT contain cycles (directly or indirectly). Producers MUST validate cycle-freedom before export.

Transitive membership: Consumers MAY compute “expanded membership” (transitive closure) when useful:

effective_members(group) = union of members(group) and members(all_descendant_groups)

This enables queries like “all resources in datacenter MXP” to include resources in nested rooms and racks.

Depth guidance: Producers SHOULD keep nesting depth reasonable for human comprehension:

• Typical datacenter: datacenter > floor > room > rack (4 levels)
• Typical cloud hierarchy (4–6 levels): tenant/account/project > region/zone > container/resource-group > network (VPC/VNet) > subnet
• Excessive depth (>6-7 levels) may reduce usability in visualization tools

6.4 Groups vs contains connections

Containment relationships can be represented either via groups or via contains connections (see chapter 5 section 5.2.3). Understanding when to use each mechanism is important for clear topology modeling.

6.4.1 Prefer groups when

Use groups when containment is primarily:

• A view or categorization (e.g. “all resources in VPC X”, “all production resources”)
• Multi-dimensional (resources belong to multiple “containers” such as team + environment + application)
• Not required as an explicit graph edge for dependency analysis or path traversal
• Organizational or logical rather than structural

Examples:

• “Production environment” > group
• “Platform team ownership” > group
• “Web tier” > group
• Resources in a VPC > group (usually)

6.4.2 Prefer contains connections when

Use contains connections when containment is:

• A strict structural relationship that must behave like a graph edge
• Used for topology traversals such as “what runs on what”, “what is physically inside what”
• A single-parent hierarchy where each resource has exactly one container
• Physical or architectural rather than organizational

Examples:

• “Chassis contains linecard” > connection
• “Host contains VMs” > connection
• “Kubernetes node contains pods” > connection
• “Rack contains servers” > connection (may also use groups for inventory)

6.4.3 Avoid duplication

Producers SHOULD avoid representing the same containment relationship in both groups and contains connections unless there is a clear consumer requirement for both representations.

If duplication is necessary (e.g. both graph-based and inventory-based consumers):

• Groups should be treated as the presentation layer (for filtering, navigation, reporting)
• contains connections should be treated as the authoritative graph edge (for topology analysis, dependency tracing)

Example: Hyperscaler or Cloud VPC containment Using groups (recommended for most VPC scenarios):

{
  "id": "grp-aws-net-vpc-0abc123def4567890",
  "type": "network.vpc",
  "name": "Production VPC",
  "members": ["subnet-aws-web-001", "subnet-aws-db-001", "aws::i-0abc123def4567890", "vm-aws-db-001"]
}

Using contains connections (if VPC is a topology node):

Resource:

{
  "id": "vpc-0abc123def4567890",
  "type": "network.vpc",
  "name": "Production VPC",
  "provider": {
    "name": "aws",
    "native_id": "vpc-0abc123def4567890",
    "region": "eu-west-1",
    "account": "123456789012"
  }
}

Connection:

{
  "id": "cn-vpc-0abc123def4567890-contains-subnet-web-001",
  "source": "vpc-0abc123def4567890",
  "target": "subnet-web-001",
  "type": "contains",
  "direction": "forward"
}

IDs shown are human-readable and derived from stable provider identifiers; hashing is optional and not required by OSIRIS. Choose based on consumer needs: groups for inventory/presentation, connections for topology traversal.

Example: Host contains VMs (on-prem virtualization) Using groups (recommended for inventory or reporting):

{
  "id": "grp-mxp-esxi-cluster-prod",
  "type": "logical.cluster",
  "name": "MXP Production ESXi Cluster",
  "members": ["host-mxp-f1-r22-esxi-001", "host-mxp-f1-r50-esxi-002", "vm-mxp-pr-web-001", "vm-mxp-pr-db-001"],
  "tags": {
    "site": "MXP",
    "environment": "prod",
    "org": "acme"
  }
}

Using contains connections (recommended when containment must be traversed as topology):

{
  "id": "host-mxp-f1-r22-esxi-001",
  "type": "compute.server",
  "name": "mxp-esxi-001",
  "provider": {
    "name": "vmware",
    "native_id": "host-mxp-12345",
    "version": "ESXi 8.0"
  }
}

{
  "id": "vm-mxp-pr-web-001",
  "type": "compute.vm",
  "name": "vm-mxp-pr-web-001",
  "provider": {
    "name": "vmware",
    "native_id": "vm-67890"
  }
}

{
  "id": "cn-host-mxp-f1-r22-esxi-001-contains-vm-mxp-pr-web-001",
  "source": "host-mxp-f1-r22-esxi-001",
  "target": "vm-mxp-pr-web-001",
  "type": "contains",
  "direction": "forward"
}

[!NOTE] Groups can classify VMs or pods by cluster, environment or ownership, while contains edges model the runtime placement relationship required for topology traversal (e.g. impact analysis).

6.5 Group metadata

Groups use the same metadata pattern as resources and connections:

• properties: Portable attributes specific to the group (e.g. capacity, quota, region_code, cost_center)
• extensions: Vendor/tool/org-specific metadata using osiris.<namespace> keys
• tags: Simple key-value labels (string > string)
• status: Normalized operational status (active|inactive|degraded|retired|unknown)
• state: Optional vendor-specific granular state

Common group properties (non-exhaustive):

• Capacity or quota information (e.g. max_members, allocated_capacity)
• Geographic or regional metadata (e.g. region, availability_zone, geo_location)
• Ownership or responsibility (e.g. owner_email, oncall_team, budget_code)
• Configuration (e.g. maintenance_window, backup_policy)

[!NOTE] properties SHOULD remain portable across producers. Vendor or platform-derived fields with non-portable semantics SHOULD be placed under extensions.osiris.<namespace>.

6.5.1 Examples

[!NOTE] Members vs children:

• members = Direct resource membership (flat set for inventory, filtering, reporting)
• children = Hierarchical nesting (tree/DAG structure for navigation and containment traversal) A group may have both members (leaf resources) and children (nested subgroups).

[!NOTE] Resource IDs: Resource and group IDs in these examples are producer-defined and may follow different conventions (human-readable names, provider native IDs, deterministic hashes). OSIRIS does not mandate a specific ID format; producers SHOULD prioritize stability and uniqueness within each document.

6.5.1.1 On-premise infrastructure groups

Physical datacenter hierarchy

{
  "id": "grp-MXP",
  "type": "physical.datacenter",
  "name": "Datacenter MXP",
  "description": "Primary datacenter facility of Acme Corp. located in Milan.",
  "children": ["grp-MXP-F1", "grp-MXP-F2"],
  "properties": {
    "total_racks": 120,
    "power_capacity_kw": 3200,
    "geo_location": {
      "latitude": null,
      "longitude": null
    }
  },
  "tags": {
    "site": "MXP",
    "tier": "tier-3",
    "region": "emea"
  }
}

[!NOTE] Geographic coordinates are optional and may be omitted for privacy or security considerations. If included, coordinates should use WGS84 decimal degrees format. Producers MAY apply precision reduction (e.g. rounding to 2-3 decimal places) or geographic jitter to avoid exposing exact facility locations while maintaining sufficient accuracy for regional grouping and visualization.

{
  "id": "grp-MXP-F1",
  "type": "physical.floor",
  "name": "Floor 1",
  "description": "Main floor housing production infrastructure",
  "children": ["grp-MXP-F1-R01", "grp-MXP-F1-R02", "grp-MXP-F1-R03"],
  "properties": {
    "floor_number": 1,
    "total_racks": 40
  }
}

{
  "id": "grp-MXP-F1-R01",
  "type": "physical.rack",
  "name": "Rack 01",
  "description": "Network fabric and compute rack",
  "members": ["MXP-F1-R01-SW-001", "MXP-F1-R01-SRV-042"],
  "properties": {
    "rack_units": 42,
    "power_capacity_watts": 5000,
    "cooling_type": "hot-aisle"
  },
  "tags": {
    "site": "MXP",
    "floor": "1",
    "row": "A"
  }
}

VMware vSphere cluster grouping

{
  "id": "grp-vmware-cluster-mxp-prod",
  "type": "compute.cluster",
  "name": "MXP Production Cluster",
  "description": "VMware vSphere production cluster in datacenter MXP",
  "members": [
    "MXP-F1-R01-SRV-042",
    "MXP-F1-R22-SRV-002",
    "MXP-F1-R50-SRV-003",
    "vm-mxp-pr-web-001",
    "vm-mxp-pr-db-001"
  ],
  "properties": {
    "cluster_name": "MXP-PROD-CLUSTER-01",
    "hypervisor_version": "ESXi 8.0 U3",
    "ha_enabled": true,
    "drs_enabled": true,
    "total_hosts": 3,
    "total_cpu_ghz": 96,
    "total_memory_gb": 768
  },
  "tags": {
    "site": "MXP",
    "environment": "prod",
    "hypervisor": "vmware"
  },
  "extensions": {
    "osiris.vmware": {
      "vcenter_instance": "vcenter-mxp.acmecorp.internal",
      "cluster_moref": "domain-c7",
      "ha_admission_control": "failover-hosts",
      "drs_automation_level": "fullyAutomated",
      "evc_mode": "intel-cascadelake"
    }
  }
}

Proxmox VE cluster grouping

{
  "id": "grp-proxmox-cluster-mxp-dev",
  "type": "compute.cluster",
  "name": "MXP Development Cluster",
  "description": "Proxmox VE development cluster in datacenter MXP",
  "members": [
    "MXP-F2-R05-SRV-001",
    "MXP-F2-R05-SRV-002",
    "MXP-F2-R06-SRV-003",
    "vm-mxp-dev-web-001",
    "vm-mxp-dev-db-001",
    "ct-mxp-dev-cache-001"
  ],
  "properties": {
    "cluster_name": "mxp-dev-pve",
    "hypervisor_version": "Proxmox VE 9.1",
    "quorum_expected_votes": 3,
    "total_nodes": 3,
    "total_cpu_cores": 72,
    "total_memory_gb": 384,
    "ha_enabled": true,
    "shared_storage": ["ceph-mxp-dev", "nfs-mxp-dev-backup"]
  },
  "tags": {
    "site": "MXP",
    "environment": "dev",
    "hypervisor": "proxmox"
  },
  "extensions": {
    "osiris.proxmox": {
      "cluster_id": "pve-cluster-mxp-dev",
      "corosync_version": "3.1.7",
      "ceph_version": "17.2.7",
      "backup_retention": {
        "daily": 7,
        "weekly": 4,
        "monthly": 3
      },
      "migration_network": "10.100.50.0/24"
    }
  }
}

[!NOTE] Both VMware vSphere and Proxmox VE clusters use the generic compute.cluster type. Vendor-specific details (vCenter instance, Corosync configuration, Ceph integration) are placed in extensions.osiris.<vendor>. Proxmox VE supports both KVM virtual machines and LXC containers; the members array can include both compute.vm and compute.container resources.

On-premise network VLAN grouping

{
  "id": "grp-mxp-vlan-100-prod",
  "type": "network.vlan",
  "name": "VLAN 100 - Production",
  "description": "Production VLAN spanning MXP datacenter fabric",
  "members": [
    "MXP-F1-R01-SW-001",
    "MXP-F1-R01-SRV-042",
    "vm-mxp-pr-web-001",
    "vm-mxp-pr-db-001"
  ],
  "properties": {
    "vlan_id": 100,
    "subnet": "10.100.0.0/24",
    "gateway": "10.100.0.1"
  },
  "tags": {
    "site": "MXP",
    "environment": "prod",
    "segment": "application"
  },
  "extensions": {
    "osiris.network": {
      "spanning_tree_priority": 4096,
      "spanning_tree_mode": "rapid-pvst"
    }
  }
}

6.5.1.2 Hyperscalers and cloud provider hybrid groups

VPC Network group (AWS)

{
  "id": "grp-aws-vpc-prod-use1",
  "type": "network.vpc",
  "name": "Production VPC",
  "description": "Primary production VPC in us-east-1",
  "members": ["subnet-aws-web-001", "subnet-aws-db-001", "aws::i-0abc123def4567890", "vm-aws-db-001"],
  "properties": {
    "cidr_block": "10.0.0.0/16",
    "region": "us-east-1"
  },
  "tags": {
    "environment": "prod",
    "managed_by": "terraform"
  },
  "extensions": {
    "osiris.aws": {
      "vpc_id": "vpc-0abc123def4567890",
      "dhcp_options_set": "dopt-0123456789abcdef",
      "security": {
        "default_security_group": "sg-0abc123"
      }
    }
  }
}

VPC Network group (GCP)

{
  "id": "grp-gcp-vpc-prod-euw1",
  "type": "network.vpc",
  "name": "Production VPC Network",
  "description": "Primary production VPC in europe-west1",
  "members": ["subnet-gcp-web-002", "subnet-gcp-db-002", "vm-gcp-web-002", "vm-gcp-db-002"],
  "properties": {
    "cidr_block": "10.1.0.0/16",
    "region": "europe-west1"
  },
  "tags": {
    "environment": "prod",
    "managed_by": "terraform"
  },
  "extensions": {
    "osiris.gcp": {
      "vpc_network_id": "projects/acme-prod/global/networks/vpc-prod-euw1",
      "auto_create_subnetworks": false,
      "routing_mode": "REGIONAL"
    }
  }
}

VNET group (Azure)

{
  "id": "grp-az-vnet-prod-weu",
  "type": "network.vnet",
  "name": "Production VNet",
  "description": "Primary production virtual network in West Europe",
  "members": ["subnet-az-web-003", "subnet-az-db-003", "vm-az-web-003", "vm-az-db-003"],
  "properties": {
    "cidr_block": "10.2.0.0/16",
    "region": "westeurope"
  },
  "tags": {
    "environment": "prod",
    "managed_by": "terraform"
  },
  "extensions": {
    "osiris.azure": {
      "vnet_id": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/rg-prod-weu/providers/Microsoft.Network/virtualNetworks/vnet-prod-weu",
      "provisioning_state": "Succeeded",
      "enable_ddos_protection": false
    }
  }
}

Resource group (Azure)

{
  "id": "grp-az-rg-prod-weu-01",
  "type": "cloud.resource.group",
  "name": "rg-prod-weu-01",
  "description": "Production resource group in West Europe",
  "members": [
    "vm-az-web-003",
    "vm-az-db-003",
    "storage-prod-001"
  ],
  "children": [
    "grp-az-vnet-prod-weu"
  ],
  "properties": {
    "region": "westeurope"
  },
  "tags": {
    "environment": "prod",
    "cost_center": "CC-1234",
    "managed_by": "terraform"
  },
  "extensions": {
    "osiris.azure": {
      "subscription_id": "12345678-1234-1234-1234-123456789012",
      "resource_group_id": "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/rg-prod-weu-01",
      "provisioning_state": "Succeeded"
    }
  }
}

[!NOTE] Cloud network constructs (AWS VPC, GCP VPC Network, Azure VNet) use generic types (network.vpc, network.vnet) with provider-specific details in extensions.osiris.<provider>. This approach enables consistent cross-cloud querying while preserving vendor-specific metadata for specialized tooling.

Hybrid environment grouping

{
  "id": "grp-prod-global",
  "type": "logical.environment",
  "name": "Production - Global Hybrid",
  "description": "Production resources across AWS, Azure, GCP and on-premise datacenter MXP",
  "members": [
    "vm-mxp-pr-web-001",
    "MXP-F1-R01-SW-001",
    "MXP-F1-R01-SRV-042",
    "aws::i-0abc123def4567890",
    "vm-gcp-web-002",
    "vm-az-web-003",
    "vm-aws-db-001",
    "vm-gcp-db-002",
    "vm-az-db-003"
  ],
  "children": [
    "grp-aws-vpc-prod-use1",
    "grp-gcp-vpc-prod-euw1",
    "grp-az-vnet-prod-weu",
    "grp-MXP-F1-R01"
  ],
  "properties": {
    "oncall_team": "platform-sme",
    "maintenance_window": "Sun 02:00-04:00 UTC",
    "backup_retention_days": 90,
    "deployment_strategy": "multi-cloud"
  },
  "tags": {
    "environment": "prod",
    "scope": "global",
    "criticality": "high"
  }
}

[!NOTE] Multi-cloud groups enable unified filtering and reporting across heterogeneous infrastructure. Members can include resources from AWS, Azure, GCP and on-premise simultaneously. The children array references both cloud network groups and on-premise physical groups, demonstrating hierarchical organization across infrastructure domains.

6.5.1.3 Generic organizational and security groups

Logical environment with multi-dimensional membership

{
  "id": "grp-prod",
  "type": "logical.environment",
  "name": "Production",
  "description": "All production workloads and infrastructure",
  "members": ["vm-mxp-pr-web-001", "vm-mxp-pr-db-001", "MXP-F1-R01-SW-001"],
  "properties": {
    "oncall_team": "platform-sme",
    "maintenance_window": "Sun 02:00-04:00 UTC",
    "backup_retention_days": 90
  },
  "tags": {
    "environment": "prod",
    "criticality": "high",
    "compliance": "soc2"
  },
  "extensions": {
    "osiris.com.acme": {
      "service_tier": "tier-1",
      "pagerduty_schedule": "PD-PROD-PRIMARY",
      "cost_center": "CC-PLATFORM-001"
    }
  }
}

Organizational team ownership

{
  "id": "grp-sw-development",
  "type": "org.team",
  "name": "Software Development Team",
  "description": "Infrastructure and platform services development ownership",
  "members": ["vm-mxp-pr-web-001", "vm-mxp-pr-db-001", "MXP-F1-R01-SW-001", "MXP-F1-R01-SRV-042"],
  "properties": {
    "team_email": "[email protected]",
    "oncall_rotation": "follow-the-sun",
    "slack_channel": "#sw-development",
    "teams_channel": "#sw-development"
  },
  "tags": {
    "department": "sw-development",
    "cost_center": "CC-1234"
  }
}

DMZ Security zone grouping

{
  "id": "grp-mxp-pr-dmz",
  "type": "security.zone",
  "name": "DMZ",
  "description": "Demilitarized zone for public-facing services",
  "members": ["vm-mxp-pr-web-001", "lb-mxp-pr-web-001"],
  "properties": {
    "trust_level": "untrusted",
    "allowed_protocols": ["http", "https"],
    "egress_restricted": true
  },
  "tags": {
    "security_zone": "dmz",
    "compliance_scope": "pci-dss"
  }
}

Vendor-specific group type (Kubernetes namespace)

{
  "id": "grp-kubernetes-production",
  "type": "osiris.kubernetes.namespace",
  "name": "production",
  "description": "Kubernetes production namespace",
  "members": ["pod-nginx-abc123", "service-nginx", "deployment-nginx"],
  "properties": {
    "cluster": "prod-cluster-1"
  },
  "extensions": {
    "osiris.kubernetes": {
      "resource_quotas": {
        "cpu": "100",
        "memory": "200Gi",
        "pods": "100"
      },
      "limit_ranges": {
        "max_cpu_per_pod": "4",
        "max_memory_per_pod": "8Gi"
      }
    }
  },
  "tags": {
    "environment": "prod",
    "team": "platform"
  }
}

6.6 Validation

If present, the following fields MUST conform to their specified types:

• properties MUST be a JSON object
• extensions MUST be a JSON object
• tags MUST be a JSON object mapping strings to strings
• members MUST be an array of strings
• children MUST be an array of strings
• status MUST be one of the defined status values (if present)

Consumers MUST:

• Accept groups with unknown fields and preserve them when re-exporting (when feasible)
• Accept groups with unknown types
• Accept groups with unknown extension namespaces
• Handle invalid member or children references gracefully

Consumers MUST NOT:

• Reject documents solely due to unrecognized group types
• Reject documents solely due to unknown group metadata fields
• Reject documents solely due to unknown extension namespaces