OSIRIS JSON

The OSIRIS JSON Governance

OSIRIS JSON is an open specification intended to be openly reviewable, community-driven, and practical to implement.

This document explains how changes are proposed, reviewed, decided, and released. It also describes how contributors can earn deeper responsibility in the project over time.

[!NOTE] Current maintenance model: OSIRIS JSON is currently maintained by a single lead maintainer. Contributions are welcome from the beginning, but the process is intentionally lightweight to keep initial releases manageable and consistent. As the community grows, trusted contributors and reviewers may be invited into broader project roles.

Roles

Maintainer

Maintainers are responsible for the quality, coherence, and long-term direction of the specification, schemas, producers, examples, documentation, and release notes. They ensure changes preserve vendor neutrality, clarity, compatibility expectations, and the project scope.

Maintainers may merge pull requests, publish releases, resolve blocked decisions, coordinate security or conduct responses, and represent the project in standardization or ecosystem discussions.

Contributor

Contributors propose improvements through issues, discussions, and pull requests. Contributions may include specification fixes, clarifications, examples, producer implementations, validation improvements, documentation, tests, and implementation guidance.

Contributors do not need formal project status to participate. Clear use cases, reproducible examples, careful reviews, and respectful discussion are all valuable contributions.

Reviewer

Reviewers are community members who provide regular technical review and feedback. Review is especially important for normative changes, schema changes, compatibility impacts, producer behavior, security-sensitive code, and versioning decisions.

Reviewers help maintain quality, but they do not necessarily have merge or release authority unless they are also maintainers.

Role progression

OSIRIS JSON is intended to grow through transparent, merit-based participation. Project responsibility SHOULD follow demonstrated trust, useful technical judgment, and sustained contribution.

A contributor may be invited to become a reviewer after they have shown consistent, constructive participation, such as:

  • submitting high-quality issues, examples, documentation, producers, or pull requests
  • giving careful technical feedback on proposals and reviews
  • helping clarify compatibility, validation, or implementation concerns
  • participating respectfully in discussions over time
  • showing good judgment about the project scope and vendor-neutral goals

A reviewer may be invited to become a maintainer after a longer pattern of trusted work, such as:

  • regularly reviewing significant changes with sound technical judgment
  • helping resolve design tradeoffs in a way that protects the specification
  • maintaining producer, tooling, documentation, or schema areas responsibly
  • demonstrating reliability, transparency, and respect for the Code of Conduct
  • earning the confidence of existing maintainers and the wider community

Maintainer invitations are made by existing maintainers. When new maintainers are added, the decision SHOULD be recorded publicly unless privacy or security concerns require discretion.

The project may refine this process as the community grows, but the goal SHOULD remain stable: responsibility is earned through sustained contribution, trust, and alignment with the open specification mission.

Where decisions happen

  • GitHub Discussions: design discussions, questions, roadmap topics, and early feedback.
  • GitHub Issues: bugs, inconsistencies, concrete proposals, and requests to change the specification.
  • Pull Requests: the authoritative place where wording, schemas, examples, code, and documentation are changed and reviewed.
  • Release Notes: the public record of published specification, schema, producer, or tooling changes.

Decision-Making principles

OSIRIS JSON follows the specification design principles with a focus on:

  • simplicity
  • vendor neutrality
  • extensibility without fragmentation
  • explicit behavior over implicit assumptions
  • cross-platform stability and compatibility
  • practical implementation by independent producers and consumers

The default decision model is rough consensus through public discussion and review. When consensus cannot be reached, the lead maintainer makes a decision and documents the rationale in the relevant issue, discussion, or pull request.

Change process

  1. Discuss the problem. Open an issue or discussion describing the use case, problem, and intended change.
  2. Prepare the change. Submit a pull request updating the specification text, schemas, examples, code, or documentation as needed.
  3. Review impact. Reviewers and maintainers evaluate correctness, clarity, compatibility, security, and implementation impact.
  4. Merge and release. Accepted changes are merged and released according to the project’s versioning, compatibility, and deprecation rules.

Types of changes

Editorial changes

Editorial changes are non-normative. They fix typos, improve clarity, restructure sections, or improve examples without changing requirements, validation behavior, or compatibility expectations.

Normative changes

Normative changes alter requirements, interpretation, validation behavior, compatibility expectations, or producer/consumer obligations. OSIRIS JSON uses JSON Schema for structural validation and follows established conventions such as RFC 2119 keywords for normative requirements.

Normative changes require careful review and SHOULD include examples, compatibility analysis, and migration guidance when applicable.

Taxonomy, registry, and extension guidance

These changes affect standard types, recommended namespaces, registries, or extension best practices. They SHOULD be reviewed for interoperability impact and the risk of fragmentation.

Versioning, compatibility, and rReleases

OSIRIS JSON uses Semantic Versioning 2.0.0 for specification releases.

The version field in an OSIRIS JSON document declares which specification version it conforms to. Producers and consumers are expected to follow the compatibility behavior described in the specification.

Draft and Pre-release versions

During development, versions may use SemVer pre-release notation, such as 1.0.0-DRAFT. Draft and pre-release versions are not considered stable and may change incompatibly until a stable release is published.

Deprecation policy

Deprecated features follow a defined lifecycle:

  1. announcement
  2. documentation and migration guidance
  3. transition period of at least one minor release cycle
  4. removal only in the next major release

Extension governance

OSIRIS JSON defines namespace rules and, when applicable, registry policy for well-known extension namespace prefixes. It does not govern the internal semantics of vendor or organization extensions. Consumers MUST treat values inside extensions as opaque unless they explicitly support that namespace.

Namespace registration in v1.0

For OSIRIS JSON v1.0, namespace registration is informal and community-driven:

  1. Document namespace usage publicly.
  2. Publish extension schemas for consumer reference when applicable.
  3. Coordinate with the OSIRIS JSON community to avoid collisions.

Organization namespaces SHOULD use reverse-domain patterns, such as org.example.* or com.example.*, to reduce collisions.

The osiris.custom.* namespace may be used for short-lived experiments and community drafts, but it is not collision-resistant. Producers SHOULD migrate to organization namespaces for persistent or production usage.

Transparency

Project decisions SHOULD be traceable. Significant decisions SHOULD be recorded in issues, discussions, pull requests, release notes, or governance updates. This helps contributors understand not only what changed, but why it changed.

Code of conduct

Participation in the OSIRIS JSON community is governed by the Code of Conduct.

Read the Code of Conduct