Lifecycle & versioning policy

Semantic versioning rules, deprecation timelines, and retirement policy — including how to handle external regulatory withdrawals (the NTS situation).

What already exists

• source/03-standards/trust-framework/docs/release-version-register.md — version log
• Schemas use semantic versioning (MAJOR.MINOR.PATCH). Currently v3.5.0 stable (per @pdtf/schemas package.json).
• Older overlay versions kept for backward compat in v3/overlays/: baspi4, nts, ntsl.

Three independent version domains

The standards stack carries three artefacts on separate version tracks. The page below treats them distinctly — they do not share a release cadence.

• PDTF schemas — currently 3.5.0 (@pdtf/schemas).
• Trust framework — currently 0.3.0, pre-1.0 (@pdtf/trust-framework).
• API spec — see the API versioning section below.

API spec versioning

The PDTF API spec is versioned independently of the schemas. Files live in source/03-standards/api/:

• pdtf-api-1.1.0.json
• pdtf-api-1.2.0.yaml
• pdtf-api-1.3.0.yaml
• pdtf-api-2.0.0.yaml — major break from the 1.x line.

Lifecycle policy for the 1.x → 2.x transition (N-1 support window, deprecation markers, sunset) is not yet defined — see the open questions below.

Policy questions to resolve

1. How long is N-1 supported? When v4 ships, how long does v3 stay supported?
2. Deprecation marking — JSON Schema deprecation keyword + machine-readable sunset date
3. What happens when an upstream form is withdrawn? (the NTS case — successor is months away from MHCLG)
4. Major-version cadence — how often? Annual? Driven by demand?
5. Per-overlay vs whole-framework versioning — overlays evolve independently from the base

Worked case study: NTS overlay retirement

NTS withdrew the Material Information v1.0 guidance in late 2025 (DMCC Act 2024 superseded the underlying regulation). OPDA's nts.json and ntsl.json overlays implement guidance that is no longer authoritative — but firms using them are still operating compliantly under the transitional arrangements.

The lifecycle policy needs to define:

• Mark nts.json as deprecated in the schema (not yet retired)
• Track MHCLG's successor publication (Oct 2025 consultation)
• When MHCLG publishes, ship a new mhclg-material-info.json overlay
• Sunset date for the old NTS overlay — proposed: 6 months after MHCLG go-live (no policy ratified yet)

See source/08-external-references/nts/README.md for the full context.