8 Extension mechanism

8.0 Overview

The OSIRIS extension mechanism enables producers to include vendor-specific, domain-specific or organization-specific data without fragmenting the core standard. Extensions preserve interoperability: consumers that do not recognize extension data can safely ignore it while still processing the core topology.

Extension philosophy:

• Standard first: Use standard fields and types whenever applicable
• Extend selectively: Extensions SHOULD be the exception, not the default
• Preserve interoperability: Unknown extensions must not break consumers
• Document extensions: Producers SHOULD document extension semantics for consumers

Terminology:

• Extension: Any data beyond the core OSIRIS specification
• Namespace: A prefix that identifies the source or domain of extension data (e.g. osiris.aws, osiris.oci, osiris.com.acme)
• Standard fields: Fields defined in this specification (e.g. id, type, provider, properties)
• Custom fields: Additional fields placed in the extensions object

8.1 Properties vs extensions

OSIRIS provides two mechanisms for including additional data beyond required fields: the properties object and the extensions object. Understanding when to use each is critical for maintaining interoperability.

8.1.1 Properties object

The properties object contains resource-specific attributes that describe generic infrastructure characteristics. Properties are not namespaced and represent common concepts that apply across vendors and platforms.

Use properties for:

• Generic infrastructure attributes (CPU count, RAM size, disk capacity)
• Network configuration (IP addresses, MAC addresses, VLANs)
• Physical characteristics (rack position, power consumption, dimensions)
• Common operational metadata (hostname, DNS name, serial number)

Properties example:

{
  "id": "dell::MXP-SRV-001",
  "type": "compute.server",
  "provider": {
    "name": "dell",
    "type": "PowerEdge R770",
    "native_id": "MXP-SRV-001"
  },
  "properties": {
    "hostname": "mxp-srv-001.internal.osiris.com.acme",
    "rack_unit_start": 10,
    "rack_unit_height": 2,
    "power_consumption_watts": 450,
    "service_tag": "ABC1234",
    "cpu": {
      "model": "Intel Xeon Gold 6430",
      "cores": 32,
      "threads": 64,
      "count": 2
    },
    "ram_gb": 512
  }
}

Properties are generic: The fields above (hostname, rack position, CPU specs) are universally applicable. Any consumer can understand “rack_unit_start” regardless of whether the server is Dell, HPE, or Supermicro.

8.1.2 Extensions object

The extensions object contains namespaced vendor-specific, platform-specific or organization-specific data that extends beyond core OSIRIS semantics. Each top-level key in extensions MUST be a namespace string starting with osiris. and the value MUST be a JSON object.

Use extensions for:

• Vendor-specific features (AWS detailed monitoring, VMware Fault tolerance)
• Platform-specific identifiers (Azure subscription IDs, GCP project IDs)
• Proprietary configuration (vendor-specific management interfaces)
• Organization-specific metadata (cost centers, compliance tags, custom workflows)

Extensions example:

{
  "id": "aws::i-0abc123def4567890",
  "type": "compute.vm",
  "provider": {
    "name": "aws",
    "type": "AWS::EC2::Instance",
    "native_id": "i-0abc123def4567890",
    "region": "us-east-1"
  },
  "properties": {
    "vcpus": 2,
    "memory_gb": 4,
    "ip_addresses": {
      "private_ip": ["10.0.1.10"]
    }
  },
  "extensions": {
    "osiris.aws": {
      "detailed_monitoring": true,
      "ebs_optimized": false,
      "placement": {
        "availability_zone": "us-east-1a",
        "tenancy": "default"
      },
      "iam_instance_profile": "arn:aws:iam::123456789012:instance-profile/web-server"
    },
    "osiris.custom.billing": {
      "cost_center": "engineering",
      "project_code": "web-platform-2024",
      "budget_owner": "[email protected]"
    }
  }
}

Extensions are namespaced: The osiris.aws prefix clearly identifies AWS-specific data, while osiris.custom.billing identifies organization-specific billing metadata.

8.1.3 Decision framework

When adding data to a resource, follow this decision tree:

Is this data universally applicable across vendors?
+--YES > Use properties
+--NO  > Is this vendor/platform-specific?
    +--YES > Use extensions.osiris.<vendor>
    +--NO  > Is this organization-specific?
        +--YES > Use extensions.osiris.com.<org>.<domain>

