12 Versioning and compatibility

This chapter defines the versioning strategy for the OSIRIS specification, compatibility guarantees and the deprecation policy for features and fields across specification versions.

12.1 Version numbering

12.1.1 Specification versioning

The OSIRIS specification uses Semantic Versioning 2.0.0 (SemVer) to communicate the nature of changes across releases.

Version format:

MAJOR.MINOR.PATCH

Semantic meaning:

• MAJOR version increments indicate incompatible changes that break backwards compatibility with consumers or producers implementing prior versions.
• MINOR version increments indicate backwards-compatible additions (new optional fields, new standard types, new validation rules that do not invalidate existing documents).
• PATCH version increments indicate backwards-compatible clarifications, corrections and non-normative improvements to the specification text without changing behavior.

Examples:

• 1.0.0 > Initial stable release
• 1.1.0 > Added new optional resource types, new connection types
• 1.0.1 > Clarified ambiguous wording in validation rules
• 2.0.0 > Changed required field structure (breaking change)

[!NOTE] The specification version is independent from the document version field. The version field in an OSIRIS document (e.g. "version": "1.0.0") declares which specification version the document conforms to, not the version of the document itself.

12.1.2 Document version field

The version field in an OSIRIS document MUST match the specification version the document conforms to.

Example:

{
  "version": "1.0.0",
  "metadata": { ... },
  "topology": { ... }
}

Producers emitting documents conforming to OSIRIS v1.0 MUST set "version": "1.0.0". Future specification versions (e.g. OSIRIS v1.x.y) will define their own version string values. The v1.0 schema endpoint MAY validate any 1.x.y for forward compatibility, but OSIRIS v1.0.0 producers MUST emit 1.0.0.

12.1.3 Pre-release and draft versions

During OSIRIS specification development (prior to the stable OSIRIS v1.0.0 release), pre-release builds were sometimes labeled using SemVer pre-release notation such as:

1.0.0-DRAFT

Pre-release versions:

• MUST NOT be considered stable
• MAY change incompatibly between pre-release iterations
• SHOULD NOT be used in production systems
• Are intended for community review and implementation feedback

OSIRIS v1.0 documents MUST NOT include pre-release suffixes in the version field.

12.1.4 Version discovery

Consumers MUST read the version field to determine document conformance.

Consumers SHOULD:

• Accept documents with versions they fully support
• Accept documents with higher PATCH versions within the same MAJOR.MINOR series
• Optionally accept documents with higher MINOR versions if forward-compatible
• Warn or reject documents with unknown MAJOR versions

Decision matrix:

Consumers implementing forward compatibility (ignoring unknown fields and types) MAY accept documents with higher MINOR versions.

12.1.5 Version negotiation

In systems where producers and consumers interact directly (e.g. APIs, pipelines), version negotiation MAY be implemented:

Producer capabilities: Producers SHOULD advertise supported output versions:

{
  "supported_versions": ["1.0.0", "1.1.0"]
}

Consumer preferences: Consumers SHOULD request their preferred version:

{
  "accept_versions": ["1.0.0"]
}

If no common version exists, the system SHOULD fail gracefully with a clear error message.

12.2 Backwards compatibility

12.2.1 Compatibility guarantees

OSIRIS provides the following compatibility guarantees within MAJOR version series (e.g. all 1.x.y versions):

Producers (documents generators):

• Documents valid under v1.0.0 MUST remain valid under v1.x.y
• Required fields MUST NOT be added
• Field semantics MUST NOT change incompatibly
• Validation rules MUST NOT become stricter for existing fields

Consumers (documents processors):

• Consumers implementing v1.0.0 MUST accept documents from v1.x.y without error (if following forward-compatibility rules)
• Unknown optional fields MUST be ignored
• Unknown types (resource, connection, group) MUST be accepted if structurally valid
• Unknown extension namespaces MUST be accepted

Stability across MINOR versions:

• New optional fields MAY be added
• New standard types MAY be added to the taxonomy
• New validation rules MAY be added (Level 3 domain rules only)
• Documentation clarifications MAY be made

12.2.2 Breaking changes (MAJOR version increments)

Breaking changes require a MAJOR version increment (e.g. 1.x > 2.0).

Examples of breaking changes:

• Adding a new required field to resources, connections or groups
• Changing the structure of existing required fields (e.g. making provider an array instead of an object)
• Removing support for previously valid field values
• Changing type naming conventions (e.g. from compute.vm to compute/vm)
• Changing namespace prefix rules (e.g. from osiris.* to osiris:*)
• Making previously optional validation rules mandatory (e.g. requiring Level 2 validation)

When a MAJOR version increment occurs:

• The specification MUST document all breaking changes clearly
• A migration guide SHOULD be provided
• Deprecation warnings SHOULD have been issued in prior MINOR releases where feasible

