5 Connection model

5.0 Overview

Connections in OSIRIS represent explicit relationships between resources. They form the edges of the topology graph and encode how infrastructure components interact, depend on each other or are linked physically or logically.

This chapter defines:

The structure and required fields of connection objects
Standard connection types and their semantics
Directionality and how it models flows or dependencies
Connection metadata via properties, extensions, tags and status/state

Connections complement resources (Chapter 4) and groups (Chapter 6) to form a complete, traversable topology graph.

5.1 Connection object structure

5.1.1 Overview

A connection is a JSON object that links two resources within the same OSIRIS document. Connections are stored in the topology.connections array (see chapter 3, section 3.4).

5.1.2 Required fields

Every connection MUST have a unique identifier within an OSIRIS document via the id field.

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

Unlike resources which represent vendor-managed objects with native identifiers, connections represent relationships discovered or inferred by parsers. Therefore, connection IDs do not reference external vendor systems and do not use the provider::native-id namespace pattern.

Every connection MUST include:

id (string): Unique identifier for this connection within the document
source (string): Resource ID of the source endpoint
target (string): Resource ID of the target endpoint
type (string): Connection type using dot notation (see section 5.2)

ID Construction: Producers SHOULD construct connection IDs using one of these strategies:

Sequential numbering:

{
    "id": "conn-001",
    "id": "conn-002",
    "id": "conn-003"
}

Descriptive naming (recommended):

{
    "id": "conn-aws-vpc-subnet-001",
    "id": "conn-aws-web-db-dependency",
    "id": "conn-mxp-leaf-spine-uplink",
    "id": "conn-mxp-app-to-cache"
}

Type-prefixed descriptive:

{
    "id": "network-vpc-to-subnet-001",
    "id": "dependency-web-to-db",
    "id": "contains-subnet-vm-001"
}

Hash-based (for reproducibility):

{
    "id": "conn-a1b2c3d4e5f6"
}

UUID (for guaranteed uniqueness on large infrastructures):

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

5.1.3 Optional fields

Connections MAY include:

name (string): Human-readable label for the connection
description (string): Free-text description of the relationship
direction (string): Directionality indicator (see chapter 5, ection 5.3)
status (string): Normalized status category (see chapter 4, section 4.5 for vocabulary)
state (string): Vendor-specific granular state (analogous to resource state)
properties (object): Connection-specific attributes
extensions (object): Vendor-specific metadata using osiris.<namespace> keys (see Chapter 8)
tags (object): Key-value labels (string > string)

5.1.4 Minimal connection examples

Following examples show how OSIRIS can at minimum allow you to represent objects within the infrastructure.

Hyperscaler (AWS) EC2 dependency to Postgres DB:

{
  "id": "conn-aws-web-db-dependency",
  "source": "aws::i-0abc123def4567890",
  "target": "aws::db-prod-postgres-01",
  "type": "dependency",
  "direction": "forward"
}

Additional examples:

Hyperscaler (AWS) network containment:

{
  "id": "conn-aws-ec2-subnet-001",
  "source": "aws::subnet-0abc123",
  "target": "aws::i-0abc123def4567890",
  "type": "contains",
  "direction": "forward"
}

Multi-vendor hybrid network connection:

{
  "id": "conn-aws-vpc-subnet-001",
  "source": "aws::vpc-0abc123",
  "target": "vmware::vm-1234",
  "type": "network",
  "direction": "bidirectional"
}

On-premise Physical network link between datacenter switches:

{
  "id": "conn-mxp-leaf-spine-uplink-r01-u42",
  "source": "arista::MXP-SW-LEAF-01",
  "target": "arista::MXP-SW-SPINE-01",
  "type": "network",
  "direction": "bidirectional",
  "properties": {
    "link_type": "uplink",
    "protocol": "ethernet",
    "bandwidth_gbps": 100,
    "mtu": 9214,
    "vlan_mode": "trunk",
    "interfaces": {
      "source": {
        "port": "Ethernet49/1",
        "port_type": "uplink",
        "speed_gbps": 100
      },
      "target": {
        "port": "Ethernet1/1",
        "port_type": "downlink",
        "speed_gbps": 100
      }
    },
    "management": {
      "source_ip": "10.130.100.101",
      "target_ip": "10.130.100.1"
    }
  },
  "status": "active",
  "extensions": {
    "osiris.arista": {
      "lacp_mode": "active",
      "port_channel_id": "Port-Channel49"
    }
  }
}

