2 Core concepts

This section introduces the fundamental building blocks of OSIRIS: Resources, Connections, Groups and Metadata. Understanding these core concepts is essential before examining the detailed schema structure in subsequent sections.

OSIRIS models infrastructure as a graph composed of:

Resources (nodes): Individual infrastructure components with identity, properties and state.
Connections (edges): Explicit relationships between resources representing dependencies, network links or containment.
Groups: Collections of resources organized by logical or physical boundaries.
Metadata: Contextual information describing the topology’s origin, scope and provenance.

Together these elements enable OSIRIS to represent complex, heterogeneous infrastructure topologies in a structured, vendor-neutral format.

2.1 Resources

2.1.1 Definition

A Resource represents a discrete infrastructure component with identity, properties and lifecycle. Resources are the fundamental baseline units of an OSIRIS topology and MAY correspond to (non-exhaustive examples):

Compute resources: virtual machines, containers, physical servers.
Network devices: routers, switches, firewalls, load balancers.
Storage systems: volumes, arrays, buckets, file systems.
Platform services: databases, message queues, managed services.
Application components: services, repositories, deployments.
Operational technology elements: building automation controllers, industrial sensors, SCADA components.

2.1.2 Resource identity

Every resource MUST have a unique identifier within an OSIRIS document. Resource identifiers enable references from connections, group memberships and other objects.

Resource identity in OSIRIS is document-scoped: identifiers MUST be unique within a single OSIRIS document but need not be globally unique across other documents or systems. This simplifies producer implementation while preserving referential integrity within each snapshot.

Resources SHOULD retain stable identifiers across multiple exports of the same infrastructure when feasible. Stable identifiers enable consumers to correlate resources over time, detect changes and compare snapshots.

The id field uniquely identifies a resource within the topology.

ID Construction:

Producers SHOULD construct IDs using one of these strategies:

Native ID <id> (preferred for unique native identifiers):

   "id": "i-0abc123def456"

Namespaced native ID <provider>::<id> (preferred for multi-provider topologies):

   "id": "aws::i-0abc123def456"
   "id": "vmware::vm-1234"
   "id": "cisco::FOC1234ABCD"
   "id": "dell::MXP-SRV-001"

Full resource identifier (for providers that support structured resource IDs):

   "id": "arn:aws:ec2:us-east-1:123456789012:instance/i-0abc123def456"
   "id": "/subscriptions/.../resourceGroups/rg/providers/Microsoft.Compute/virtualMachines/vm-01"

Generated ID (only when native ID unavailable or not globally unique):

   "id": "postgres-prod-01.mxp.internal.osiris.com.acme"

Rationale: Using native provider IDs maintains traceability to source systems, enables change tracking and reflects actual infrastructure state.

ID separator (::): The double-colon separator distinguishes the provider namespace from the native identifier. This separator was chosen because:

Does not conflict with AWS ARNs (which use single colons: arn:aws:ec2:...)
Does not conflict with Azure resource IDs (which use slashes: /subscriptions/...)
Provides clear visual distinction between provider and identifier
Easy to parse programmatically: id.split('::') works in all languages

The provider name (left of ::) follows canonical naming rules from section 4.3.3: use segments: [a-z0-9] lowercase letters, digits and dots separator only (no hyphens, underscores or spaces) (e.g. arista, paloalto). The native identifier (right of ::) preserves the original vendor format.

Uniqueness: IDs MUST be unique within a topology. When combining resources from multiple providers, use namespaced IDs (approach 2) or full resource identifiers (approach 3).

2.1.3 Resource types

Each resource MUST declare a type that classifies what kind of infrastructure component it represents. Resource types follow a hierarchical dot notation convention (e.g. compute.vm, network.switch, storage.volume) that supports both categorization and specificity.

The type system includes:

Standard types: common resource categories defined in chapter 7 (Resource Type Taxonomy).
Vendor specific types: platform specific types using namespaced conventions (see chapter 8).
Custom types: organization defined types for specialized or internal components.

Consumers MUST be able to process resources with unknown types by treating them as opaque resources while still preserving identity, properties and relationships.

2.1.4 Provider attribution

Resources retain attribution to their originating system through provider information.

Provider attribution enables:

traceability to source systems for validation or enrichment.
mixed-vendor topologies where resources from different platforms coexist.
platform-specific rendering or behavior in consuming tools (when supported).
audit trails and source tracking.

Provider information typically includes provider name (e.g. AWS, Azure, Arista, Cisco, Proxmox), native resource identifiers, account/subscription/project context and regional or zonal placement where applicable.

2.1.5 Resource properties

Resources carry properties that describe characteristics, configuration and operational attributes.

Properties MAY include:

Intrinsic attributes: size, capacity, network addresses, operating system.
Configuration details: enabled features, policies, attached resources.
Operational indicators: running, stopped, healthy, degraded (as applicable).
Vendor-specific metadata: fields relevant to particular platforms.

The core OSIRIS schema defines a standard property structure. The extension mechanism allows producers to include additional properties without breaking schema validity. Consumers that do not recognize extended properties MUST safely ignore them while processing core fields.

2.1.6 Resource status and state

Resources MAY include high-level status and/or state information to support filtering, visualization and operational awareness.

Status generally refers to lifecycle presence or availability within the snapshot context.
State generally refers to an operational condition (where applicable).

The exact fields and allowed values are defined in the chapter 4 Resource model (see section 4.5).

2.1.7 Resource lifecycle considerations

OSIRIS represents infrastructure at a point in time. Resources reflect their observed state when the OSIRIS document was generated, not ongoing changes. Lifecycle events such as creation, modification or deletion are not represented within a single document but MAY be inferred by comparing multiple snapshots.

Resources that no longer exist in source systems SHOULD NOT appear in subsequent exports unless producers intentionally emit tombstones or inactive entries for change-tracking purposes (as defined by the schema and producer behavior).

2.2 Connections

2.2.1 Definition

A Connection represents an explicit relationship between two resources. Connections are the edges in the OSIRIS topology graph and describe how resources interact depend on each other or are organized hierarchically.

Connections capture relationships that MAY include (non-exhaustive examples):

Network connectivity: Layer 2/Layer 3 links, routing neighbours, firewall rules, VPN tunnels.
Dependencies: Applications depending on databases, services consuming APIs, load balancers distributing to backends.
Containment: Virtual machines within hypervisors, containers within pods, resources within VPCs or subnets.
Data flow: Storage mounted to compute, backup relationships, replication streams.
Physical topology: Cables between switches, power distribution, rack-to-server relationships.
Logical associations: Membership in availability zones, assignment to projects, tagging relationships.

2.2.2 Connection identity

Every connection MUST have a unique identifier within an OSIRIS document. Connection identifiers enable reference and validation.

Connection identity is document-scoped, analogous to resource identity. Identifiers MUST be unique within a single OSIRIS document but need not be globally unique.

2.2.3 Source and target

Each connection MUST identify a source resource and a target resource using their respective resource identifiers.

Both source and target identifiers MUST reference resources that exist within the same OSIRIS document. Connections MUST NOT reference resources outside the document boundary.

Producers SHOULD validate referential integrity before emitting OSIRIS documents. Consumers MUST handle connections with invalid references gracefully, either by reporting validation errors or by ignoring malformed connections while processing valid topology data.

2.2.4 Connection types

Each connection MUST declare a type that classifies the nature of the relationship. Connection types enable consumers to distinguish between different kinds of relationships and apply appropriate logic for visualization, analysis or validation.

The connection type system includes:

Standard types: common relationship types defined in chapter 5 section 5.2 (Connection Types), such as network, dependency, contains, dataflow.
Vendor-specific types: platform specific relationships using namespaced conventions (see Chapter 8).
Custom types: organization defined types for specialized relationships.

Consumers MUST be able to process connections with unknown types by treating them as generic relationships while preserving their source, target and properties.

2.2.5 Directionality

Connections MAY specify directionality to indicate the orientation or flow of the relationship:

Bidirectional: The relationship applies equally in both directions (e.g. a Layer 2 network link, peering relationships).
Forward (source > target): The relationship flows from source to target (e.g. a service depends on a database, traffic flows from client to server).
Reverse (target > source): The relationship flows from target to source (e.g. telemetry or logs flow from a workload/agent to a monitoring or logging system)

If directionality is unspecified, consumers SHOULD treat the connection as bidirectional unless the connection type definition explicitly specifies otherwise.

Directionality is distinct from the graph structure itself: the source and target fields define graph topology, while directionality provides semantic annotation about how the relationship should be interpreted.

2.2.6 Connection properties

Connections MAY carry properties that describe relationship characteristics:

Protocol or mechanism: TCP, HTTP, NFS, iSCSI, routing protocol.
Capacity or bandwidth: Link speed, throughput limits.
Ports or endpoints: Source/destination ports, IP addresses.
Quality attributes: Latency, packet loss, reliability indicators.
Administrative metadata: Tags, labels, ownership, creation time.

As with resources, the extension mechanism allows producers to include vendor specific or custom properties without breaking schema validity. Consumers that do not recognize extended properties MUST safely ignore them.

2.2.7 Connection status

Connections MAY include status information indicating operational health or availability to support filtering and visualization.

Common values include active, inactive, degraded and unknown. The exact field structure and allowed values are defined in chapter 5 Connection model (see section 5.4 Connection properties).

2.2.8 Implicit vs. explicit relationships

OSIRIS requires connections to be explicit. Relationships that could be inferred from resource properties (e.g. a VM referencing a VPC ID in its properties) SHOULD also be represented as explicit connection objects.

Explicit representation ensures:

consuming tools do not require inference logic specific to vendor property conventions.
relationship semantics are clear and unambiguous.
topology graphs can be traversed using connection objects alone.

Producers MAY emit both property based references and explicit connections for redundancy and compatibility with different consumer implementations.

2.2.9 Multiple connections between resources

Two resources MAY have multiple connections of different types or with different properties.

Example:

A virtual machine and a storage volume may have both a contains relationship and a dataflow relationship.
Two switches may have multiple network connections representing distinct physical links.

Each distinct relationship MUST be represented as a separate connection object with a unique identifier.

2.3 Groups

2.3.1 Definition

A Group represents a logical or physical collection of resources organized by common characteristics, boundaries or administrative domains. Groups provide structure to OSIRIS topologies and enable representation of organizational, architectural or geographical boundaries.

Groups MAY represent (non-exhaustive examples):

Network boundaries: VPCs/virtual networks, subnets, VLANs, VRFs, security zones.
Resource organization: resource groups, projects, namespaces, folders, tenants.
Physical location: data centers, buildings, floors, rooms, racks, rows.
Availability constructs: regions, availability zones, fault domains.
Administrative boundaries: subscriptions, accounts organizational units.
Functional grouping: application tiers (web/app/db), environments (production/staging/development).

2.3.2 Group identity

Every group MUST have a unique identifier within an OSIRIS document. Group identifiers enable reference from other groups and from metadata contexts.

Group identity is document-scoped, consistent with resources and connections. Identifiers MUST be unique within a single OSIRIS document but need not be globally unique.

2.3.3 Group types

Each group MUST declare a type that classifies what kind of collection or boundary it represents. Group types follow a hierarchical dot-notation convention similar to resource types (e.g. network.vpc, logical.environment, physical.datacenter).

The group type system includes:

Standard types: common grouping categories defined in Chapter 6 Group model, section 6.2 (Group types).
Vendor-specific types: platform specific grouping constructs using namespaced conventions (see Chapter 8 Extensive mechanism).
Custom types: organization defined types for specialized grouping needs.

Consumers MUST be able to process groups with unknown types by treating them as generic collections while preserving membership and hierarchy.

2.3.4 Membership (resources)

Groups contain members, which are resource identifiers representing the resources that belong to the group. Membership is represented as an array of resource IDs.

All member identifiers MUST reference resources that exist within the same OSIRIS document. Groups MUST NOT reference resources outside the document boundary.

A resource MAY be a member of multiple groups simultaneously. For example, a physical server may belong to both a rack (physical.rack) and an environment group (logical.environment.production), while a VM may belong to both a subnet group (network.subnet) and an application tier group (logical.tier.web).

Membership is explicit and direct: resources listed in a group are members of that group only. Consumers that require transitive membership SHOULD implement traversal logic.

2.3.5 Hierarchical groups (nesting)

Groups MAY define hierarchy by referencing other groups by identifier as children (sub-groups). Group hierarchies MUST NOT contain cycles.

This enables nested organizational structures such as:

A data center group containing building groups.
A building group containing floor groups.
A floor group containing room groups.
A room group containing rack groups.
A rack group containing server groups.
A server group containing resources (via membership).

Group nesting MUST be explicit (e.g. a children[] list of group IDs). Resources that are members of a child group are not automatically members of the parent group unless explicitly listed (e.g. no implicit transitive membership).

Producers MUST ensure that group hierarchies do not create circular references. Consumers SHOULD detect and handle circular hierarchies gracefully, either by reporting validation errors or by ignoring problematic relationships.

2.3.6 Group properties

