# OSIRIS JSON — Full LLM Context

> OSIRIS JSON is an open, vendor-neutral specification for portable, point-in-time infrastructure resource and topology snapshots.

Last reviewed: 2026-07-13

## 1. Project Definition

OSIRIS stands for **Open Specification for Infrastructure Resource Interchange Schema**.

OSIRIS JSON defines a vendor-neutral JSON format for describing:

- infrastructure resources;
- document metadata and scope;
- explicit topological relationships;
- logical and physical groups;
- provider provenance;
- vendor- or organization-specific extensions.

The format is intended for heterogeneous environments spanning hyperscalers, cloud and hosting platforms, on-premises compute, networking, storage, virtualization, and selected operational technology environments.

An OSIRIS JSON document describes **what exists and how it relates at a specific point in time**. It is a static interchange artifact rather than a live control plane.

## 2. Authoritative Sources

The following source precedence applies:

1. The **OSIRIS JSON Format Specification** is the authoritative definition of fields, semantics, normative behavior, compatibility, and security requirements.
2. The **OSIRIS JSON Core Schema** is the authoritative structural schema for the corresponding specification version.
3. The **OSIRIS JSON Toolbox Core** is the canonical implementation of validation behavior and structured diagnostics.
4. Producers, consumers, CLI tools, editor integrations, examples, and documentation must remain aligned with the specification and schema.

Authoritative references:

- Specification: https://osirisjson.org/en/specification
- Core schema v1.0: https://osirisjson.org/schema/v1.0/osiris.schema.json
- GitHub organization: https://github.com/osirisjson

## 3. Ecosystem Boundaries

### 3.1 Specification and Core Schema

The specification and schema define the portable OSIRIS JSON document format. They do not discover infrastructure, render diagrams, or connect to vendor systems.

### 3.2 OSIRIS JSON Producers

Producers are read-only applications or components that translate infrastructure data into OSIRIS JSON documents.

A producer may obtain source data from:

- cloud or hosting APIs and CLIs;
- network and infrastructure APIs;
- SSH, NETCONF, or similar protocols;
- hypervisors and management platforms;
- existing JSON, YAML, CSV, inventory, configuration, or state exports;
- selected IT and OT data sources.

The producer lifecycle is:

1. **Discover** source resources and relationships.
2. **Normalize** vendor-specific representations into OSIRIS concepts.
3. **Redact** credentials, authentication material, secrets, and prohibited sensitive values.
4. **Emit** a deterministic OSIRIS JSON document.

First-party producers are primarily implemented in Go, but the specification is language-independent.

Producers do not provision, configure, or mutate the infrastructure they inspect.

No AI platform, agent, MCP server, SaaS middleware, or OSIRIS-operated intermediary service is required to generate a document. The producer runs within an environment selected and controlled by the operator.

The generated file remains local unless the owner chooses to move, integrate, or share it.

Producer documentation:

- Getting started: https://docs.osirisjson.org/osiris-producers/getting-started/
- Installation: https://docs.osirisjson.org/osiris-producers/installation/
- Security: https://docs.osirisjson.org/osiris-producers/security/
- Producer guidelines: https://docs.osirisjson.org/developer-guidelines/producers/producer-guidelines/
- Writing a producer: https://docs.osirisjson.org/developer-guidelines/producers/writing-a-producer/

### 3.3 OSIRIS JSON Toolbox

The Toolbox validates and processes OSIRIS JSON documents locally. It does not discover infrastructure and does not replace a producer.

Core packages:

- `@osirisjson/core`: canonical validation engine;
- `@osirisjson/cli`: local and CI/CD command-line interface;
- `@osirisjson/sdk`: reusable TypeScript types and tooling integration helpers.

Toolbox documentation:

- CLI: https://docs.osirisjson.org/validate/toolbox-cli/
- Validation levels: https://docs.osirisjson.org/validate/validation-levels/
- Architecture guidelines: https://docs.osirisjson.org/developer-guidelines/architecture/

### 3.4 OSIRIS JSON Consumers

OSIRIS JSON Consumers read OSIRIS JSON documents and generate downstream outputs. The project currently describes consumer candidates under development for:

- architecture documentation reports;
- audit reports;
- snapshot diff views;
- automatic topology generation and updates.

Consumer documentation:

- https://docs.osirisjson.org/osiris-consumers/getting-started/

### 3.5 User-Controlled Uses

The generated OSIRIS JSON file is a portable artifact. The owner may use it with independently selected tools and workflows, including:

- CMDB, IPAM, and DCIM reconciliation;
- custom analytics and graph processing;
- migration baselining;
- incident and dependency analysis;
- security review;
- AI platforms, agents, and MCP servers;
- internal or third-party integrations.

These are optional uses of the document. AI, MCP, SaaS, CMDB, IPAM, DCIM, and third-party platforms are not required dependencies of OSIRIS JSON.

## 4. Scope and Non-Goals

OSIRIS JSON is designed for:

- portable point-in-time infrastructure snapshots;
- normalized resource inventories;
- explicit topology relationships;
- architecture and operational documentation;
- diagram generation;
- audit evidence;
- snapshot comparison and drift analysis;
- systems-of-record integration;
- controlled downstream analysis.

