• Interpret technical vs. editorial changes.
• Evaluate whether content meaning has shifted significantly.
• Distinguish minor corrections from major updates.
• Track the rationale behind evolving information.

Revision notes are essential for trust, transparency, and long-term content reliability.

• Be truthful — accurately describe what changed.
• Be specific — avoid vague or generic statements.
• Be human-readable — intended primarily for human oversight.
• Be tied to a specific revision — cannot exist without a corresponding revision entry.

Notes SHOULD focus on meaning-related changes, not minor formatting-only edits.

• Be a plain-text natural-language string.

Recommended best practices:

• Summarize intent and scope of the change.
• Clarify whether the revision affects accuracy, clarity, structure, or compliance.
• Include reviewer involvement if part of a review-driven update.

• AI agents MUST use revisionNotes to classify the update type (e.g., editorial, factual, structural).
• Significant wording changes SHOULD increase perceived information freshness.
• Minor edits (e.g., typographical fixes) SHOULD NOT substantially affect trust weighting.
• Conflicting or misleading notes MUST be treated as a potential trust violation.
• If revisionNotes is missing, AI SHOULD rely on revisionDate and metadata diffs but with reduced certainty.

Revision notes help prevent AI misinterpretation by providing explicit change context.

• revision — the container for revisionNotes.
• revisionDate — timestamp paired with the notes.
• revisionVersion — identifies the version the notes apply to.
• provenance — updates in provenance may be explained via revisionNotes.
• reviewer — reviewers may validate or influence the change rationale.

{
  "revisionNotes": "Corrected description for improved clarity."
}

Detailed explanation example:

{
  "revisionNotes": "Updated the definition of 'parent' to clarify single-parent hierarchy rules and added examples for AI interpretation."
}

Complete revision object with notes:

{
  "revision": {
    "id": "rev-2025-04",
    "revisionDate": "2025-12-11T15:12:00Z",
    "revisionNotes": "Added explicit AI interpretation rules and clarified terminology.",
    "revisionVersion": "1.0.4"
  }
}

• It provides a truthful, clear explanation of each revision.
• The notes align with the actual content changes.
• The notes are paired with valid revision metadata.
• All normative requirements for clarity and accuracy are satisfied.