Examples:

8.1.4 Extension field structure

Extension objects MUST be nested under the osiris.<namespace> key. Producers MUST NOT place extension data directly under extensions without a namespace prefix.

Correct:

"extensions": {
  "osiris.aws": {
    "detailed_monitoring": true
  }
}

Incorrect:

"extensions": {
  "detailed_monitoring": true
}

Rationale: Namespacing prevents collision between extensions from different sources and enables consumers to selectively process extensions they understand.

8.1.4.1 Extension object key style

Extension objects SHOULD follow these key naming conventions:

Recommended practices:

• Use snake_case for keys: detailed_monitoring, cost_center, project_code
• Prefer nested objects over dotted keys: Safer for document databases (MongoDB, etc.)
• Use consistent naming within a namespace: Maintain style across all extensions in the same namespace

GOOD example: Recommended style

"extensions": {
  "osiris.aws": {
    "detailed_monitoring": true,      
    "placement": {                     
      "availability_zone": "us-east-1a",
      "partition_number": null
    },
    "iam_instance_profile": {         
      "arn": "arn:aws:iam::123456789012:instance-profile/web",
      "id": "AIPAI23HZ27SI6FQMGNQ2"
    }
  }
}

BAD example: Discouraged dotted keys

"extensions": {
  "osiris.aws": {
    "placement.availability_zone": "us-east-1a",
    "placement.partition_number": null
  }
}

Rationale: Dotted keys can cause issues with document databases that interpret dots as nesting operators. Using actual nested objects is safer and more widely compatible.

Exception: Vendor-native shapes When exporting lossless representations of vendor APIs, producers MAY preserve the vendor’s native key style (camelCase, PascalCase, etc.) if explicitly documented:

"extensions": {
  "osiris.aws.raw": {
    "DetailedMonitoring": true,
    "EbsOptimized": false
  }
}

If using vendor-native shapes, producers SHOULD:

• Use a sub-namespace (e.g. osiris.aws.raw) to signal non-standard casing
• Document the preserved format
• Consider providing both normalized and raw representations

8.1.5 Multiple extension namespaces

A single resource MAY contain extensions from multiple namespaces. Each namespace is independent.

Example:

{
  "id": "vmware::vm-web-001",
  "type": "compute.vm",
  "extensions": {
    "osiris.vmware": {
      "fault_tolerance": false,
      "tools_version": "12.0.0",
      "vmx_version": "19"
    },
    "osiris.com.acme.monitoring": {
      "alert_policy": "critical",
      "on_call_team": "operations"
    },
    "osiris.com.acme.compliance": {
      "pci_scope": true,
      "data_classification": "restricted"
    }
  }
}

Each namespace is processed independently. A consumer that understands osiris.vmware can use that data while safely ignoring osiris.com.acme.monitoring and osiris.com.acme.compliance.

[!NOTE] This example uses organization-specific namespaces (osiris.com.acme.*) for production extensions. For short-lived experiments, producers MAY use osiris.custom.*, but should migrate to organization-specific namespaces when extensions stabilize.

8.1.6 Provider-specific metadata vs extensions

The provider object contains metadata about the resource’s origin (provider name, native ID, region, account). The extensions object contains additional vendor-specific properties or features of the resource itself.

Provider object (origin metadata):

"provider": {
  "name": "aws",
  "type": "AWS::EC2::Instance",
  "native_id": "i-0abc123",
  "region": "us-east-1",
  "account": "123456789012"
}

Extensions object (vendor-specific features):

"extensions": {
  "osiris.aws": {
    "detailed_monitoring": true,
    "ebs_optimized": false
  }
}

Rule of thumb: If the data answers “where is this resource?” or “what is the provider’s identifier?”, it belongs in provider. If the data answers “what vendor-specific features does this resource have?”, it belongs in extensions.

8.1.7 Forward compatibility

Consumers MUST accept resources with unknown extension namespaces. Consumers MAY ignore extension data they do not recognize.

Producers SHOULD ensure that core topology (resources, connections, groups) is understandable even if consumers ignore all extension data.

Example: A consumer that does not understand osiris.aws extensions can still process the resource:

{
  "id": "aws::i-0abc123",
  "type": "compute.vm",
  "provider": { "name": "aws", "native_id": "i-0abc123" },
  "properties": { "vcpus": 2, "memory_gb": 4 },
  "extensions": {
    "osiris.aws": { "detailed_monitoring": true }
  }
}

The consumer can identify the resource (aws::i-0abc123), its type (compute.vm) and its basic properties (vcpus, memory_gb) without understanding AWS-specific extensions.

8.2 Vendor-specific extensions

Vendor-specific extensions are additional resource attributes that are meaningful only within a specific vendor’s ecosystem. These attributes belong in the extensions object under the vendor’s namespace.

8.2.1 Vendor namespace structure

Vendor namespaces follow the pattern osiris.<vendor>, where <vendor> is a canonical lowercase identifier for the platform or vendor.

A vendor namespace key in extensions MUST map to a JSON object.

Well-known vendor namespaces examples (non-exhaustive):

Producers SHOULD use consistent canonical identifiers for well-known vendors. Organization-specific namespaces SHOULD use domain-scoped namespaces (see section 8.4.3).

8.2.2 AWS specific extensions

AWS resources often have features specific to the AWS ecosystem. These belong under osiris.aws.

Example: EC2 instance with AWS-specific properties

{
  "id": "aws::i-0abc123def4567890",
  "type": "compute.vm",
  "name": "web-server-prod-01",
  "provider": {
    "name": "aws",
    "type": "AWS::EC2::Instance",
    "native_id": "i-0abc123def4567890",
    "region": "us-east-1",
    "account": "123456789012"
  },
  "properties": {
    "vcpus": 2,
    "memory_gb": 4,
    "instance_type": "t3.medium"
  },
  "extensions": {
    "osiris.aws": {
      "detailed_monitoring": true,
      "ebs_optimized": false,
      "ena_support": true,
      "hypervisor": "xen",
      "placement": {
        "availability_zone": "us-east-1a",
        "tenancy": "default",
        "partition_number": null
      },
      "iam_instance_profile": {
        "arn": "arn:aws:iam::123456789012:instance-profile/web-server",
        "id": "AIPAI23HZ27SI6FQMGNQ2"
      }
    }
  }
}

8.2.3 Azure specific extensions

Azure resources may include platform-specific metadata under osiris.azure.

Example: Azure VM with platform-specific properties

{
  "id": "azure::/subscriptions/sub-123/resourceGroups/rg-prod/providers/Microsoft.Compute/virtualMachines/web-vm-01",
  "type": "compute.vm",
  "name": "web-vm-01",
  "provider": {
    "name": "azure",
    "type": "Microsoft.Compute/virtualMachines",
    "native_id": "/subscriptions/sub-123/resourceGroups/rg-prod/providers/Microsoft.Compute/virtualMachines/web-vm-01",
    "region": "eastus",
    "subscription_id": "sub-123",
    "resource_group": "rg-prod"
  },
  "properties": {
    "vm_size": "Standard_D2s_v3",
    "vcpus": 2,
    "memory_gb": 8
  },
  "extensions": {
    "osiris.azure": {
      "priority": "Regular",
      "eviction_policy": null,
      "license_type": "Windows_Server",
      "zones": ["1"],
      "managed_disk_type": "Premium_LRS"
    }
  }
}

8.2.4 GCP specific extensions

GCP resources often expose Google-specific features such as preemptibility/spot behavior, Shielded VM settings, service accounts and metadata flags. These belong under osiris.gcp.

Example: GCE instance with GCP-specific properties

{
  "id": "gcp::projects/acme-prod/zones/us-central1-a/instances/web-01",
  "type": "compute.vm",
  "name": "web-01",
  "provider": {
    "name": "gcp",
    "type": "compute#instance",
    "native_id": "projects/acme-prod/zones/us-central1-a/instances/web-01",
    "region": "us-central1",
    "account": "acme-prod"
  },
  "properties": {
    "vcpus": 2,
    "memory_gb": 8,
    "machine_type": "e2-standard-2"
  },
  "extensions": {
    "osiris.gcp": {
      "zone": "us-central1-a",
      "preemptible": false,
      "spot": true,
      "termination_action": "STOP",
      "shielded_vm": {
        "secure_boot": true,
        "vtpm": true,
        "integrity_monitoring": true
      },
      "service_accounts": [
        {
          "email": "[email protected]",
          "scopes": [
            "https://www.googleapis.com/auth/cloud-platform"
          ]
        }
      ],
      "scheduling": {
        "automatic_restart": false,
        "on_host_maintenance": "TERMINATE"
      },
      "labels": {
        "env": "prod",
        "app": "web"
      }
    }
  }
}

