What an OSIRIS JSON producer is expected to do
OSIRIS JSON producers are where the standard becomes real.
The producer guidelines and producer SDK documentation make that explicit. A producer is not just a parser that happens to emit JSON. It is the boundary where proprietary inventories are translated into a deterministic, portable, and safe OSIRIS snapshot that other tools can trust.
A producer is a read-only translator
The first important point in the producer guidance is what a producer is not.
It does not provision infrastructure. It does not mutate devices. It does not invent missing data. It does not reinterpret the specification. A producer’s job is narrower and stricter: discover what exists, normalize it into OSIRIS, remove unsafe or irrelevant data, and emit a snapshot that can be validated by the canonical OSIRIS toolchain.
That sounds obvious, but it is the right line to draw. The moment producers start behaving like control planes, or start embedding custom ideas of what OSIRIS means, interoperability breaks.
The producer workflow is deliberate
The docs describe the producer lifecycle as four steps: discovery, normalization, redaction, and emission.
That sequence matters because each stage has a different responsibility:
- discovery gathers vendor or platform data
- normalization maps it into standard OSIRIS structures
- redaction strips secrets, PII, and useless noise
- emission serializes the document and validates it before publication
The guidance also makes room for reality. Partial inventories are acceptable. Individual discovery failures should usually be logged and skipped rather than crashing the whole export. But that flexibility stops at the security boundary: if secrets are detected, the producer is expected to fail safely.
Determinism is a feature, not polish
One of the strongest themes across both documents is determinism.
Resource IDs, connection IDs, and group IDs are expected to be stable across runs. The producer docs push hard against randomness, unstable ordering, and ad-hoc naming. The reason is straightforward: if the same environment produces different output every time, diffs, correlation, and downstream automation all become unreliable.
The SDK reinforces that with concrete helpers:
- deterministic ID generation from canonical keys
- two-phase collision handling through an
IDRegistry - a
DocumentBuilderthat owns$schema,version, generator metadata, and sorted topology output - test helpers that check byte-for-byte determinism and golden-file consistency
This is one of the clearest signs that OSIRIS is being designed for long-lived tooling, not one-off exports.
Security is a producer responsibility
The producer guidelines are equally firm about redaction.
OSIRIS documents must not contain credentials, tokens, private keys, or connection strings with embedded secrets. Producers are expected to scan for common patterns before emission, decompose unsafe values instead of copying them whole, and choose an explicit failure mode.
The recommended default is fail-closed. An opt-in log-and-redact mode exists, but even there the rules stay strict: never log the secret value itself, always mark the document as redacted, and never let redaction happen silently.
That is the right posture. Producers sit closest to raw source systems, which makes them the most dangerous place to be careless.
The SDK is there to remove drift
The Go producer SDK is not presented as magic infrastructure. It is presented as a way to stop producer drift.
It standardizes the Collect(ctx) contract, provides shared runtime context, resource and relationship factories, normalization helpers, deterministic builders, and a test harness. Just as important, it refuses to become a second validator. The SDK does not own V-* diagnostics and does not import @osirisjson/core as a library. Producers validate output by calling the canonical CLI as an external step.
That separation is architecturally sound. It keeps mapping logic in producers and validation logic in the shared OSIRIS engine.
Trust comes from tests
The final message in the producer docs is that producer output must be reproducible and reviewable.
Golden files are treated as the main regression defense. The expected workflow is simple: mock the vendor input, generate the OSIRIS document, diff it against the golden file, then validate that artifact with the canonical CLI under the strict profile. The SDK test harness adds helpers for that flow and for deterministic re-runs with fixed clocks and fixtures.
This matters because producer quality is not just about whether the export “works once.” It is about whether the same input keeps producing trustworthy output as the ecosystem evolves.
Read the producer docs
The producer guidance is available in the architecture section of the documentation: