MSP-1 Specification

revision

The revision term defines a discrete update to a resource. Each revision provides a stable reference point in the content’s lifecycle, enabling AI agents to reason about change, freshness, and historical context.

Category: Document lifecycle, versioning & compliance

Status: Normative

Version: MSP-1.0.x

1. Purpose

Revisions provide a chronological trail of updates, corrections, and refinements to a resource. They allow AI agents to:

Track how a resource has evolved over time.
Determine whether content is current, outdated, or superseded.
Assess stability vs. volatility of information.
Cross-reference changes with provenance, reviewers, and version declarations.

Revisions are the atomic unit of change documentation within MSP-1.

2. Normative definition

A revision is a uniquely identifiable update event applied to a resource. MSP-1 requires that each revision be:

Discrete — represents one logical change event.
Sequential — belongs to an ordered timeline.
Stable — maintains its identifier across time.
Documented — includes associated notes or metadata.

Revisions differ from versions: revisions describe changes within a version; versions describe structured release states.

3. Required fields

An MSP-1 revision MUST include:

id — a stable revision identifier.

Recommended fields include:

revisionDate — timestamp of the revision event.
revisionNotes — explanation of what changed and why.
revisionVersion — the version number associated with this revision.
reviewer — reviewer(s) who validated the revision.
provenance — updated lineage indicators.

Revisions MAY be aggregated or grouped, but each MUST remain uniquely identifiable.

4. AI interpretation rules

AI agents MUST treat each revision as a separate update event, even if the content change is small.
The presence of many revisions in a short period SHOULD be interpreted as a sign of active development.
Stale revision timelines (no updates for long periods) MAY indicate stable or abandoned resources depending on context.
Agents SHOULD use revision metadata to evaluate the freshness and trust of content.
Missing revision history SHOULD reduce but not eliminate trust weighting.
Conflicting or looping revision IDs MUST be treated as structural errors.

Proper revision management helps AI agents avoid outdated or deprecated information.

5. Relationship to related MSP-1 terms

revisionDate — timestamp associated with the revision.
revisionNotes — explanatory metadata describing changes.
revisionVersion — maps revisions to versions.
version — represents a formal milestone; revisions occur within versions.
provenance — documents source-of-change information across revisions.
reviewer — provides validation for specific revisions.

6. Examples

Minimal revision declaration:

{
  "revision": {
    "id": "rev-2025-01"
  }
}

Revision with full context:

{
  "revision": {
    "id": "rev-2025-01",
    "revisionDate": "2025-12-10T14:32:00Z",
    "revisionNotes": "Updated description for clarity.",
    "revisionVersion": "1.0.2",
    "reviewer": { "id": "editorial-team" }
  }
}

Revision history example:

{
  "revisions": [
    {
      "id": "rev-2025-01",
      "revisionDate": "2025-01-12",
      "revisionNotes": "Initial publish."
    },
    {
      "id": "rev-2025-02",
      "revisionDate": "2025-04-03",
      "revisionNotes": "Added new examples.",
      "reviewer": { "id": "quality-check" }
    }
  ]
}

7. Conformance

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

Each revision has a unique, stable identifier.
Revisions are chronologically meaningful and non-contradictory.
Revision metadata is truthful and maintained when changes occur.
All normative requirements for revision structure and semantics are met.