OSIRIS JSON Architecture Guidelines

OSIRIS JSON now has a dedicated architecture document for contributors building around the standard.

Published on February 4, 2026, the OSIRIS JSON Architecture Development Guidelines define how the ecosystem is expected to evolve across the specification repository, toolbox packages, producers, and editor integrations. This is not a second specification. It is the operational blueprint for keeping implementations aligned as the project grows.

Why this document matters

Open standards often become fragmented when each tool, extension, or producer starts interpreting the format on its own. The architecture guidelines are meant to prevent that outcome early.

The document makes two positions explicit:

• The OSIRIS specification and schema remain the single source of truth for the format
• @osirisjson/core is the canonical implementation of validation behavior and diagnostic formatting

That matters because the same OSIRIS document should behave consistently in CI, in the CLI, and inside editor integrations. The project is drawing a hard line against duplicated validators, incompatible forks of rule logic, and repo sprawl disguised as flexibility.

The core architectural direction

The guidelines formalize a clear separation of concerns across the ecosystem:

• osiris defines the canonical specification, schema, examples, and development guidelines
• osiris-toolbox hosts the shared TypeScript packages, including @osirisjson/core, @osirisjson/sdk, and @osirisjson/cli
• osiris-producers contains vendor-specific producers and the Go producer SDK
• osiris-editor-integrations consumes the shared validation engine instead of re-implementing it

One of the most important rules in the document is the “forbidden direction” rule for dependencies. Validation logic flows downward into the shared core; it does not get copied upward into editors, producers, or command wrappers. That design is what keeps the ecosystem portable and avoids split-brain behavior between tools.

More than repo structure

The architecture guidelines are also where OSIRIS defines how the system should behave under real implementation pressure.

They describe:

• A three-stage validation pipeline: structural, semantic, and domain checks
• A stable diagnostic model built around codes, severities, messages, and document paths
• Deterministic identity guidance so resources, groups, and connections remain diff-friendly across exports
• JSON file conventions intended to reduce noisy changes and improve editor tooling
• Security and redaction expectations, including a strict ban on credentials and secrets inside OSIRIS documents

This is also where the project explains a pragmatic platform split: the canonical toolbox is built in TypeScript and distributed through NPM for maximum reuse across CLI and editor integrations, while first-party producers are recommended in Go because acquisition, transport, concurrency, and vendor-specific collection have different runtime constraints.

What contributors should take from it

The main message of the architecture document is straightforward: OSIRIS is designed as an ecosystem, not just a schema file.

If you are building a producer, a validation rule, a CLI feature, or an editor integration, the guidelines clarify where that work belongs, which contracts are stable, and which shortcuts are not acceptable. That makes the document especially important for early contributors, because it establishes boundaries before accidental duplication becomes project debt.

Read the guidelines

The architecture guidelines are currently published as a draft document, created on February 4, 2026 and revised on February 11, 2026:

• Read the OSIRIS Architecture Development Guidelines
• Read the OSIRIS JSON v1.0 specification
• Read the implementation guidelines
• Read the validation chapter
• Read the versioning and compatibility chapter
• View the project repository

Banner icon author Reyda Dönmez