8.2.5 VMware specific extensions

VMware environments have specific features like Fault Tolerance, vMotion and DRS.

Example: VMware VM with ESXi-specific properties

{
  "id": "vmware::vm-web-001",
  "type": "compute.vm",
  "name": "web-001",
  "provider": {
    "name": "vmware",
    "native_id": "vm-web-001",
    "region": "mxp-datacenter"
  },
  "properties": {
    "vcpus": 4,
    "memory_gb": 16,
    "guest_os": "ubuntu64Guest"
  },
  "extensions": {
    "osiris.vmware": {
      "tools_status": "toolsOk",
      "tools_version": "12.0.0",
      "fault_tolerance": false,
      "vmx_version": "19",
      "drs_behavior": "fullyAutomated",
      "cpu_hot_add_enabled": false,
      "memory_hot_add_enabled": false
    }
  }
}

8.2.6 Proxmox specific extensions

Proxmox environments have platform-specific capabilities and metadata such as VMID, node placement, HA state, QEMU machine type and storage backend details.

Example: Proxmox VM with Proxmox-specific properties

{
  "id": "proxmox::vm-web-001",
  "type": "compute.vm",
  "name": "web-001",
  "provider": {
    "name": "proxmox",
    "native_id": "101",
    "region": "mxp-datacenter"
  },
  "properties": {
    "vcpus": 4,
    "memory_gb": 16,
    "guest_os": "ubuntu"
  },
  "extensions": {
    "osiris.proxmox": {
      "vmid": 101,
      "node": "pve-01",
      "ha_enabled": true,
      "ha_state": "started",
      "qemu_machine": "pc-q35-8.1",
      "bios": "ovmf",
      "tags": ["prod", "web"],
      "storage": {
        "backend": "ceph",
        "pool": "rbd",
        "volumes": [
          {
            "id": "vm-101-disk-0",
            "size_gb": 60,
            "type": "scsi"
          }
        ]
      }
    }
  }
}

8.2.7 On-premise vendor extensions

Physical infrastructure from vendors like Dell, Arista, or Cisco may include hardware-specific extensions.

Example: Dell server with iDRAC management extensions

{
  "id": "dell::MXP-SRV-R01-001",
  "type": "compute.server",
  "name": "MXP-SRV-R01-001",
  "provider": {
    "name": "dell",
    "type": "PowerEdge R770",
    "native_id": "MXP-SRV-R01-001"
  },
  "properties": {
    "service_tag": "ABC1234",
    "rack_unit_start": 10,
    "cpu": {
      "model": "Intel Xeon Gold 6430",
      "cores": 32,
      "count": 2
    },
    "ram_gb": 512
  },
  "extensions": {
    "osiris.dell": {
      "idrac_version": "5.10.00.00",
      "idrac_ip": "10.0.100.10",
      "lifecycle_controller_version": "4.10.10.10",
      "bios_version": "2.15.0",
      "system_id": 2137
    }
  }
}

Example: Arista switch with EOS-specific extensions

{
  "id": "arista::MXP-LEAF-01",
  "type": "network.switch",
  "name": "MXP-LEAF-01",
  "provider": {
    "name": "arista",
    "type": "DCS-7050X3-48YC12",
    "native_id": "MXP-LEAF-01"
  },
  "properties": {
    "management_ip": "10.0.10.11",
    "site": "mxp-datacenter",
    "rack": "R05",
    "rack_unit_start": 22,
    "interfaces": [
      { "name": "Ethernet1", "type": "physical", "speed": "100G", "admin_status": "up", "oper_status": "up" },
      { "name": "Ethernet2", "type": "physical", "speed": "100G", "admin_status": "up", "oper_status": "up" },
      { "name": "Ethernet49", "type": "physical", "speed": "25G", "admin_status": "up", "oper_status": "down" }
    ]
  },
  "extensions": {
    "osiris.arista": {
      "eos_version": "4.30.2F",
      "system_mac": "00:1c:73:aa:bb:cc",
      "serial_number": "JPE12345678",
      "mlag": {
        "enabled": true,
        "domain_id": "MLAG01",
        "peer_link": "Port-Channel1000",
        "peer_address": "192.0.2.2",
        "state": "active"
      },
      "vxlan": {
        "enabled": true,
        "vtep_ip": "10.0.255.11"
      },
      "hardware": {
        "supervisor": "fixed",
        "transceivers_present": 28
      }
    }
  }
}