OSIRIS JSON is not:

- a real-time monitoring or telemetry protocol;
- an observability backend;
- an Infrastructure-as-Code deployment language;
- a provisioning or orchestration system;
- a configuration-management platform;
- an authentication or authorization system;
- a live infrastructure control plane;
- a requirement to use AI or any external service.

## 5. Document Structure

The canonical schema uses **JSON Schema Draft 2020-12**.

A minimal OSIRIS JSON document contains three required top-level fields:

```json
{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0",
  "metadata": {
    "timestamp": "2026-07-13T12:00:00Z"
  },
  "topology": {
    "resources": []
  }
}
```

Required top-level fields:

- `version`: OSIRIS specification version in `MAJOR.MINOR.PATCH` form;
- `metadata`: document-level provenance and snapshot context;
- `topology`: resources and optional relationships and groups.

The `$schema` field is optional but recommended for schema-aware tooling.

Unknown top-level and nested fields must be ignored by forward-compatible consumers when the document is otherwise structurally valid.

## 6. Core Concepts

### 6.1 Resources

A resource represents an infrastructure, application, or selected OT entity.

Required resource fields:

- `id`;
- `type`;
- `provider`.

Optional standard fields include:

- `name`;
- `description`;
- `status`;
- `state`;
- `properties`;
- `extensions`;
- `tags`.

Resource IDs must be unique within the document. Producers should keep IDs stable across comparable snapshots when feasible.

Resource and group types use lowercase dot notation with at least two segments, for example:

- `compute.vm`;
- `network.switch`;
- `storage.volume`;
- `ot.sensor.environmental`.

The structural pattern is:

```text
^[a-z0-9]+(?:\.[a-z0-9]+)+$
```

Standard OSIRIS types should be preferred when they accurately represent the resource.

Custom resource types must use the form:

```text
osiris.<namespace>.<type>
```

Examples:

- `osiris.aws.lambda.edge`;
- `osiris.cisco.aci.fabric`;
- `osiris.com.acme.widget`.

Consumers must accept unknown structurally valid types.

### 6.2 Connections

A connection represents an explicit relationship between two resources.

Required connection fields:

- `id`;
- `type`;
- `source`;
- `target`.

Optional fields include:

- `direction`;
- `name`;
- `description`;
- `status`;
- `state`;
- `properties`;
- `extensions`;
- `tags`.

Valid `direction` values are:

- `bidirectional`;
- `forward`;
- `reverse`.

When `direction` is omitted, consumers should assume `bidirectional`.

Connection source and target identifiers must reference resources in the same document.

### 6.3 Groups

A group represents a logical or physical grouping of resources.

Required group fields:

- `id`;
- `type`.

Optional fields include:

- `name`;
- `description`;
- `members`;
- `children`;
- `properties`;
- `extensions`;
- `tags`.

`members` contains resource IDs. `children` contains group IDs. References must resolve within the same document, and group hierarchies must not contain cycles.

### 6.4 Metadata

Metadata describes the document and snapshot as a whole.

Required metadata field:

- `timestamp`: RFC 3339 / ISO 8601 date-time including `Z` or an explicit offset.

Optional metadata fields:

- `generator`;
- `scope`.

Metadata may also contain additional fields for forward compatibility.

### 6.5 Provider Provenance

Every resource contains a `provider` object.

Required provider field:

- `name`.

Optional provider fields include:

- `namespace`;
- `native_id`;
- `account`;
- `tenant`;
- `type`;
- `region`;
- `zone`;
- `subscription`;
- `project`;
- `site`;
- `system`;
- `source`;
- `version`.

When `provider.name` is `custom`, `provider.namespace` is required.

Provider provenance preserves traceability to the originating system while allowing vendor-neutral processing.

### 6.6 Properties, Extensions, and Tags

Use `properties` for normalized resource, connection, or group data that does not require a dedicated top-level field.

Use `extensions` for vendor- or organization-specific payloads.

Extension keys must begin with `osiris.` and use lowercase dot-separated identifiers. Each extension value must be a JSON object.

Examples:

```json
{
  "extensions": {
    "osiris.aws": {
      "native_feature": "example"
    },
    "osiris.com.acme": {
      "internal_classification": "tier-1"
    }
  }
}
```

Consumers must accept unknown extension namespaces and should preserve them when re-exporting documents.

Use `tags` for string key-value labels used in filtering, grouping, and search.

## 7. Validation Model

OSIRIS validation is layered.

### Level 1 — Structural

Checks JSON syntax and conformance to the OSIRIS JSON Core Schema, including required fields, data types, patterns, formats, and enum values.

A document that fails structural validation is not safe for normal processing.

### Level 2 — Semantic

Checks internal graph consistency, including:

- unique resource, connection, and group IDs;
- connection source and target references;
- group member references;
- group child references;
- hierarchy safety and invalid self-references.

### Level 3 — Domain

Provides optional best-practice and interoperability guidance. Level 3 must not redefine structural conformance or reject a document only because a type or extension is unknown.

