OSIRIS JSON Architecture Development Guidelines

Table of Content

• Table of Content
• 1 Introduction
  • 1.1 Developer navigation matrix
  • 1.2 Architectural principles
    • 1.2.1 Single source of truth
    • 1.2.2 Separation of concerns
• 2 Physical architecture
  • 2.1 Ecosystem structure
    • 2.1.1 Repository layout (Polyrepo vs monorepo)
    • 2.1.2 Repository responsibilities
  • 2.2 The toolbox monorepo (@osirisjson/*)
    • 2.2.1 @osirisjson/core: The validation engine
    • 2.2.2 @osirisjson/sdk: IDEs and tooling SDK
    • 2.2.3 @osirisjson/cli: Command Line Interface
  • 2.3 The producer repository (osiris-producers)
    • 2.3.1 Go producer SDK
  • 2.4 Dependency graph and stability rules
    • 2.4.1 The “forbidden direction” rule
    • 2.4.2 Version alignment strategy
  • 2.5 Implementation platform rationale (TypeScript + NPM) (Non-normative)
    • Decision summary
    • Why TypeScript/NPM for the toolbox
    • Why Go for producers
    • Two SDKs by audience
    • Comparison matrix (toolbox reference implementation)
    • Guidance for non-Go producers
    • Specialized producers (C/Rust etc.) (Non-normative)
• 3 Logical architecture (Data Flow pipelines)
  • 3.1 The ingestion pipeline (Producer lifecycle)
    • 3.1.1 Context and scope
    • 3.1.2 Normalization
  • 3.2 The validation pipeline (Core engine)
    • 3.2.1 Stage 1: Structural (Schema)
    • 3.2.2 Stage 2: Semantic (Integrity)
    • 3.2.3 Stage 3: Domain (Best practices)
  • 3.3 The consumption pipeline (CLI and Editors)
• 4 Core architectural patterns
  • 4.1 Diagnostics and error handling
    • 4.1.1 The diagnostic model
    • 4.1.2 Severity guidance and profiles
  • 4.2 Identity strategy (deterministic IDs)
  • 4.3 Extensibility mechanism
  • 4.4 JSON file conventions
    • 4.4.1 File format
    • 4.4.2 Top-level fields
    • 4.4.3 Recommended ordering and diffs
    • 4.4.4 Recommended formatting
  • 4.5 Terminology
  • 4.6 Stability tiers
• 5 Cross-Cutting concerns
  • 5.1 Performance constraints
  • 5.2 Security and redaction
• 6 References
  • 6.1 Normative references
    • RFC2119
    • RFC3339
    • RFC5737
    • RFC8259

1 Introduction

This document defines the architectural foundation for the OSIRIS ecosystem. It establishes the patterns, principles and repository structures required to build and evolve the OSIRIS core toolbox, producers and editor-integrations in a sustainable and scalable way.

These Architecture Development Guidelines prioritize:

1.1 Developer navigation matrix

This document is intentionally lean and focuses on ecosystem contracts, boundaries and architectural rules.
Implementation details live in focused guides and repository READMEs close to the code.

Use the matrix below to find the right entry point.

1.2 Architectural principles

1.2.1 Single source of truth

OSIRIS is designed to avoid fragmentation. The ecosystem must agree on one canonical definition of the format and one canonical implementation of validation behavior.

Rationale: a document validated in CI should behave the same in VS Code, in the CLI and in any consumer embedding @osirisjson/core. Tooling should work offline (schema may be bundled), but the endpoint remains canonical for versioned resolution.

1.2.2 Separation of concerns

OSIRIS splits the ecosystem into clear responsibilities to keep scaling sustainable.

Rationale: when each layer only does its job, the ecosystem remains predictable and contributors know where changes belong.

2 Physical architecture

2.1 Ecosystem structure

2.1.1 Repository layout (Polyrepo vs monorepo)

OSIRIS is developed across multiple repositories under the osirisjson GitHub organization. This structure separates canonical specification content from tooling, vendor producers and editor integrations, keeping responsibilities clear and enabling the ecosystem to scale as more producers and tools are added.

OSIRIS generated documents are standard JSON files and are expected to use the .json extension; consumers and tooling detect OSIRIS content via schema metadata and/or document structure rather than a custom file extension.

osirisjson/
├── .github
│   ├── ISSUE_TEMPLATE/
│   ├── workflows/
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── CODE_OF_CONDUCT.md
│   ├── COMMUNITY_GUIDE.md
│   ├── FUNDING.yml
│   ├── GOVERNANCE.md
│   ├── MEMBERS.md
│   ├── README.md
│   ├── SECURITY.md
│   └── SUPPORT.md
├── osiris                      # Canonical specification, schema sources, guidelines and normative examples
├── osiris-toolbox              # NPM packages: core validation, IDEs/tooling SDK and CLI
│   ├── core
│   ├── sdk
│   └── cli
├── osiris-producers            # Producer SDK + vendor-specific producers (parsers/exporters)
├── osiris-editor-integrations  # Editor integrations (VS Code/VSCodium today; others later)
└── osiris-mcp                  # Future MCP server

2.1.2 Repository responsibilities

Repository boundaries

Use these rules to avoid duplication and circular dependencies:

• Format definition changes (fields, semantics, namespaces, examples) belong in osiris
• Validation behavior changes (rule logic, diagnostics shape) belong in @osirisjson/core
• IDEs and tooling consumers helpers (document types, diagnostic utilities, integration helpers) belong in @osirisjson/sdk
• Producer ergonomics (transport, ID generation, normalization, golden fixtures) belong in the Go producer SDK within osirisjson-producer
• Command UX / CI behavior (flags, exit codes, output formats, orchestration) belong in @osirisjson/cli
• Vendor integrations (API calls, auth, inventory mapping, vendor-specific quirks) belong in osirisjson-producer
• IDE UX (language features, UI performance, quick fixes) belong in osiris-editor-integrations

2.2 The toolbox monorepo (@osirisjson/*)

The toolbox monorepo is the shared foundation of the OSIRIS ecosystem. It provides reusable libraries so that each consumer does not implement its own OSIRIS logic.

2.2.1 @osirisjson/core: The validation engine

The purpose is to validate OSIRIS documents and emit deterministic, tool-friendly diagnostics.

2.2.2 @osirisjson/sdk: IDEs and tooling SDK

The purpose is to provide reusable TypeScript building blocks for tools that consume or manipulate OSIRIS documents (editors, dashboards, import pipelines).

2.2.3 @osirisjson/cli: Command Line Interface

The purpose is to provide a CI-friendly and developer-friendly interface to validate and process OSIRIS documents.

2.3 The producer repository (osiris-producers)

The producer repository contains first-party Go producers and the Go producer SDK. It is separate from the toolbox because producers have different runtime concerns (transport, concurrency, vendor APIs) and a different primary language.

Command contract: osirisjson-producer <vendor> [subcommand] [flags] The osirisjson-producer CLI is designed as a dispatcher. Vendor backends are treated as interchangeable executables and MAY be implemented in any language (Go, C, Rust, etc.), provided they are invoked by the dispatcher, emit a valid OSIRIS document and follow the tool’s standard behavior (stdout for the document, stderr for diagnostics, exit codes).

2.3.1 Go producer SDK

The purpose is to provide reusable Go building blocks for building vendor-specific OSIRIS producers with minimal external dependencies.

2.4 Dependency graph and stability rules

2.4.1 The “forbidden direction” rule

OSIRIS packages are layered to prevent circular dependencies and to keep the validation engine portable. Dependencies MUST only flow “down” towards more foundational layers.

• @osirisjson/core MUST NOT depend on @osirisjson/sdk, @osirisjson/cli, osiris-producers, or any editor integration.
• @osirisjson/cli MAY depend on @osirisjson/core.
• @osirisjson/sdk MUST remain usable without requiring @osirisjson/cli or editor code.
• osiris-editor-integrations like a VS code extension MUST delegate validation to @osirisjson/core and MUST NOT ship incompatible validation logic.
• Go producers osirisjson-producer (e.g. osirisjson-producer cisco --ssh ...) use the Go producer SDK at runtime and MUST NOT depend on @osirisjson/core as a library. Canonical validation is invoked via @osirisjson/cli in CI (e.g. npx @osirisjson/cli validate <osiris document>).

A typical dependency direction looks like this:

flowchart TB
  subgraph SPEC_G["OSIRIS Specification"]
    SPEC["osiris<br/>(spec + schema)"]
  end

  subgraph TLB_G["OSIRIS Toolbox"]
    CLI["@osirisjson/cli"]
    CORE["@osirisjson/core"]
    SDK_TS["@osirisjson/sdk<br/>(TS tooling)"]
  end

  subgraph PROD_G["OSIRIS Producers"]
    SDK_GO["Go producer SDK"]
    PROD["vendor producers"]
  end

  subgraph EDT_G["OSIRIS Editors"]
    EXT["osiris-editor-integrations<br/>(VS Code / VSCodium)"]
  end

  CORE --> SPEC
  SDK_TS --> SPEC
  SDK_TS --> CORE
  CLI --> CORE
  EXT --> CORE
  SDK_GO --> SPEC
  PROD --> SDK_GO
  PROD -. "validate in CI" .-> CLI
  SDK_GO -. "MUST NOT" .-> CORE

2.4.2 Version alignment strategy

OSIRIS versioning is designed to keep the ecosystem compatible while allowing evolution.

Document and schema rules (OSIRIS v1.0)

• Documents declare version as MAJOR.MINOR.PATCH (SemVer semantics)
• The v1.0 schema endpoint accepts any 1.x.y document version
• Producers MAY include $schema. Other top-level fields SHOULD NOT be emitted
• Consumers MUST ignore unknown fields for forward compatibility

Toolbox alignment principles

• Toolbox packages MUST share the same MAJOR version across @osirisjson/core, @osirisjson/sdk and @osirisjson/cli
• @osirisjson/cli MUST be compatible with the corresponding MAJOR of @osirisjson/core
• Producers and extensions SHOULD declare which OSIRIS MAJOR they support (documentation and/or package metadata)
• Breaking changes to diagnostic shapes, rule identifiers, or CLI contract MUST be a toolbox MAJOR bump

Rationale: a stable major alignment prevents ecosystem “split brain” where producers, editors and CI disagree on what “valid” means.

2.5 Implementation platform rationale (TypeScript + NPM) (Non-normative)

OSIRIS is language-agnostic at the document level: any producer in any language is valid if it emits OSIRIS JSON that validates against the core schema and passes the canonical validation engine in CI. The OSIRIS canonical toolbox (validation engine + CLI + reference SDK) is built on TypeScript and distributed as NPM packages to maximize reuse across CLI and editor integrations.

Decision summary

• Canonical toolbox platform: Node.js + TypeScript
• Toolbox distribution: NPM packages (SemVer-aligned)
• Producers: Any language is supported; first-party producers are recommended in Go for portability and scale
• Canonical truth rule: validation behavior and diagnostic shape are defined by @osirisjson/core and must not be re-implemented elsewhere

Why TypeScript/NPM for the toolbox

The main drivers are ecosystem alignment and code reuse:

• IDEs like VS Code/VSCodium extensions run on Node: sharing diagnostics/schema/validation logic is direct
• One runtime for CLI + core + editor integrations reduces “split brain” behavior and duplication
• NPM makes SemVer alignment and dependency composition straightforward for an ecosystem.
• TypeScript provides strong typing for diagnostics, rule APIs and SDK builders without sacrificing iteration speed.

Why Go for producers

Producers are made of acquisition and parsing systems: transport (HTTP/SSH/NETCONF), concurrency, normalization and vendor quirks. Go is highly recommended for first-party producers because it supports:

• Portable deployment (single binary, cross-compilation)
• High-throughput polling/collection (concurrency, predictable memory)
• Long-term maintainability (stdlib-first approach for HTTP/JSON/XML/TLS/crypto/regex)

This does not change OSIRIS interoperability: producers still emit OSIRIS JSON and validate via the canonical toolbox in CI.

Two SDKs by audience

To avoid mixing concerns, OSIRIS treats “SDK” as audience-specific:

• Tooling SDK (TypeScript): aligns with @osirisjson/core contracts and editor integrations (@osirisjson/sdk in the toolbox).
• Producer/acquisition SDK (Go): lives with Go producers and provides transport and normalization helpers for building exporters at scale.

Comparison matrix (toolbox reference implementation)

Conclusion: TypeScript/NPM remains the most pragmatic choice for the canonical toolbox because it maximizes reuse across CLI+core+editor integrations with the lowest contributor friction. Go for producers remain first-class providing strong performance in complex scenarios generating large snapshots.

Guidance for non-Go producers

• Emit OSIRIS JSON with $schema.
• Validate in CI using @osirisjson/core (via CLI) to match canonical behavior.
• Use golden fixtures to prevent drift across releases.

Specialized producers (C/Rust etc.) (Non-normative)

OSIRIS is language-agnostic. While first-party producers are generally recommended in Go, some environments like OT landscape require lower-level implementations.

In constrained or realtime OT landscapes, producers/collectors MAY be implemented in C, Rust or other languages, for example:

• bare-metal or RTOS targets
• hard-realtime sampling loops with strict requirements
• very small memory/flash budgets
• direct serial/fieldbus/proprietary binary protocols (e.g. RS-485/Modbus RTU, BACnet MS/TP, CAN)

In these cases, C/Rust producers SHOULD be treated as edge collectors focused on acquisition.

They SHOULD either:

• emit OSIRIS JSON on a gateway/system that can run validation
• emit a minimal intermediate payload to a gateway which performs normalization and produces OSIRIS JSON.

Regardless of implementation language, all produced OSIRIS documents MUST be validated in CI using the canonical TypeScript validation engine (@osirisjson/core) to prevent rule drift.

3 Logical architecture (Data Flow pipelines)

3.1 The ingestion pipeline (Producer lifecycle)

The ingestion pipeline describes how producers create an OSIRIS snapshot from source systems. It is intentionally described as a contract-level lifecycle; implementation details belong in OSIRIS-ADG-PR-1.0 and the OSIRIS Go producer SDK.

3.1.1 Context and scope

Producers MUST establish explicit export context before emitting an OSIRIS document.

• metadata.timestamp reflects when the snapshot was generated (ISO 8601 with timezone)
• metadata.generator identifies the producer/tool name and version
• metadata.scope describes what the snapshot represents (e.g. providers, accounts/subscriptions, regions, sites, environments) and any known limitations

Guidance

• If inventory is incomplete, producers SHOULD still export what they know and document limitations in metadata.scope.description (or equivalent) rather than failing silently.
• Very large infrastructures MAY be split into multiple documents (e.g. per region/environment/account). Scope MUST make boundaries explicit.

3.1.2 Normalization

Normalization makes documents comparable over time and across producers. It standardizes representation, not meaning (normalization MUST NOT introduce artifacts).

Producers SHOULD:

• Normalize provider naming and stable identifiers under provider
• Prefer stable field representations (e.g. consistent casing and units)
• Avoid embedding volatile, noise-heavy values unless they are essential for the intended use case
• Produce diff-friendly output where feasible (e.g. stable ordering of arrays such as sorting by id)

3.2 The validation pipeline (Core engine)

Validation is executed by @osirisjson/core and emits diagnostics. Validation is defined in terms of levels; see OSIRIS-ADG-VL-1.0 for the full model and catalog. Validation profiles (e.g. default vs strict) may change which checks run and how results are reported, but MUST NOT change the meaning of a rule.

3.2.1 Stage 1: Structural (Schema)

3.2.2 Stage 2: Semantic (Integrity)

3.2.3 Stage 3: Domain (Best practices)

3.3 The consumption pipeline (CLI and Editors)

Consumers are responsible for presenting and acting on validation outcomes. CLI and editors MUST delegate validation behavior to @osirisjson/core (no duplicated validators).

CLI pipeline:

• Read files and resolve schema (offline/local).
• Run @osirisjson/core validation with a chosen profile.
• Emit:
  • stable exit codes for CI
  • machine-readable results (JSON)
  • human-readable summaries

Editor pipeline (Visual Studio Code/VSCodium):

• Detect OSIRIS documents (via $schema and/or document structure)
• Validate via @osirisjson/core (directly or via LSP)
• Render diagnostics (squiggles, hovers, quick fixes)
• Enforce performance constraints (debounce, incremental parsing, avoid UI blocking)

4 Core architectural patterns

This chapter defines the ecosystem patterns that keep OSIRIS toolbox consistent across CLI, editors, producers and third-party consumers.

4.1 Diagnostics and error handling

Diagnostics are the common language across the OSIRIS ecosystem. They MUST be stable, structured and tool-friendly.

flowchart TD
  DOC["OSIRIS JSON document"]
  PROFILE["Validation profile (default/strict)"]

  subgraph CORE["OSIRIS @osirisjson/core"]
    direction TB

    L1["Level 1
    - JSON schema
    - required fields
    - types, formats, enums
    - pattern constraints"]

    L2["Level 2
    - Semantic referential integrity
    - connection source/target > resource id
    - group members/children > resource/group id
    - ID uniqueness per array
    - cycle detection (groups)"]

    L3["Level 3
    - Domain best-practice checks
    - modeling hints
    - quality warnings
    - security posture hints"]

    L1 --> L2 --> L3
  end

  DOC --> CORE
  PROFILE -.-> CORE

  subgraph DIAG["OSIRIS diagnostic"]
    direction LR
    CODE["code"]
    SEV["severity"]
    MSG["message"]
    PATH["path"]
    RANGE["range"]
  end

  CORE --> DIAG

  subgraph CONSUMERS["OSIRIS consumers"]
    direction LR
    CLI["CLI
    exit codes
    JSON / text"]
    EDITOR["Editor
    squiggles
    quick fixes"]
    THIRDPARTY["Third-party
    pipelines
    dashboards"]
  end

  DIAG --> CLI
  DIAG --> EDITOR
  DIAG --> THIRDPARTY

4.1.1 The diagnostic model

A diagnostic represents a single validation finding emitted by @osirisjson/core.

Minimum fields

Optional fields

Example (illustrative, not normative):

{
  "code": "V-REF-002",
  "severity": "error",
  "message": "Connection target references non-existent resource 'aws::db-nonexistent'.",
  "path": "/topology/connections/0/target",
  "range": {
    "start": { "line": 220, "character": 18 },
    "end":   { "line": 220, "character": 44 }
  }
}

[!NOTE] Rule definitions and canonical code meanings are specified in the OSIRIS-JSON-v1.0. The engine input/output contract and profile mapping are defined in OSIRIS-ADG-VL-1.0.

4.1.2 Severity guidance and profiles

Diagnostics separate what failed code from how serious it is severity. Severity may depend on the active validation profile (e.g. default vs strict), but codes must not change meaning.

General guidance:

• Structural (Level 1) violations are typically error.
• Semantic (Level 2) violations are typically error (broken references, duplicate IDs), but some may be downgraded under non-strict profiles.
• Domain (Level 3) findings are typically warning, info, or hint.

The authoritative rule catalog and mapping live in OSIRIS-ADG-VL-1.0 and are implemented in @osirisjson/core

4.2 Identity strategy (deterministic IDs)

Stable identity is what makes OSIRIS useful for diffs, correlation and long-lived tooling.

Core rules: Resource, connection and group IDs MUST be unique within a document.

• IDs SHOULD remain stable across exports when feasible.
• IDs are opaque identifiers: consumers SHOULD NOT require parsing ID structure.

Recommended producer strategy:

Rationale: stable IDs enable meaningful topology diffs and downstream correlation without vendor-specific logic.

4.3 Extensibility mechanism

OSIRIS is designed to evolve without breaking consumers.

Forward-compatibility rules:

• Consumers MUST ignore unknown fields (including unknown extension payloads).
• Producers SHOULD NOT introduce new top-level fields in v1.0 beyond optional $schema.

Where to put additional data:

Namespace governance:

• Extension keys MUST follow osiris.<identifier> naming rules (lowercase, dot-separated).
• The osiris. prefix is reserved to prevent collisions and support registry conventions.
• OSIRIS governs namespace rules (and optionally a registry), not the internal semantics of each extension payload.
• Consumers MUST treat unknown extension fields as opaque.

4.4 JSON file conventions

These conventions keep OSIRIS documents portable, editor-friendly and diff-friendly.

4.4.1 File format

• Documents MUST be valid JSON format adhering to RFC8259.
• Canonical OSIRIS documents MUST NOT use comments (jsonc).
• Character encoding MUST be in UTF-8 adhering to RFC8259.
• Documents are expected to use the .json extension (tools detect OSIRIS via $schema and/or structure).

4.4.2 Top-level fields

• Producers MAY include $schema (recommended for tooling/editor resolution).
• Other top-level fields SHOULD NOT be emitted in OSIRIS v1.0.

4.4.3 Recommended ordering and diffs

• Prefer consistent key ordering for common objects (at least at the top level).
• Prefer stable ordering for arrays when it does not change semantics:
  • topology.resources sorted by id
  • topology.connections sorted by id
  • topology.groups sorted by id
• Avoid nondeterministic iteration order that creates noisy diffs.

4.4.4 Recommended formatting

• 2-space indentation
• newline at end of file

4.5 Terminology

4.6 Stability tiers

This table defines which ecosystem surfaces are expected to remain stable within a MAJOR version.

5 Cross-Cutting concerns

Cross-cutting concerns apply to all OSIRIS components (producers, validation engine, CLI, editor integrations and any third-party consumers). These rules exist to keep the ecosystem reliable, safe and predictable at scale.

5.1 Performance constraints

OSIRIS tooling must remain reliable on large documents and in interactive environments.

5.2 Security and redaction

OSIRIS is an interchange format. It MUST be safe to share under controlled policies. Producers and tooling MUST prevent accidental disclosure of secrets.

6 References

This chapter lists normative and informative references used in the OSIRIS architecture and guidelines.

6.1 Normative references

The following documents are referenced normatively in this specification. Implementers MUST consult these references to fully understand OSIRIS requirement levels and terminology.

RFC2119

Key words for use in RFCs to indicate requirement levels https://www.rfc-editor.org/rfc/rfc2119 Defines the normative keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY and OPTIONAL used throughout this specification.

RFC3339

Date and Time on the Internet: Timestamps RFC3339 Defines defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar.

RFC5737

IPv4 Address Blocks Reserved for Documentation RFC 5737 Defines the three IPv4 unicast address blocks reserved for use in examples in OSIRIS specifications and other documents.

RFC8259

The JavaScript Object Notation (JSON) data interchange format https://www.rfc-editor.org/rfc/rfc8259 Defines the JSON data format used as the foundation for OSIRIS documents.