8.2.8 Extension data types

Extension values MAY be any valid JSON type: strings, numbers, booleans, objects, arrays, or null. Producers SHOULD use appropriate JSON types that reflect the data semantics.

Type examples:

"extensions": {
  "osiris.aws": {
    "detailed_monitoring": true,
    "placement_group": null,
    "cpu_credits": "unlimited",
    "network_performance": "Up to 5 Gigabit",
    "hibernation_configured": false,
    "metadata_options": {
      "http_tokens": "optional",
      "http_put_response_hop_limit": 1
    },
    "block_device_mappings": [
      {
        "device_name": "/dev/sda1",
        "ebs": {
          "volume_id": "vol-0abc123",
          "delete_on_termination": true
        }
      }
    ]
  }
}

8.2.9 Extension stability

Extension schemas MAY evolve independently of the core OSIRIS specification. Producers SHOULD maintain backward compatibility within an extension namespace when possible.

If breaking changes to an extension schema are unavoidable, producers MAY version the extension namespace:

"extensions": {
  "osiris.aws.v1": { ... },
  "osiris.aws.v2": { ... }
}

Consumers SHOULD prefer the highest version they understand and gracefully handle unknown versions.

8.3 Custom resource types

Custom resource types enable producers to represent vendor-specific or organization-specific infrastructure that does not map cleanly to standard types defined in Chapter 7. Custom types use the osiris.<namespace> prefix to distinguish them from standard types.

8.3.1 When to create custom types

Producers SHOULD use standard resource types (Chapter 7) whenever possible. Custom types are appropriate when:

1. No standard type exists and the resource semantics are vendor-specific
2. Standard type exists but semantics differ significantly
3. Vendor-specific features are essential to understanding the resource
4. Organization-specific infrastructure requires custom representation

Decision tree:

Does a standard type capture the resource's primary function?
+-- YES > Use the standard type
+-- NO  > Does a vendor-specific type exist for this resource?
    +-- YES > Use the vendor type (osiris.<vendor>.*)
    +-- NO  > Does this resource represent organization-specific infrastructure?
        +-- YES > Create custom type (osiris.com.<org>.*)

8.3.2 Custom type naming

Custom resource types MUST use the osiris.<namespace> prefix followed by dot-separated segments describing the resource type. Type identifiers MUST follow the same format rules as standard types (see Chapter 4, section 4.2.3):

• MUST be in lowercase letters and digits only
• MUST have dot (.) as the only separator
• MUST have no underscores, hyphens, or spaces
• MUST have no leading, trailing, or consecutive dots

GOOD valid custom types:

osiris.aws.lambda.edge
osiris.azure.cosmosdb
osiris.vmware.vsan
osiris.cisco.aci.fabric
osiris.com.acme.widget.v2

BAD invalid custom types:

osiris.aws.vpc_peering
osiris.azure.cosmos-db
osiris.Acme.Widget
.osiris.aws.lambda
osiris.aws..lambda

8.3.3 Vendor-specific types

Vendor-specific types use the pattern osiris.<vendor>.* where <vendor> is a well-known identifier.

Example: AWS Lambda@Edge (distinct from standard serverless)

{
  "id": "aws::edge-func-auth",
  "type": "osiris.aws.lambda.edge",
  "name": "cloudfront-auth",
  "provider": {
    "name": "aws",
    "type": "AWS::Lambda::Function",
    "native_id": "edge-func-auth",
    "region": "us-east-1"
  },
  "properties": {
    "runtime": "python3.11",
    "memory_mb": 128
  },
  "extensions": {
    "osiris.aws": {
      "edge_region": "us-east-1",
      "cloudfront_distribution": "E1234567890ABC"
    }
  }
}

Rationale: Lambda@Edge executes at CloudFront edge locations with different semantics than standard Lambda functions. The custom type osiris.aws.lambda.edge explicitly signals these distinct semantics.

