Versioning Policy

1. Overview

This document defines the versioning policy for the Cascade Protocol semantic vocabularies, including rules for version numbering, backward compatibility guarantees, deprecation timelines, and the relationship between vocabulary versions and SDK versions.

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in RFC 2119.

The Cascade Protocol comprises multiple independently versioned vocabularies that share a common version numbering scheme. Each vocabulary evolves at its own pace, but all vocabularies adhere to the same compatibility guarantees described in this policy.

2. Version Numbering

Cascade Protocol vocabularies use a two-part version number in the format MAJOR.MINOR (for example, 1.3 or 2.0).

When the MAJOR version is incremented, the MINOR version resets to 0. There is no PATCH component for vocabularies; small corrections that do not affect the schema (such as fixing a typo in a description) are published under the same version number with an updated dct:modified date.

3. Current Stable Versions

The following table lists the current stable version of each Cascade Protocol vocabulary.

4. Breaking Changes

A breaking change is any modification to a vocabulary that could cause a conforming consumer to fail to read or correctly interpret existing data. Breaking changes MUST trigger a MAJOR version increment.

The following changes are classified as breaking:

Example: Breaking Change

# Before (health v2.2):
health:heartRate a owl:DatatypeProperty ;
    rdfs:range xsd:integer .

# After (health v3.0) - type changed from integer to decimal:
health:heartRate a owl:DatatypeProperty ;
    rdfs:range xsd:decimal .

# This is a breaking change (B4) because consumers expecting
# xsd:integer may fail to parse xsd:decimal values.

5. Non-Breaking Changes

A non-breaking change is any modification that maintains full backward compatibility with existing consumers and data. Non-breaking changes trigger a MINOR version increment.

The following changes are classified as non-breaking:

Example: Non-Breaking Change

# health v2.1 adds a new optional property to VitalSigns:
health:respiratoryRate a owl:DatatypeProperty ;
    rdfs:label "Respiratory Rate" ;
    rdfs:domain health:VitalSigns ;
    rdfs:range xsd:integer ;
    rdfs:comment "Breaths per minute. Added in v2.1." .

# This is a non-breaking change (N1). SDKs built for health v2.0
# will simply ignore the respiratoryRate property when reading data
# written with health v2.1.

6. Backward Compatibility Guarantee

The Cascade Protocol makes the following compatibility guarantees to ensure that data remains readable across vocabulary versions.

6.1 Same-Major-Version Reading

A conforming SDK MUST be able to read data produced by any vocabulary version that shares the same MAJOR version number, regardless of MINOR version differences.

6.2 Backward Compatibility (Newer SDK Reads Older Data)

An SDK built for a higher MINOR version MUST successfully read data written with a lower MINOR version of the same MAJOR version. Properties that are absent from older data default to undefined/null.

6.3 Forward Compatibility (Older SDK Reads Newer Data)

An SDK SHOULD be able to read data from a higher MINOR version within the same MAJOR version. Because new MINOR versions only add optional properties, an older SDK will simply not recognize or display the newer properties. The data it does understand remains correct.

7. Deprecation Timeline

Vocabulary terms (classes, properties, named individuals) may be deprecated when they are superseded by better alternatives. Deprecation follows a structured timeline to give consumers adequate time to migrate.

7.1 Deprecation Rules

• Deprecated terms MUST be supported for at least 2 MINOR versions after the deprecation notice before they may be removed in the next MAJOR version.
• Deprecated terms MUST NOT be removed within the same MAJOR version in which they were deprecated.
• When a term is deprecated, a replacement SHOULD be identified in the deprecation notice.

7.2 Deprecation Signals

Deprecation MUST be signaled through all of the following channels:

7.3 Example: Deprecation Lifecycle

# health v2.1 - property is deprecated
health:bpmReading a owl:DatatypeProperty ;
    rdfs:label "BPM Reading (Deprecated)" ;
    owl:deprecated "true"^^xsd:boolean ;
    rdfs:comment "Deprecated in v2.1. Use health:heartRate instead." ;
    rdfs:seeAlso health:heartRate .

# health v2.2 - deprecated property still present (1 minor version later)
# health v2.3 - deprecated property still present (2 minor versions later)
# health v3.0 - property MAY be removed (next major version)

8. Schema Version Embedding

Every Cascade Protocol record MUST embed a schema version so that consumers can determine which vocabulary definitions apply to the data.

8.1 The cascade:schemaVersion Property

The cascade:schemaVersion property is a required property on all Cascade Protocol records. It indicates the overall protocol schema version under which the data was serialized.

8.2 Turtle Example

@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
@prefix pots: <https://ns.cascadeprotocol.org/pots/v1#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<#pots-check-abc123> a pots:POTSCheckResult ;
    cascade:schemaVersion "1.3" ;
    pots:date "2026-01-15T10:30:00Z"^^xsd:dateTime ;
    pots:protocol "nasaLean" ;
    pots:potsThresholdMet "true"^^xsd:boolean .

8.3 JSON-LD Context

When using JSON-LD serialization, the schema version is included in the @version field of the JSON-LD context, in addition to being present as a data property on the record itself.

{
  "@context": {
    "@version": 1.1,
    "cascade": "https://ns.cascadeprotocol.org/core/v1#",
    "pots": "https://ns.cascadeprotocol.org/pots/v1#",
    "schemaVersion": "cascade:schemaVersion"
  },
  "@type": "pots:POTSCheckResult",
  "schemaVersion": "1.3"
}

9. SDK Versioning

SDKs that implement the Cascade Protocol use Semantic Versioning (semver) with the three-part format MAJOR.MINOR.PATCH.

9.1 SDK Version Independence

SDK versions are independent of vocabulary versions. An SDK at version 3.1.0 may support vocabulary versions ranging from health v1.0 through health v2.2.

9.2 Vocabulary Support Documentation

Each SDK release MUST document which vocabulary versions it supports. This information appears in the SDK README and changelog.

# CascadeSDK v2.4.0
## Supported Vocabularies
- cascade (core): v2.0 - v2.2
- clinical: v1.0 - v1.5
- health: v2.0 - v2.2
- checkup: v2.0 - v3.0
- pots: v1.0 - v1.3
- coverage: v1.0

9.3 SDK and Vocabulary Lifecycle

When a new vocabulary MAJOR version is released, the SDK SHOULD support both the old and new MAJOR versions for at least one SDK MINOR release cycle to give consumers time to migrate their data.

10. Summary of Change Classification

The following table provides a quick reference for classifying changes.