Groups MAY carry properties that describe collection characteristics:

Boundaries or constraints: IP ranges (subnets), VLAN IDs, VRF names, geographic coordinates (data centers).
Configuration or policies: security policies, routing constraints, segmentation intent.
Capacity or limits: quotas, available rack units, power capacity.
Administrative metadata: tags, labels, ownership, creation time.

As with resources and connections, the extension mechanism allows producers to include vendor-specific or custom properties without breaking schema validity. Consumers that do not recognize extended properties MUST safely ignore them.

2.3.7 Groups vs. connections

Groups and connections serve complementary purposes:

Groups represent containment and organization (boundaries, membership, hierarchy).
Connections represent relationships and interactions (communication, dependency, linkage).

Example (in hybrid environments):

A VM or server is a member of a subnet/VLAN group (structure).
A load balancer dependency or routes_to backend instances via connections (behavior/interaction).

Producers SHOULD choose the representation that most clearly expresses the intended semantics. Consumers SHOULD support both patterns and MUST NOT assume exclusive use of either mechanism.

2.3.8 Empty groups

Groups MAY have an empty membership list (zero members). Empty groups are valid and may represent:

Pre-defined organizational structures awaiting resource assignment.
Placeholder groups for documentation or planning.
Structures preserved across exports even when temporarily unused.

Consumers MUST handle empty groups without error.

2.4 Metadata

2.4.1 Definition

Metadata provides contextual information about an OSIRIS document, including its origin, scope, generation details and provenance. Metadata enables consumers to understand what infrastructure the document represents, when it was produced and how to interpret or validate its contents.

Metadata is distinct from resource properties: metadata describes the document and topology as a whole not individual infrastructure components.

2.4.2 Purpose of metadata

Metadata serves several critical functions in the OSIRIS interchange model:

Provenance tracking: Identifying the source system, tool or process that generated the document.
Temporal context: Recording when the snapshot was taken to enable time-based correlation or change detection.
Scope documentation: Describing what infrastructure is included (regions, accounts, environments) and what is excluded.
Specification context: Indicating which OSIRIS version the document conforms to.
Audit trail: Supporting compliance and governance workflows by documenting data lineage.
Consumer guidance: Providing advisory hints that help consuming tools interpret or validate the topology.

2.4.3 Core metadata elements

OSIRIS metadata MUST include at minimum:

Timestamp: An ISO 8601 timestamp indicating when the topology snapshot was generated (e.g. 2025-12-18T14:30:00Z).

OSIRIS metadata SHOULD include:

Generator information: The name and version of the tool or system that produced the document.
Scope description: What providers, regions, accounts/projects/subscriptions or environments are represented.

OSIRIS metadata MAY include:

Tags or labels: Custom key-value pairs for organizational categorization.
Source references: References to originating systems, API endpoints or datasets used to construct the topology.
Validation hints: Advisory information to assist consumers in validating or interpreting the topology.

[!NOTE] The OSIRIS specification version is declared at the document level (see section 3.2). Metadata MAY repeat this information for convenience, but any duplicated version information MUST be consistent.

2.4.4 Metadata extensibility

Like resources, connections and groups, metadata supports extension through custom properties. Producers MAY include vendor-specific or organization-specific metadata fields without breaking schema validity.

Consumers that do not recognize extended metadata properties MUST safely ignore them while processing the document.

2.4.5 Metadata vs. resource properties

It is important to distinguish metadata from resource level properties:

Metadata describes the OSIRIS document: “This topology was exported from AWS on 2025-12-18 at 14:30 UTC covering us-east-1 and us-west-2a.”
Resource properties describe individual components: “This instance is t3.medium with 2 vCPUs and 4 GB RAM.”

Information that applies to the entire document or export process belongs in metadata. Information that applies to a specific resource belongs in that resource’s properties.

2.4.6 Metadata and change tracking

While OSIRIS represents infrastructure at a point in time, metadata enables consumers to correlate multiple snapshots over time:

Timestamps allow chronological ordering of documents.
Generator information enables filtering by source or tool version.
Scope descriptions help identify whether documents represent comparable infrastructure sets.

Change detection and versioning logic are the responsibility of consuming systems but metadata provides the context to support these workflows.

2.4.7 Metadata stability

Metadata structure is part of the core OSIRIS schema and follows the same versioning and compatibility rules as the rest of the specification.

Consumers SHOULD validate metadata before processing topology content to detect version mismatches or unsupported schema features early.