Alternative approach: If edge execution is a deployment detail rather than a fundamental semantic difference, producers MAY use the standard type compute.function.serverless and place edge-specific metadata in extensions:

{
  "id": "aws::edge-func-auth",
  "type": "compute.function.serverless",
  "extensions": {
    "osiris.aws": {
      "execution_environment": "edge",
      "edge_region": "us-east-1"
    }
  }
}

Producers SHOULD document their type selection rationale.

8.3.4 Organization-specific types

Organizations MAY define custom types for proprietary or organization-specific infrastructure using reverse domain notation: osiris.com.<organization>.*.

Example: Organization-specific monitoring appliance

{
  "id": "custom::monitoring-appliance-01",
  "type": "osiris.com.acme.monitoring.appliance",
  "name": "monitoring-appliance-01",
  "provider": {
    "name": "acme",
    "type": "Acme Monitoring Appliance v3",
    "native_id": "monitoring-appliance-01"
  },
  "properties": {
    "rack_unit_start": 5,
    "power_consumption_watts": 200
  },
  "extensions": {
    "osiris.com.acme": {
      "firmware_version": "3.2.1",
      "collector_count": 4,
      "retention_days": 90
    }
  }
}

Reverse domain notation:

8.3.5 Custom type documentation

Producers that use custom types SHOULD document:

• Type semantics and purpose
• When to use the custom type vs standard types
• Properties and extensions specific to the type
• Example usage

Documentation example:

Type: osiris.com.acme.widget

Purpose: Represents Acme Corp's proprietary network widget appliance

Use this type when:
- The resource is an Acme Widget hardware appliance
- The appliance provides both routing and deep packet inspection

Standard type alternative:
- Use network.router if only routing functionality is relevant
- Use security.firewall if only DPI functionality is relevant

Required properties:
- firmware_version (string): Widget firmware version
- widget_mode (string): "router" | "firewall" | "hybrid"

Extensions (osiris.com.acme):
- license_key (string): Widget license key
- management_vlan (integer): Management VLAN ID

8.3.6 Consumer handling of custom types

Consumers MUST accept resources with unrecognized custom types. Consumers MAY treat unrecognized types as generic resources based on the namespace:

• osiris.aws.* > Assume AWS-specific resource
• osiris.azure.* > Assume Azure-specific resource
• osiris.com.<org>.* > Assume organization-specific resource

Consumers SHOULD preserve custom type information when re-exporting or transforming topology data.

8.3.7 Type stability and evolution

Custom types MAY evolve over time. Producers SHOULD maintain semantic stability within a custom type when possible.

If a custom type’s semantics change significantly, producers MAY:

1. Create a new type with a version suffix (e.g. osiris.aws.lambda.edge.v2)
2. Deprecate the old type with a documented migration path
3. Support both types during a transition period

8.4 Namespacing

Namespace management prevents collision between extensions from different sources and enables safe evolution of the OSIRIS ecosystem.

Governance boundary (OSIRIS governed vs vendor defined)

OSIRIS governs:

• Namespace format rules (e.g. osiris.<vendor> and reverse-domain organization namespaces)
• Registry and collision-avoidance rules for well-known namespaces

OSIRIS does not govern:

• The internal structure and semantics of extensions["osiris.<vendor>"] payloads
• Provider-specific state values and other opaque vendor enums

Extension payloads may evolve independently of the OSIRIS specification. Consumers MUST treat unknown extension fields as opaque and MUST ignore what they do not understand.

8.4.1 Namespace format

Extension namespaces MUST follow the pattern osiris.<identifier> where <identifier> is a dot-separated lowercase string.

Namespace format rules:

• MUST start with osiris. prefix
• MUST use lowercase letters, digits and dots only
• MUST have no underscores, hyphens, or spaces
• MUST have no consecutive dots
• MUST have minimum two segments (e.g. osiris.aws, not just osiris)

GOOD examples of valid namespaces:

osiris.aws
osiris.azure.devtest
osiris.com.acme
osiris.custom.billing

BAD examples of invalid namespaces:

aws
osiris.AWS
osiris.acme_corp
osiris.
osiris_

8.4.2 Registered well-known namespaces

The osiris. prefix is reserved by this specification for namespaces that follow OSIRIS naming rules and collision-avoidance conventions.

