This developer guide is designed for engineers building or editing OSIRIS JSON Producers, OSIRIS JSON Consumers, or creating custom validations tool within the OSIRIS JSON ecosystem.
OSIRIS is a vendor-neutral, open specification for infrastructure resource interchange. By normalizing on a common, local-first data format, we enable seamless infrastructure analysis, diagramming, and policy auditing without locking data into proprietary languages and platforms.
Every tool built for the OSIRIS JSON ecosystem adhere to these fundamental principles:
1. Local-First & Private
Producers and consumers must run locally on workstation or server systems under the user’s complete control. Never require external internet connectivity (in case of targeting locally available resources) and never have to transmit data to any third-party services this include AI integrations. Users, without being forced at any step into any model or choice typical of vendor lock-in platform and tools, after generating the OSIRIS JSON document are free to share, store, and process the document wherever they want.
2. Secure by Default
Redact all secrets, API tokens, and credentials at the source before emitting OSIRIS JSON snapshots. The output should be safe to store in version control and share with third-parties.
3. Explicit & Decoupled
Model infrastructure dependencies explicitly. Decouple data discovery (handled by Producers) from data utilization (handled by Consumers or AI analysis engines).
4. Forward-Compatible
Strictly follow Semantic Versioning. Treat unrecognized properties and custom extensions as opaque objects that can be parsed and passed along without throwing validation errors.
To help you get started, we have structured the developer guidelines into several key areas:
- Specification Architecture: Understand the design philosophy, document structure, and the relationship between resources, connections, and groups.
- Building Producers: Technical details on using the Go SDK, constructing valid resource types, and mapping native infrastructure schemas.
- Style Guidelines: Formatting conventions, naming rules, and testing criteria for JSON examples and schema files.
- Core Schema Reference: Detailed field-by-field definitions of the OSIRIS envelope, metadata scope, and topology elements.