5.1.5 Referential integrity

The source and target fields MUST reference resources that exist in the same document’s topology.resources array.

Connections MUST NOT:

Reference resources in different OSIRIS documents
Reference non-existent resource IDs
Create self-references where source == target

Producers SHOULD validate referential integrity before exporting. Consumers MUST handle invalid references gracefully (e.g. emit warnings, skip invalid connections or reject the document in strict-validation mode).

5.1.6 Connection identity and stability

Connection IDs MUST be unique within the document. Connection IDs SHOULD remain stable across exports when feasible to enable change detection and correlation.

Producers MAY generate connection IDs deterministically using a stable fingerprint derived from:

endpoint identities (source, target)
connection type
direction
(optionally) key endpoint metadata that materially distinguishes the link (e.g. source_port, target_port, VLAN, protocol)

Deterministic fingerprint (recommended)

Producers SHOULD build a canonical endpoint tuple:

A = (resource_id, port) and B = (resource_id, port) where port is optional (empty string if unknown)

For direction = "bidirectional", producers SHOULD canonicalize endpoint ordering by sorting (A, B) before generating the ID, to prevent ID flips between exports.

For direction = "forward" and direction = "reverse", producers SHOULD NOT reorder endpoints, as the orientation is semantically meaningful.

Example fingerprint:

fingerprint = type + "|" + direction + "|" + A.resource_id + "|" + A.port + "|" + B.resource_id + "|" + B.port
id = hash(fingerprint)

Human-readable IDs (optional)

Instead of hashing, producers MAY use a human-readable ID encoding both endpoints, for example:

cn-<source_id>-<source_port>-to-<target_id>-<target_port>-<index>

When using human-readable IDs for direction = "bidirectional", producers SHOULD apply the same canonical endpoint ordering described above (sort (A, B) first) to ensure stability across exports.

[!NOTE] A single pair of resources may have multiple distinct connections (e.g. multiple ports or VLANs). If the chosen fingerprint is not sufficient to uniquely identify each connection, producers MUST include additional discriminators (such as ports, VLAN, protocol) or append a stable suffix.

5.1.7 Multiple connections between the same resources

Two resources MAY have multiple connections of different types or different properties. Each distinct relationship MUST be represented as a separate connection object with a unique id.

5.1.8 Field extensibility

Consumers MUST accept connections 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.

5.2 Connection types

5.2.1 Overview

The type field classifies the semantic meaning of a relationship between resources. Connection types use hierarchical dot notation similar to resource types (see chapter 4, section 4.2).

5.2.2 Type format rules

Connection type values:

MUST NOT contain whitespace
MUST be lowercase
MUST use dot (.) as the segment separator when multiple segments are present
MUST NOT start or end with a dot
MUST NOT contain consecutive dots (..)

Examples of valid connection types:

network
dependency
contains
dataflow
physical.ethernet
network.bgp

5.2.3 Standard connection types (v1.0)

OSIRIS defines the following standard connection types:

network

Meaning: Network-layer connectivity or reachability between resources (L2/L3 or higher-level network linkage)

Direction: Typically bidirectional unless modeling asymmetric flows

Common subtypes (optional):

network.l2
network.l3
network.bgp
network.ospf
network.vpn

dependency

Meaning: One resource requires another to function (application/service dependency, runtime requirement)

Direction: Typically forward (source depends on target)

Common subtypes (optional):

dependency.api
dependency.database
dependency.storage

contains

Meaning: Hierarchical containment (source contains target)

Direction: Typically forward

[!NOTE] Containment can be represented via contains connections or via groups (Chapter 6). Use whichever yields the clearest model; avoid duplicating the same containment semantics in both unless you have a specific consumer need.

dataflow

Meaning: Data transfer, message passing or write/read flow between resources

Direction: Typically forward (data flows from source to target)

Common subtypes (optional):

dataflow.http
dataflow.kafka
dataflow.mqtt

physical.*

Meaning: Physical connectivity (cables, fiber, power)

Direction: Typically bidirectional

Common subtypes:

physical.ethernet
physical.fiber
physical.power

5.2.4 Vendor-specific and custom connection types

Vendor-specific or organization-specific relationships SHOULD use the namespaced pattern:

osiris.<namespace>.<type>

Examples:

osiris.aws.vpc.peering
osiris.kubernetes.service.selector
osiris.arista.mlag
osiris.com.acme.workflow

5.2.5 Unknown connection types

Consumers MUST accept connections with unknown types. When encountering unknown types, consumers SHOULD:

Preserve the connection in the graph
Treat it as a generic relationship
Display the type string verbatim (useful for debugging)
Traverse it normally

5.3 Directionality

5.3.1 Overview

The direction field indicates whether a connection represents a symmetric relationship or a forward or reverse relationship with a specific orientation.

5.3.2 Direction values

If present, direction MUST be one of:

bidirectional: Symmetric relationship (default if omitted)
forward: Flows from source to target
reverse: Flows from target to source

5.3.3 Default behavior

If direction is omitted, consumers SHOULD treat the connection as bidirectional unless the connection type definition explicitly states a directional default.

5.3.4 Graph traversal semantics

bidirectional: edges in both directions
forward: edge source > target
reverse: edge target > source

5.4 Connection properties

5.4.1 Overview

Connections use the same metadata pattern as resources:

properties: Portable, connection-specific attributes
extensions: Vendor/tool/org-specific structures using osiris.<namespace>
tags: Simple labels (string > string)
status: Normalized high-level category (active|inactive|degraded|retired|unknown)
state: Optional granular vendor-defined state

5.4.2 Common properties

Network connections:

protocol (e.g. tcp, udp, icmp, bgp)
ports (array of numbers)
vlan (number)
mtu (number)
bandwidth_mbps / speed_gbps
latency_ms

Physical connections:

source_port (string)
target_port (string)
cable_type (string; e.g. cat6a, om4, os2, dac)
length_meters (number)
source_transceiver (object; optional): transceiver/module installed on the source port
target_transceiver (object; optional): transceiver/module installed on the target port

source_transceiver and target_transceiver are Intended for pluggable modules (SFP/SFP+/SFP28/QSFP family, SFP-10G-T, etc.). For fixed copper ports (integrated BASE-T NIC ports), producers SHOULD omit *_transceiver and instead describe the port/NIC at the resource level (e.g. server NIC model in resource properties or provider.model). If producers still choose to represent fixed-port endpoints, they MUST not imply optical DOM availability.

Each *_transceiver object SHOULD include when known:

vendor (string)
model (string; e.g. “SFP-10G-T”, “QSFP-100G-SR4”)
part_number (string; optional)
serial_number (string; optional)
form_factor (string; e.g. sfp, sfp+, sfp28, qsfp28, qsfp-dd)
dom (object; optional): Digital Optical Monitoring - Digital Diagnostic Monitoring (DOM/DDM) telemetry for transceivers that support diagnostics.
- DOM/DDM commonly includes module temperature, supply voltage, Tx/Rx optical power and often Tx bias current.
- Availability, precision and supported metrics are module/vendor dependent; producers SHOULD omit keys that are not supported (equivalent to “N/A” on many platforms).
- Consumers SHOULD treat DOM values as indicative operational telemetry, not metrology-grade measurements.
Recommended DOM keys (portable core):
- module_temperature_c (number)
- supply_voltage_v (number)
- tx_power_dbm (number)
- rx_power_dbm (number)
- tx_bias_ma (number; if supported)
Lane-aware DOM (optional, for multi-lane optics):
- lanes (array of objects): per-lane diagnostics when available
  - lane (number; 1-based index)
  - tx_power_dbm (number; optional)
  - rx_power_dbm (number; optional)
  - tx_bias_ma (number; optional)
- For multi-lane optics, producers SHOULD use lanes. For single-lane optics, producers MAY use only the top-level keys. If both are present, consumers SHOULD prefer lanes.
Advanced diagnostics (optional, often vendor/platform dependent):
- pre_fec_ber (number; optional)
- uncorrected_ber (number; optional)
- snr_db (number; optional)
- laser_temperature_c (number; optional)
- laser_frequency_ghz (number; optional)
Producers SHOULD place highly vendor-specific optics telemetry, proprietary counters or fields with vendor-dependent semantics in extensions.osiris.<namespace>.

Dependency connections:

required (boolean)
endpoint (string; URL/host)
timeout_seconds (number)
api_version (string)

Containment connections:

allocation (object; producer-defined)
capacity (object; producer-defined)

5.4.3 Extensions

Extensions follow the same osiris.<namespace> convention as resources:

{
  "extensions": {
    "osiris.cisco": {
      "neighbor_address": "192.0.2.1",
      "soft_reconfiguration": true
    }
  }
}

Consumers MUST ignore unknown extension namespaces and fields.

5.4.4 Examples

Hyperscaler (AWS) network connection (bidirectional)

{
  "id": "conn-aws-web-db-network",
  "source": "aws::i-0abc123def4567890",
  "target": "aws::db-prod-postgres-01",
  "type": "network",
  "direction": "bidirectional",
  "status": "active",
  "properties": {
    "protocol": "tcp",
    "ports": [5432],
    "vlan_id": 100,
    "interfaces": {
      "source": {
        "ip": "10.0.1.10",
        "port": "eth0"
      },
      "target": {
        "ip": "10.0.2.20",
        "port": "eth0"
      }
    }
  },
  "tags": {
    "environment": "production",
    "application": "web-tier"
  }
}

Application dependency (forward)

{
  "id": "conn-app-api-auth-dependency",
  "source": "kubernetes::api-gateway-7d8f9c-abcde",
  "target": "kubernetes::auth-service-5a6b7c-fghij",
  "type": "dependency.api",
  "direction": "forward",
  "status": "active",
  "properties": {
    "required": true,
    "api_version": "v2",
    "timeout_seconds": 5,
    "retry_policy": {
      "max_retries": 3,
      "backoff_seconds": 2
    }
  },
  "tags": {
    "criticality": "high"
  }
}

On-premise physical copper ethernet link (bidirectional)

{
  "id": "conn-mxp-sw-to-srv-042-port48",
  "source": "arista::MXP-SW-LEAF-01",
  "target": "dell::MXP-SRV-042",
  "type": "physical.ethernet",
  "direction": "bidirectional",
  "status": "active",
  "properties": {
    "link_type": "server-access",
    "speed_gbps": 10,
    "cable": {
      "model": "cat6a",
      "length_meters": 5
    },
    "interfaces": {
      "source": {
        "port": "Ethernet48",
        "port_type": "access",
        "transceiver": {
          "vendor": "arista",
          "model": "SFP-10G-T",
          "form_factor": "sfp+",
          "serial_number": "SFP10GT-AR12345"
        }
      },
      "target": {
        "port": "eno1",
        "port_type": "onboard",
        "transceiver": {
          "vendor": "broadcom",
          "model": "57412 Quad Port 10GbE",
          "form_factor": "base-t",
          "serial_number": "BCM57412-DL98765"
        }
      }
    }
  },
  "tags": {
    "rack": "R01",
    "cable_id": "MXP-CAB-048-042"
  }
}

On-premise physical fiber ethernet lin (bidirectional)