OSIRIS governs the namespace rules and (when applicable) the registry of well-known namespaces. OSIRIS does not govern the internal semantics of vendor or organization-specific payloads carried under these namespaces.

The following vendor namespaces are registered as well-known prefixes to encourage consistent producer behavior for infrastructure management systems (hyperscalers, cloud providers, virtualization, networking, compute, storage, OT/industrial platforms).

Hyperscalers and Cloud providers

Virtualization & HCI

Networking & security

[!NOTE] For systems where hardware and software are decoupled (e.g. SONiC running on white-box hardware), producers SHOULD use the software/NOS namespace (e.g. osiris.sonic) for vendor extensions and record the physical platform under properties.hardware_vendor, properties.model, and properties.platform (e.g. x86_64-accton_as7326_56x-r0) when available.

Compute & storage vendors

Enterprise platforms & ITSM/CMDB

OT & Industrial ecosystems

Governance scope (namespaces vs semantics)

OSIRIS governs the namespace rules and (when applicable) the registry policy for well-known namespace prefixes under extensions (e.g. collision avoidance, canonical vendor identifiers).

OSIRIS does not govern the internal semantics of vendor/organization extensions (i.e. the fields inside extensions["osiris.<vendor>"]) and does not govern provider-defined enumerations such as state. Consumers MUST treat such values as opaque.

[!NOTE]

• These namespaces are intended to standardize vendor-specific extension placement for commonly used infrastructure management systems.
• Third-party producers/parsers MAY emit these namespaces when exporting resources sourced from the corresponding vendor/platform (e.g. a discovery tool exporting AWS resources may emit extensions.osiris.aws).
• Not all canonical provider.name values require a registered vendor namespace. Technologies and software components (e.g. databases, middleware, application frameworks) can be valid provider.name values without requiring a well-known osiris.<vendor> extension namespace.

Rationale: This list focuses on systems that manage infrastructure resources (hyperscalers and cloud platforms, virtualization stacks, networking/security, compute/storage vendors and OT/industrial ecosystems). Keeping the registry constrained avoids turning the specification into a general catalog of all technologies, while still enabling consistent, interoperable vendor extension usage.

8.4.3 Organization namespaces

Organizations creating proprietary extensions SHOULD use a domain-scoped namespace to avoid collisions:

• osiris.com.<organization>
• osiris.org.<organization>
• osiris.net.<organization>
• osiris.edu.<institution>

Examples:

Domain-scoped namespaces are collision-resistant because they are derived from an internet domain controlled by the organization.

8.4.4 Custom namespaces

For short-lived experiments or early community drafts, producers MAY use the osiris.custom.* namespace.

Important: The osiris.custom.* namespace is not collision-resistant. Multiple organizations using osiris.custom.billing will conflict. For any extension intended to persist or be used in production, producers SHOULD use reverse domain notation (e.g. osiris.com.<org>.*).

Recommended usage:

• Experiments/prototypes: osiris.custom.* (temporary)
• Production/persistent: osiris.com.<org>.* (collision-resistant)

Example: Experimental extension (temporary)

"extensions": {
  "osiris.custom.draft.monitoring": {
    "experimental_metric": true,
    "note": "RFC draft for community review"
  }
}

Example: Production extension (recommended)

"extensions": {
  "osiris.com.acme.monitoring": {
    "alert_policy": "critical",
    "on_call_team": "platform-ops"
  }
}

The osiris.custom namespace is appropriate for:

• Proof-of-concept extensions
• Community RFC drafts before standardization
• Short-lived experimental features

Producers SHOULD migrate from osiris.custom.* to organization-specific namespaces when extensions are production-ready.

8.4.5 Namespace registration

For OSIRIS v1.0, namespace registration is informal and community-driven. Organizations are encouraged to:

1. Document their namespace usage publicly (e.g. in a GitHub repository)
2. Publish extension schemas for consumer reference
3. Coordinate with the OSIRIS community to avoid collisions

Future versions of OSIRIS MAY introduce a formal namespace registry.

8.4.6 Namespace collision avoidance

Namespace collisions occur when multiple parties use the same namespace with different semantics. To avoid collisions:

Producers SHOULD:

• Use vendor namespaces (osiris.aws) only for the corresponding vendor
• Use reverse domain notation for organization namespaces
• Document namespace usage publicly
• Avoid reusing existing namespace patterns with different semantics

