What is OSIRIS JSON

What OSIRIS is

OSIRIS (Open Standard for Infrastructure Resource Interchange Schema) defines a vendor-neutral JSON format for describing infrastructure resources, their properties and their topological relationships across heterogeneous environments with an extension path for OT where applicable.

As an interchange schema, OSIRIS normalizes exports from diverse sources and enables portable consumption by tools dedicated to diagramming, documentation, inventory/CMDB workflows, audit evidence and integrations without requiring each consumer to implement and maintain vendor-specific parsers.

OSIRIS defines a canonical JSON schema that acts as a neutral middleware between infrastructure data sources and consuming applications. Instead of embedding vendor-specific parsing logic into every tool, OSIRIS adopts a translation-layer approach:

PRODUCERS (parsers, translators, discovery agents) translate source/vendor representations into OSIRIS documents.
CONSUMERS (diagramming tools, CMDBs, IPAMs, DCIMs, documentation pipelines) read and process a single, well-defined schema.

This decouples data sources from consuming applications, reducing integration complexity from S×C (S sources × C consumers) to P+C (P producers + C consumers).

This decouples data sources from applications and reduces integration complexity. In an environment with S source systems and C consuming applications, integration effort shifts from S×C direct mappings to S producer mappings (source > OSIRIS) plus C consumer mappings (OSIRIS > application).

The challenge

Infrastructure data is exposed through vendor-specific formats and models, with inconsistent semantics for equivalent concepts identity, properties, relationships and hierarchy. In mixed environments spanning hyperscalers, public cloud, on-prem systems and OT infrastructure, the problem compounds. The result is fragmented sometime high-cost tooling, inconsistent exports and documentation with fragmented or low quality topology that quickly becomes outdated.

crisis_alert

Fragmentation consequences

crisis_alert

Integration complexity

Tools must maintain vendor-specific adapters, mappings and translators.
crisis_alert

High maintenance cost

Vendor-specific APIs and data models evolve, forcing continuous updates to parsers and integrations blasting costs over time.
crisis_alert

Inconsistent topology semantics

Relationships may be implicit, incomplete, or represented differently across sources making topology hard to compare and reuse.
crisis_alert

Documentation drift

Manual translation is fragile; documentation is poor and diagrams are low-quality most of time with incomprehensible icons and cahotic flows quickly fall out of date.
crisis_alert

Tribal knowledge risk

Without a shared standard, critical context often lives in people’s heads. When people leave, that knowledge goes with them and systems become harder to understand and operate.
crisis_alert

Lock-in risk

Organizations may become dependent on closed, vendor-specific, or paid normalization solutions that are hard to replace or may not be maintained with a long-term vision.

verified

OSIRIS Open Standard approach

verified

Neutral JSON interchange schema

A vendor-neutral format for exchanging infrastructure resources and topology between systems.
verified

Producers translate source exports into OSIRIS documents

Parsers/translators/discovery agents map native representations into the OSIRIS schema.
verified

Consumers implement one schema for many sources

Tools can read a single, well-defined document format across different environments.
verified

Explicit, first-class topology relationships

Connections, dependencies, containment, and grouping are represented directly so a snapshot can describe what exists and how it relates at a point in time.
verified

Forward compatibility through safe ignoring of unknown fields

Consumers can ignore unknown properties and extensions without breaking basic processing.
verified

Extensions are natively supported

A defined mechanism allows vendors and users to enrich documents without breaking interoperability.

Core capabilities

schema Unified design

Built for heterogeneous IT environments, with a clear extension path for OT and other domains as adoption grows.

hub Explicit relationships model

First-class representation of connections, dependencies, containment, and other topology relationships.

account_tree Grouping constructs

Support for logical and physical grouping that reflects real organizational and architectural structures without forcing a single taxonomy.

dns Provider attribution

Resources preserve traceability to their source system/provider while using a standardized, vendor-neutral representation.

extension Extensibility

A defined mechanism for vendor-specific properties and custom resource types without breaking compatibility.

verified_user Three-Level validation

Structural (schema), semantic and domain validation improving consistency and data quality when validation tooling is applied.

Design principles

Static snapshot format

OSIRIS is a static snapshot interchange format. It captures what exists and how it relates at a point in time. It was not designed as a real-time monitoring system, a deployment tool, or an Infrastructure-as-Code engine.

What OSIRIS is NOT

close Not real-time telemetry and monitoring

OSIRIS describes topology and inventory state, not time-series metrics, logs or observability data. Projects like Prometheus, Grafana, Zabbix, OpenTelemetry address telemetry concerns.

close Not infrastructure deployment and orchestration

OSIRIS is not an infrastructure-as-code language or a deployment specification. Projects like Terraform, CloudFormation or TOSCA Oasis address deployment workflows.

close Not configuration management

OSIRIS does not define or enforce desired state configuration for resources. Configuration management systems like Ansible, Puppet, Chef, Salt serve this purpose.

close Not change tracking and history

OSIRIS represents a point-in-time snapshot. Tracking changes over time is the responsibility of producing and consuming systems.

close Not authentication, authorization and access policies

OSIRIS may carry metadata describing boundaries or ownership, but it does not define access control mechanisms or policies.

close Cost and billing information

Detailed billing and financial modeling are outside the core schema scope, although cost-related metadata may be included by extension.

Document structure

OSIRIS documents are JSON objects. In Specification v1.0.0, the top-level object is defined around three fields: version, metadata, and topology. An optional $schema field may be included to reference the schema URI.

[!NOTE] This is a top-level OSIRIS schema outline. $defs are omitted here for top-level readability, refer to the canonical URI for the full schema.

The schema defines:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema#",
  "$id": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "title": "Core OSIRIS JSON Schema v1.0",
  "description": "OSIRIS Open Standard for Infrastructure Resource Interchange Schema. This schema encodes baseline interoperability requirements; additional semantic rules (e.g. referential integrity, uniqueness) are validated by tooling.",
  "type": "object",
  "required": [
    "version",
    "metadata",
    "topology"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Optional JSON Schema dialect reference for OSIRIS documents.",
      "format": "uri"
    },
    "version": {
      "type": "string",
      "description": "OSIRIS specification version of this document (semver). For the v1.0 schema endpoint, any 1.x.y is allowed.",
      "pattern": "^1\\.[0-9]+\\.[0-9]+$"
    },
    "metadata": {
      "$ref": "#/$defs/metadata"
    },
    "topology": {
      "$ref": "#/$defs/topology"
    }
  },
  "additionalProperties": true,
  "$defs": {
    "osirisType": { },
    "providerName": { },
    "namespaceKey": { },
    "tags": { },
    "freeformObject": { },
    "extensions": { },
    "provider": { },
    "resource": { },
    "connectionDirection": { },
    "connectionType": { },
    "connection": { },
    "group": { },
    "topology": { },
    "metadataGenerator": { },
    "metadataScope": { },
    "metadata": { }
  }
}

topology.resources

Uniquely identifiable infrastructure entities with properties and provider attribution.

topology.connections

Explicit relationships and direction between resources (network, dependency, containment, data flow, etc.).

topology.groups

Logical or physical collections that organize resources (e.g. VPC, subnet, rack, data center).

Validation and interoperability