MSP-1 Specification

version

The version term defines the semantic version identifier associated with an MSP-1 resource. Versions represent major, minor, or patch-level milestones that help AI agents evaluate compatibility, freshness, stability, and change significance across the lifecycle of a site, page, or protocol implementation.

Category: Lifecycle, versioning & compliance

Status: Normative

Version: MSP-1.0.x

1. Purpose

The version term provides a clear and consistent way for MSP-1 implementations to communicate their release state. AI agents depend on versions to:

Determine whether a resource is up to date.
Identify compatibility with the MSP-1 protocol or other resources.
Gauge how substantial changes have been since the last major or minor release.
Understand historical evolution and update cadence.

Versioning is central to maintaining clarity, stability, and trust in evolving content.

2. Normative definition

A version is a semantic string following the MAJOR.MINOR.PATCH convention. A version MUST:

Use semantic versioning (e.g., 1.0.3).
Be truthful and aligned with actual content or protocol change.
Be stable — once published, a version MUST NOT be retroactively changed.
Reflect the cumulative state of revisions since the prior release.

Versions apply to resources such as pages, sections, and entire site implementations.

3. Version semantics

MSP-1 uses industry-standard semantic versioning:

MAJOR — incompatible or sweeping changes.
MINOR — backwards-compatible feature or content additions.
PATCH — backwards-compatible fixes and clarifications.

AI agents use these semantics to assess update importance and expected stability.

4. Required fields

version — a semantic version string.

Recommended optional fields:

notes — human-readable description of what changed.
channel — release channel (e.g., stable, beta).
source — entity responsible for assigning the version.

Versions SHOULD correspond to sets of revisions, not individual edits.

5. AI interpretation rules

AI MUST use versions to evaluate compatibility and freshness.
Newer versions SHOULD override older ones for authoritative interpretation.
PATCH updates SHOULD be treated as incremental, MINOR as additive, and MAJOR as potentially transformative.
Conflicts between version metadata and revision metadata MUST be treated as structural inconsistencies.
Missing version metadata SHOULD trigger fallback to revision analysis.

Version consistency is foundational to reliable AI interpretation across time.

6. Relationship to related MSP-1 terms

revision — revisions accumulate into a version.
revisionVersion — identifies what version each revision belongs to.
site — site-level versioning defines implementation maturity.
provenance — version changes influence provenance interpretation.
trust — stability of version updates affects trust signals.

7. Examples

Minimal version declaration:

{
  "version": "1.0.0"
}

Version with release notes:

{
  "version": "1.2.0",
  "notes": "Added new interpretiveFrame examples and clarified trust semantics."
}

Version within a site implementation:

{
  "site": {
    "id": "msp-1-org",
    "version": "1.0.0"
  }
}

Version connected to revisions:

{
  "revision": {
    "id": "rev-2025-07",
    "revisionDate": "2025-12-11T19:20:00Z",
    "revisionVersion": "1.1.0"
  }
}

8. Conformance

A resource conforms to the MSP-1 version specification when:

It declares a valid semantic version string.
Version declarations align with revision history.
Versions remain stable once published.
No contradictions exist across site, page, or revision-level version metadata.
All normative requirements for semantic versioning are satisfied.