Consumers SHOULD:

• Accept multiple extension namespaces in the same resource
• Process known namespaces and ignore unknown ones
• Log warnings for unexpected namespace combinations

8.4.7 Namespace versioning

If extension semantics change significantly, producers MAY version namespaces:

"extensions": {
  "osiris.aws.v1": {
    "detailed_monitoring": true
  },
  "osiris.aws.v2": {
    "monitoring": {
      "level": "detailed",
      "interval_seconds": 60
    }
  }
}

Versioned namespaces enable gradual migration. Producers SHOULD:

• Support old and new versions during a transition period
• Document migration paths from old to new versions
• Provide examples showing both versions

8.4.8 Forward compatibility

Consumers MUST accept resources with unknown extension namespaces.

Consumers encountering unknown namespaces SHOULD:

• Log the unknown namespace for debugging
• Continue processing known fields and namespaces
• Preserve unknown namespace data when re-exporting

This forward compatibility ensures that new extensions do not break existing consumers.

8.5 Extension best practices

8.5.1 For producers

Use standard fields and types first:

• Prefer standard types (Chapter 7) over custom types
• Prefer properties over extensions for generic data
• Only create custom types when standard types are insufficient

Document extensions:

• Publish extension schemas for consumer reference
• Provide examples showing typical usage
• Explain when to use extensions vs standard fields
• Version extension schemas if semantics change

Validate extension data:

• Ensure extension data is well-formed JSON
• Use appropriate JSON types (boolean, number, string, object, array)
• Validate data against extension schemas before emitting

Maintain stability:

• Avoid breaking changes to extension schemas when possible
• Use versioned namespaces for incompatible changes
• Provide migration paths for deprecated extensions

8.5.2 For consumers

Accept unknown extensions:

• Do not reject resources with unrecognized extension namespaces
• Process known fields and ignore unknown extensions
• Log unknown extensions for debugging

Preserve extension data:

• When re-exporting topology, preserve extension fields
• Do not strip extensions consumers do not understand

Handle missing extensions gracefully:

• Do not assume extension fields are present
• Provide defaults for missing extension values
• Degrade gracefully when extension data is unavailable

Provide configuration:

• Enable users to control extension processing (enable/disable specific namespaces)
• Allow selective extension filtering for privacy or security
• Support extension validation against schemas

8.5.3 Common patterns

Pattern 1: Vendor-specific feature flags

"extensions": {
  "osiris.aws": {
    "detailed_monitoring": true,
    "ebs_optimized": false
  }
}

Pattern 2: Organization metadata

"extensions": {
  "osiris.com.acme.billing": {
    "cost_center": "engineering",
    "project": "web-platform"
  },
  "osiris.com.acme.compliance": {
    "pci_scope": true,
    "sox_audited": false
  }
}

Pattern 3: Provider console/management references (non-primary identity)

"extensions": {
  "osiris.azure": {
    "portal_url": "https://portal.azure.com/#@/resource/subscriptions/.../resourceGroups/.../providers/...",
    "zones": ["1", "2"]
  }
}

[!NOTE] Provider identifiers used to locate the resource (subscription/project/account, region, native resource ID) SHOULD be placed in provider. Use extensions for vendor UX links, secondary references, or tool-specific foreign keys.

Pattern 4: Hardware management interfaces

"extensions": {
  "osiris.dell": {
    "idrac_ip": "10.0.100.10",
    "idrac_version": "5.10.00.00",
    "idrac_console_url": "https://10.0.100.10"
  }
}

8.6 Summary

The OSIRIS extension mechanism balances flexibility and interoperability:

• Properties contain generic infrastructure attributes applicable across vendors
• Extensions contain namespaced vendor-specific, platform-specific, or organization-specific data
• Custom types represent resources that do not map to standard types
• Namespaces prevent collisions and enable ecosystem growth

Key principles:

• Standard first, extend selectively
• Namespace all extensions (osiris.<namespace>)
• Consumers must accept unknown extensions
• Producers should document extension semantics

The extension mechanism enables the OSIRIS ecosystem to evolve without fragmenting the core specification. Producers can represent vendor-specific infrastructure while maintaining interoperability with consumers that understand only core OSIRIS fields.