Common validation profiles:

- `basic`: Level 1;
- `default`: Levels 1 and 2;
- `strict`: Levels 1, 2, and selected Level 3 checks.

The canonical CLI can be used locally or in CI/CD:

```bash
npx @osirisjson/cli validate --profile strict snapshot.json
```

## 8. Versioning and Compatibility

OSIRIS document versions use Semantic Versioning.

Within a supported major version:

- consumers must ignore unknown fields;
- consumers must accept unknown structurally valid resource, connection, and group types;
- consumers must accept unknown extension namespaces;
- new optional fields and types may be added in minor versions;
- required fields and existing semantics must not change incompatibly.

A major-version mismatch may be rejected as unsupported.

Stable resource IDs and deterministic ordering are recommended because they improve snapshot comparison and drift analysis.

## 9. Security and Privacy

OSIRIS documents can contain sensitive infrastructure metadata and topology information.

Producers must exclude credentials, private keys, tokens, connection secrets, and authentication material from emitted documents.

Producers should apply data minimization and redaction before emission. Logs must not disclose secret values.

Generated files should be classified, stored, transferred, retained, and deleted according to the owner's security policies.

OSIRIS supports local generation and local validation. It does not require uploading infrastructure data to an OSIRIS-operated service.

The owner decides whether a document remains offline or is shared with internal systems, auditors, AI platforms, agents, MCP servers, or third parties.

## 10. Principal Use Cases

Common uses include:

- point-in-time audit and compliance evidence;
- automated architecture and operational documentation;
- topology diagram generation and updates;
- deterministic snapshot comparison and drift detection;
- handover and incident-triage baselines;
- CMDB and IPAM reconciliation;
- migration discovery and dependency baselining;
- graph-based security and blast-radius analysis;
- IT/OT infrastructure documentation;
- optional, governed AI or MCP context.

Use-case documentation:

- https://docs.osirisjson.org/introduction/use-cases/

## 11. Examples

Reference examples are available for IT and OT environments:

- IT examples: https://docs.osirisjson.org/examples/it-infrastructure/
- OT examples: https://docs.osirisjson.org/examples/ot-infrastructure/

Examples are informative. If an example conflicts with the specification or core schema, the specification and schema are authoritative.

## 12. Project Status and Roadmap

Producer availability, consumer milestones, and implementation priorities change over time.

Use the roadmap as the current source for project status:

- https://osirisjson.org/en/commitments/roadmap

Do not infer that a named producer or consumer is released merely because it appears in a use case, example, roadmap, or architecture diagram.

## 13. Repositories

- Specification and schema: https://github.com/osirisjson/osiris
- Producers and Go producer SDK: https://github.com/osirisjson/osiris-producers
- Toolbox, validation engine, CLI, and TypeScript SDK: https://github.com/osirisjson/osiris-toolbox
- Editor integrations: https://github.com/osirisjson/osiris-editor-integrations
- Organization profile and community files: https://github.com/osirisjson/.github

## 14. Documentation Index

### Introduction

- Welcome: https://docs.osirisjson.org/introduction/welcome/
- What is OSIRIS JSON?: https://docs.osirisjson.org/introduction/what-is-osiris/
- Use cases: https://docs.osirisjson.org/introduction/use-cases/

### Producers

- Getting started: https://docs.osirisjson.org/osiris-producers/getting-started/
- Installation: https://docs.osirisjson.org/osiris-producers/installation/
- Security: https://docs.osirisjson.org/osiris-producers/security/
- AWS: https://docs.osirisjson.org/osiris-producers/hyperscalers/amazon-aws/
- Azure: https://docs.osirisjson.org/osiris-producers/hyperscalers/microsoft-azure/
- Cisco: https://docs.osirisjson.org/osiris-producers/network/cisco/

### Consumers

- Getting started and status: https://docs.osirisjson.org/osiris-consumers/getting-started/

### Validation

- Toolbox CLI: https://docs.osirisjson.org/validate/toolbox-cli/
- Validation levels: https://docs.osirisjson.org/validate/validation-levels/

### Developer Guidelines

- Developer entry point: https://docs.osirisjson.org/developer-guidelines/welcome/
- Architecture: https://docs.osirisjson.org/developer-guidelines/architecture/
- Producer guidelines: https://docs.osirisjson.org/developer-guidelines/producers/producer-guidelines/
- Producer SDK: https://docs.osirisjson.org/developer-guidelines/producers/producer-sdk/
- Writing a producer: https://docs.osirisjson.org/developer-guidelines/producers/writing-a-producer/

### Community and Commitments

- Manifesto: https://osirisjson.org/en/commitments/manifesto
- Roadmap: https://osirisjson.org/en/commitments/roadmap
- Governance: https://osirisjson.org/en/commitments/governance
- Maintainers: https://osirisjson.org/en/commitments/maintainers
- Contributing: https://docs.osirisjson.org/community/contributing/

## 15. Licensing

Licensing varies by repository and artifact. Consult the applicable `LICENSE` or `LICENSE-CODE` file in each repository.

Do not assume that the specification, documentation, schemas, and executable source code all use the same license.