{
  "id": "conn-mxp-leaf-spine-uplink-r01",
  "source": "arista::MXP-SW-LEAF-01",
  "target": "arista::MXP-SW-SPINE-01",
  "type": "physical.fiber",
  "direction": "bidirectional",
  "status": "active",
  "properties": {
    "link_type": "uplink",
    "speed_gbps": 100,
    "cable": {
      "model": "om4",
      "length_meters": 30
    },
    "interfaces": {
      "source": {
        "port": "Ethernet49/1",
        "port_type": "uplink",
        "admin_status": "up",
        "oper_status": "up",
        "transceiver": {
          "vendor": "arista",
          "model": "100GBASE-SR4",
          "form_factor": "qsfp28",
          "serial_number": "QSFP100SR4-AR12345",
          "wavelength_nm": 850,
          "digital_optical_monitoring": {
            "module_temperature_c": 42.1,
            "supply_voltage_v": 3.28,
            "lanes": [
              {
                "lane": 1,
                "tx_power_dbm": -1.3,
                "rx_power_dbm": -2.1,
                "tx_bias_ma": 44.2
              },
              {
                "lane": 2,
                "tx_power_dbm": -1.2,
                "rx_power_dbm": -2.3,
                "tx_bias_ma": 44.0
              },
              {
                "lane": 3,
                "tx_power_dbm": -1.4,
                "rx_power_dbm": -2.2,
                "tx_bias_ma": 44.4
              },
              {
                "lane": 4,
                "tx_power_dbm": -1.1,
                "rx_power_dbm": -2.0,
                "tx_bias_ma": 43.8
              }
            ]
          }
        }
      },
      "target": {
        "port": "Ethernet1/1",
        "port_type": "downlink",
        "admin_status": "up",
        "oper_status": "up",
        "transceiver": {
          "vendor": "arista",
          "model": "100GBASE-SR4",
          "form_factor": "qsfp28",
          "serial_number": "QSFP100SR4-AR67890",
          "wavelength_nm": 850,
          "digital_optical_monitoring": {
            "module_temperature_c": 39.7,
            "supply_voltage_v": 3.30,
            "lanes": [
              {
                "lane": 1,
                "tx_power_dbm": -1.0,
                "rx_power_dbm": -2.4,
                "tx_bias_ma": 41.9
              },
              {
                "lane": 2,
                "tx_power_dbm": -1.1,
                "rx_power_dbm": -2.5,
                "tx_bias_ma": 42.1
              },
              {
                "lane": 3,
                "tx_power_dbm": -1.2,
                "rx_power_dbm": -2.6,
                "tx_bias_ma": 42.0
              },
              {
                "lane": 4,
                "tx_power_dbm": -1.0,
                "rx_power_dbm": -2.3,
                "tx_bias_ma": 41.8
              }
            ]
          }
        }
      }
    }
  },
  "tags": {
    "rack": "R01",
    "layer": "leaf-spine"
  },
  "extensions": {
    "osiris.arista": {
      "lacp_mode": "active",
      "port_channel_id": "Port-Channel49"
    }
  }
}

Hyperscaler (AWS) vendor-specific connection type (VPC peering)

{
  "id": "conn-aws-vpc-peering-prod-dev",
  "source": "aws::vpc-0abc123def456",
  "target": "aws::vpc-0def789ghi012",
  "type": "osiris.aws.vpc.peering",
  "direction": "bidirectional",
  "status": "active",
  "properties": {
    "peering_status": "active",
    "cidr_blocks": {
      "source": ["10.0.0.0/16"],
      "target": ["10.1.0.0/16"]
    },
    "dns_resolution": {
      "source_to_target": true,
      "target_to_source": true
    }
  },
  "extensions": {
    "osiris.aws": {
      "peering_connection_id": "pcx-0abc123def4567890",
      "accepter_vpc_info": {
        "owner_id": "123456789012",
        "region": "us-east-1"
      },
      "requester_vpc_info": {
        "owner_id": "123456789012",
        "region": "us-east-1"
      }
    }
  },
  "tags": {
    "purpose": "cross-environment-access",
    "cost_center": "networking"
  }
}

5.4.5 Validation

If present, properties and extensions MUST be JSON objects. tags (if present) MUST be a JSON object mapping strings to strings.

Consumers MUST accept connections with unrecognized property keys or extension namespaces and MUST NOT reject documents solely due to unknown connection metadata.

5 Connection model

5.0 Overview

5.1 Connection object structure

5.1.1 Overview

5.1.2 Required fields

5.1.3 Optional fields

5.1.4 Minimal connection examples

5.1.5 Referential integrity

5.1.6 Connection identity and stability

Deterministic fingerprint (recommended)

Human-readable IDs (optional)

5.1.7 Multiple connections between the same resources

5.1.8 Field extensibility

5.2 Connection types

5.2.1 Overview

5.2.2 Type format rules

5.2.3 Standard connection types (v1.0)

network

dependency

contains

dataflow

physical.*

5.2.4 Vendor-specific and custom connection types

5.2.5 Unknown connection types

5.3 Directionality

5.3.1 Overview

5.3.2 Direction values

5.3.3 Default behavior

5.3.4 Graph traversal semantics

5.4 Connection properties

5.4.1 Overview

5.4.2 Common properties

5.4.3 Extensions

5.4.4 Examples

Hyperscaler (AWS) network connection (bidirectional)

Application dependency (forward)

On-premise physical copper ethernet link (bidirectional)

On-premise physical fiber ethernet lin (bidirectional)

Hyperscaler (AWS) vendor-specific connection type (VPC peering)

5.4.5 Validation

Help improve this page