12.2.3 Forward compatibility rules

To maximize forward compatibility, consumers MUST implement these behaviors:

Unknown fields: Consumers MUST ignore unknown fields at all levels (top-level, metadata, topology, resource, connection, group).

Example: A v1.1 document introduces metadata.generator.platform:

{
  "version": "1.1.0",
  "metadata": {
    "timestamp": "2026-01-23T18:15:00Z",
    "generator": {
      "name": "manual",
      "version": "1.0.0",
      "platform": "linux"  // Added in v1.1
    }
  }
}

A v1.0 consumer MUST accept this document and ignore the platform field.

Unknown types: Consumers MUST accept unknown resource, connection and group types if the objects are structurally valid.

Example: A v1.2 document introduces compute.edgefunction:

{
  "id": "edge-fn-001",
  "type": "compute.edgefunction",  // Added in v1.2
  "provider": { "name": "cloudflare" }
}

A v1.0 consumer MUST accept this resource even if compute.edgefunction is not recognized.

Unknown extensions: Consumers MUST accept unknown extension namespaces.

Example:

"extensions": {
  "osiris.newvendor": { ... }  // Unknown namespace
}

Consumers MUST preserve unknown namespaces when re-exporting documents.

12.2.4 Backwards compatibility testing

Specification maintainers SHOULD:

• Maintain a test suite of v1.0 documents
• Verify that all v1.0 documents remain valid in v1.x releases
• Automate compatibility testing in the release pipeline
• Document any exceptions or edge cases

Implementers SHOULD:

• Test their parsers and consumers against documents from multiple specification versions
• Validate forward-compatibility by accepting documents with unknown fields and types
• Provide configuration options for strictness levels (permissive, standard, strict)

12.3 Deprecation policy

12.3.1 Deprecation process

Features, fields or patterns MAY be deprecated but MUST NOT be removed within a MAJOR version.

Deprecation lifecycle:

1. Announcement: Feature is marked as deprecated in specification release notes
2. Documentation: Specification includes deprecation warnings and migration guidance
3. Transition period: Feature remains supported for at least one full MINOR version cycle
4. Removal: Feature is removed only in the next MAJOR version

Example timeline:

• v1.0.0: Feature X is fully supported
• v1.1.0: Feature X is deprecated (warning added)
• v1.2.0: Feature X remains deprecated (still valid)
• v2.0.0: Feature X is removed (breaking change)

12.3.2 Deprecation notices

Deprecated features MUST be clearly marked in the specification.

Specification markup:

> [!WARNING]
> **DEPRECATED in v1.1.0:** The `legacy_field` is deprecated and will be removed in v2.0.0.
> Use `new_field` instead. See migration guide in Appendix E.

Migration guidance: Deprecation notices SHOULD include:

• Version when deprecation was introduced
• Version when removal is planned
• Replacement feature or migration path
• Rationale for deprecation
• Code examples showing old and new patterns

12.3.3 Handling deprecated features

Producers:

• SHOULD avoid emitting deprecated fields in new documents
• MAY continue to emit deprecated fields for backwards compatibility
• SHOULD provide configuration to disable deprecated field emission

Consumers:

• MUST continue to accept deprecated fields until they are removed
• MAY log warnings when deprecated fields are encountered
• SHOULD support migration by accepting both old and new patterns

Example: Deprecated field support

{
  "id": "srv-001",
  "type": "compute.server",
  "legacy_identifier": "SRV001",  // Deprecated in v1.1
  "provider": {
    "name": "custom",
    "native_id": "SRV001"  // Preferred in v1.1+
  }
}

A v1.1+ consumer MUST accept both legacy_identifier and provider.native_id, even though legacy_identifier is deprecated.

12.3.4 Extension deprecation

Custom extensions and vendor-specific namespaces follow their own lifecycle and are not governed by the OSIRIS deprecation policy.

However, well-known registered namespaces (e.g. osiris.aws, osiris.azure) SHOULD:

• Maintain compatibility within their own versioning schemes
• Document deprecations clearly
• Provide migration paths when changing semantics

Consumers MUST treat deprecated extensions as valid and preserve them during re-export.

12.3.5 Standard type deprecation

Standard resource, connection and group types MAY be deprecated if:

• A superior replacement type is introduced
• The type was found to be poorly defined or ambiguous
• The type duplicates functionality of another type

Deprecated types:

• MUST remain valid for the remainder of the MAJOR version
• MUST be documented with replacement guidance
• MAY be removed in the next MAJOR version

Example:

> [!WARNING]
> **DEPRECATED in v1.2.0:** The type `network.loadbalancer.classic` is deprecated.
> Use `network.loadbalancer` with `properties.type = "classic"` instead.