Skip to main content

Versioning Strategy

This document defines versioning rules for PTI v1.0 APIs, events, and derived artifacts.

Normative language​

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are to be interpreted as described in RFC 2119.

Version identifiers​

PTI uses semantic versioning at two layers:

LayerFormatExample
Specificationpti-spec/Majorpti-spec/1.0
Artifact schemaname.vMajortrust_event.v1, trust_intelligence.v1
HTTP APIMajor.Minor in X-PTI-Version1.0, 1.1

Major version increments indicate breaking changes. Minor API versions MUST remain backward compatible for existing clients.

Schema compatibility rules​

Backward compatible (minor) changes​

The following MAY occur without a major bump:

  • Adding OPTIONAL fields
  • Adding new event_type values
  • Adding new enum values when clients ignore unknown values
  • Adding new error codes

Breaking (major) changes​

The following MUST trigger a major version:

  • Removing or renaming required fields
  • Changing field types or semantics
  • Tightening validation previously accepted
  • Removing enum values
  • Changing signature algorithms without dual support window

API negotiation​

Clients MUST send:

X-PTI-Version: 1.0

Servers MUST:

  1. Process requests at the highest mutually supported minor version.
  2. Reject unsupported major versions with PTI-4001.
  3. Include X-PTI-Version in responses indicating the version used.

Capability discovery​

GET /registry/v1/capabilities

Response:

{
  "spec_version": "pti-spec/1.0",
  "api_versions": ["1.0", "1.1"],
  "schemas": {
    "trust_event": ["v1"],
    "trust_intelligence": ["v1"]
  },
  "deprecated": []
}

Event schema evolution​

Producers MUST declare schema_version on every event. Consumers of async streams MUST branch on schema_version before deserialization.

Migration pattern for new major event versions:

Dual-write periods SHOULD last at least 90 days for federation partners.

Intelligence artifact versioning​

Trust reports MUST include schema_version. Lookup clients MUST validate version before parsing contexts blocks.

Adding explainability fields is backward compatible. Removing drivers MUST NOT occur without major bump.

Deprecation policy​

StageMinimum durationOperator obligation
Announced90 daysPublish deprecation notice in capabilities endpoint
Warning60 daysLog warnings for deprecated clients
Retired—Return PTI-4001 or 410 Gone for retired endpoints

Emergency security retirements MAY shorten timelines with 14-day minimum notice except for active exploitation.

Federation version alignment​

Federated registries MUST agree on:

  • Minimum supported event schema
  • Assertion signature suite
  • Replication protocol version

Version mismatch MUST trigger federation health alert and SHOULD block new assertion exchange until resolved.

Client implementation checklist​

  1. Pin X-PTI-Version explicitly — do not rely on server default.
  2. Parse unknown JSON fields gracefully.
  3. Monitor deprecated array in capabilities responses.
  4. Maintain integration tests against staging next version channel when offered.