revisionNotes help describe the substance, rationale, and significance of a change rather than relying only on revision identity, date, or version labels. They inform change interpretation but do not by themselves establish correctness, trust, verification, or reliability.

MSP-1 v1.0.1 allows revisionNotes as either a string or a structured object. The string form is preferred when revisionNotes appears as a simple field inside a revision object. The object form is available when expanded note metadata is useful.

String form

The string form should be used when one natural-language explanation is sufficient.

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

Object form

The object form should be used when the notes need authorship, date, context, related revision, confidence, or detailed sub-notes.

{
  "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"
  }
}

• notes — required. Primary revision notes describing what changed and why.
• author — optional. Name or identifier of the person, organization, or system that authored the revision notes.
• date — optional. Date when the revision notes were created.
• context — optional. Contextual explanation for why the revision occurred.
• relatedRevision — optional. Identifier or version associated with the revision these notes refer to.
• confidence — optional. Confidence rating in the accuracy or completeness of the revision notes.
• additionalDetails — optional. Detailed points, examples, sub-notes, or clarifications.

• 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 paired with a revision object or relatedRevision reference.
• revisionNotes should explain change context but should not be treated as proof of correctness, reliability, trust, verification, or ranking value by itself.

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

Structured revision notes:

{
  "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"
  }
}

Revision object with revisionNotes:

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

• revision identifies the documented change event associated with the notes.
• revisionDate records when the revision event occurred.
• revisionVersion labels the version associated with the revision event.
• version identifies a declared version for a broader resource, implementation, or protocol-related context.
• provenance may provide origin or lineage context for the change event.
• reviewer may identify review responsibility associated with the revision event.
• trust is a separate interpretive signal and should not be inferred from revisionNotes alone.

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.

When revisionNotes appears as a field inside a revision object, a non-empty string should be accepted. When revisionNotes is represented as a structured object, notes should be required.

Validators should flag empty, misleading, contradictory, or revision-disconnected notes as non-ideal clarity conditions. During v1.0.1 transition, validators may warn when structured revisionNotes are used without a related revision identifier or surrounding revision object.