Appendices

Appendix A: JSON Schema definition

The OSIRIS JSON Schema provides structural validation for OSIRIS documents.

Schema location URI: OSIRIS JSON Schema

Schema reference in documents:

{
  "$schema": "https://osirisjson.org/schema/v1.0/osiris.schema.json",
  "version": "1.0.0"
}

A.1 Schema overview

The OSIRIS JSON Schema validates:

• Top-level document structure (version, metadata, topology)
• Required fields at each level
• Field data types (string, number, boolean, object, array)
• Enum constraints (e.g. direction must be bidirectional, forward or reverse)
• Format constraints (e.g. timestamp must be ISO 8601 / RFC 3339)

The schema does not validate:

• Referential integrity (connections referencing resources)
• Type semantics (e.g. whether a type is ‘recognized’ or appropriate for the domain)
• Domain-specific semantics (Chapter 9, Level 2 and Level 3 validation)

A.2 Schema structure (excerpt/top-level outline)

[!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": { }
  }
}

A.3 Using the schema

Validation tools:

• Validate OSIRIS JSON Document

A.4 Schema evolution

The OSIRIS JSON Schema evolves with the specification:

• v1.0.0 schema: Validates OSIRIS v1.0.0 documents
• v1.1.0 schema: Adds optional fields introduced in v1.1.0 but remains backwards-compatible
• v2.0.0 schema: May introduce breaking changes aligned with specification v2.0.0

Consumers SHOULD use the schema version matching their target specification version.

A.5 Complete schema

The complete JSON Schema is available at:

• Canonical URI: https://osirisjson.org/schema/v1.0/osiris.schema.json
• GIT Repository: https://github.com/osirisjson/osiris/tree/main/schema

Appendix B: Complete examples

Complete, validated examples demonstrating OSIRIS v1.0 are available in the OSIRIS GitHub repository:

• Canonical URI: https://osirisjson.org/examples/v1.0/
• GIT Repository: https://github.com/osirisjson/osiris/tree/main/examples/v1.0

B.1 Example categories

Examples are organized by domain:

IT/Cloud examples:

• IT/cloud/osiris_minimal_cloud_provider_infrastructure.json
• IT/hyperscalers/osiris_minimal_hyperscalers_infrastructure.json
• IT/hyperscalers/osiris_simple_hyperscaler_infrastructure.json
• IT/hyperscalers/osiris_hyperscaler_infrastructure_belonging.json
• IT/hyperscalers/osiris_multi_hyperscaler_environment.json
• IT/hyperscalers/osiris_hybrid_hyperscaler_on_premise.json

IT/On-Premise examples:

• IT/on-premise/osiris_minimal_on_premise_infrastructure.json
• IT/on-premise/osiris_on_premise_network_topology.json

OT (Operational Technology) examples:

• OT/osiris_minimal_ot_infrastructure.json
• OT/osiris_it_ot_cross_network_topology.json
• OT/osiris_industrial_printer.json
• OT/osiris_security_camera.json
• OT/osiris_door_access_control.json

B.2 Example validation

All examples are validated against:

• JSON Schema (Level 1): Structural correctness
• Referential integrity (Level 2): All IDs resolve, no dangling references
• Domain rules (Level 3): Type format, naming conventions

Examples are automatically validated in the repository CI/CD pipeline.

B.3 Using examples

Examples serve multiple purposes:

• Learning: Understand OSIRIS structure and patterns
• Testing: Validate parser and consumer implementations
• Templates: Starting points for new documents
• Reference: Demonstrate best practices

Implementers SHOULD test their tools against the complete example set.

Appendix C: Resource type registry

This appendix provides a comprehensive listing of all standard resource types defined in OSIRIS v1.0.

C.1 Compute resources

C.2 Network resources

C.3 Storage resources

C.4 Application resources

C.5 Container and organization resources

C.6 Operational Technology (OT) resources

C.7 Type evolution

New types MAY be added in MINOR version updates (e.g. v1.1.0).

To propose a new standard type:

1. Open an issue in the OSIRIS GitHub repository
2. Provide use case justification and examples
3. Demonstrate that existing types are insufficient
4. Propose type name following naming conventions (lowercase, dot notation)

Appendix D: Comparison with related standards

This appendix compares OSIRIS with related standards and formats for infrastructure topology and configuration.

D.1 OSIRIS vs TOSCA (Topology and Orchestration Specification for Cloud Applications)

When to use OSIRIS:

• Documenting existing infrastructure
• Exporting topology snapshots for visualization
• Cross-platform inventory and CMDB integration
• Lightweight interchange between tools

When to use TOSCA:

• Application provisioning and orchestration
• Infrastructure-as-code with lifecycle management
• Complex dependency modeling with workflows

Interoperability: OSIRIS documents MAY be generated from TOSCA topologies by extracting instantiated resources and relationships.

D.2 OSIRIS vs Terraform / AWS CloudFormation / Azure ARM Templates

When to use OSIRIS:

• Documenting infrastructure that already exists
• Exporting topology from multiple providers in a single document
• Creating provider-agnostic documentation

When to use IaC tools:

• Provisioning new infrastructure
• Managing infrastructure lifecycle
• Implementing GitOps workflows

Interoperability: OSIRIS documents MAY be generated from Terraform state or CloudFormation stacks to document provisioned infrastructure.

D.4 OSIRIS vs OpenAPI Specification

Relationship: Both OSIRIS and OpenAPI define JSON-based interchange formats with JSON Schema validation. OSIRIS focuses on infrastructure, OpenAPI focuses on APIs. OSIRIS documents MAY include references to OpenAPI specifications in resource properties (e.g. an application.service resource with api_spec_url: "https://api.example.com/openapi.json").

D.5 OSIRIS vs NETCONF/YANG

When to use OSIRIS:

• Documenting heterogeneous infrastructure (not just network)
• Multi-vendor topology snapshots
• Lightweight JSON interchange

When to use NETCONF/YANG:

• Network device configuration management
• Standardized network state retrieval
• Network automation requiring write operations

Interoperability: OSIRIS documents MAY be generated from NETCONF data by transforming YANG-modeled state into OSIRIS resources and connections.

D.6 OSIRIS vs CMDB schemas (ServiceNow, BMC, etc.)

Relationship: OSIRIS can serve as an export format from CMDBs and as an import format into CMDBs.

Workflow:

1. Export infrastructure from sources (cloud APIs, network devices, OT systems)
2. Generate OSIRIS document
3. Import OSIRIS document into CMDB (ServiceNow, BMC, etc.)
4. CMDB enriches with additional lifecycle data (ownership, contracts, incidents)