Definition

msp:revisionNotes provides natural-language change context for a revision. It may describe what changed, why the change was made, whether the revision was corrective, structural, editorial, conceptual, or otherwise meaningful, and what context is needed to interpret the update.

The revisionNotes term should not be confused with msp:revisionDate or msp:revisionVersion. revisionNotes explain what changed and why; revisionDate records when the change occurred; revisionVersion labels the version associated with the revision.

Usage

The lean string form is preferred for ordinary revision metadata.

{
  "msp:revisionNotes": "Expanded examples and clarified definitions for improved AI readability."
}

The structured form may be used when note authorship, date, context, confidence, related revision, or detailed sub-notes are needed.

{
  "msp:revisionNotes": {
    "notes": "Updated the definition of parent to clarify single-parent hierarchy rules.",
    "author": "editorial-team",
    "date": "2026-06-24",
    "context": "terminology harmonization",
    "relatedRevision": "rev-2026-06-24",
    "confidence": "high"
  }
}

Inside a revision object, the lean string form keeps the revision declaration compact.

{
  "msp:revision": {
    "id": "rev-2026-06-24",
    "revisionDate": "2026-06-24",
    "revisionNotes": "Added explicit AI interpretation guidance and clarified terminology.",
    "revisionVersion": "1.0.1"
  }
}

Guidance

• revisionNotes should accurately describe the declared revision.
• revisionNotes should avoid vague statements when meaningful changes occurred.
• revisionNotes should be understandable as natural-language change context.
• revisionNotes should normally be associated with a corresponding revision object or relatedRevision reference.
• revisionNotes should explain change context but should not be treated as proof of correctness, reliability, or trust by itself.

Deprecated compatibility note

The deprecated compliance term should not be emitted in new MSP-1 v1.0.1 declarations. revisionNotes metadata should not reactivate compliance language or imply that revision explanation alone establishes trust, correctness, or long-term reliability.

Related Terms