# Suggestion Schema — Layer 3 Specialized Document Type # KNO Schema Version: 0.1.0 # # Layer 3 schema that extends document-schema.kno for collaborative suggestions. # A suggestion is a proposed amendment to another .kno entity, with its own # lifecycle (draft → submitted → review → accepted/rejected/withdrawn). # # KEY DISTINCTION from other document types: # - A suggestion is a PROPOSAL about another entity, not standalone content # - It has a target entity + version, amendment content, and lifecycle state # - Accepting a suggestion creates a new version of the target entity via VCS # # Three-Gate Test (from rfc-versioning-collaboration-design.md §7a): # G1 Distinctness: Yes — a proposed amendment to another entity is fundamentally # different from the entity itself # G2 Reusability: Yes — applies to RFCs, KB articles, and spec suggestions # G3 Clarity: Yes — separates "proposal" from "entity being amended" # # EXTENDS: document-schema.kno (which composes identity, history, quality) # ENABLES: Suggestion instances (content/suggestions/*.kno, future) # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (composed from identity-schema.kno) # ============================================================================= id: 01KJXVS9W13WMY2NA2DSFKCCAS slug: suggestion-schema type: spec version: 0.1.0 # ============================================================================= # STANDARD TIER (inherited from document-schema.kno) # ============================================================================= title: "Suggestion Schema" purpose: | Define the schema for collaborative suggestion entities. **What is a Suggestion?** A suggestion is a proposed amendment to an existing .kno entity. It targets a specific version of the entity, describes what should change, and follows a lifecycle from draft through review to resolution (accepted, rejected, or withdrawn). **Suggestion vs Direct Edit**: | Aspect | Suggestion | Direct Edit | |-------------|-------------------------------|------------------------| | Who | Contributor / admin | Maintainer / admin | | Flow | Propose → Review → Merge | Edit → Commit | | Tracking | Full lifecycle with provenance| VCS commit history | | Reversible | Can be rejected/withdrawn | Requires revert commit | **Layer 3 Position**: Suggestion extends document (Layer 2), which composes identity, history, and quality (Layer 1). **Design source**: docs/planning/rfc-updates-v1/rfc-versioning-collaboration-design.md §4, §7 # ============================================================================= # RICH TIER — Relationships (Edge Maximization) # ============================================================================= provenance: origin: id: 01KJXVS9W13WMY2NA2DSFKCCAS timestamp: "2026-03-05" tool: ai-assisted-authoring taxonomy: topics: - collaboration - amendments - proposals - review - version-control keywords: - suggestion - amendment - proposal - review - collaboration - patch - diff relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type" depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to kno@0.0.9 kernel" - xri: "kno://specs/history-schema" reason: "Suggestion lifecycle tracked via history primitives" composes: - xri: "kno://specs/identity-schema" reason: "Layer 1: id, slug, type" - xri: "kno://specs/history-schema" reason: "Layer 1: _history, lifecycle transitions" - xri: "kno://specs/quality-schema" reason: "Layer 1: quality metadata" related_to: - xri: "kno://specs/rfc-schema" reason: "Primary target type for suggestions (RFC amendments)" - xri: "kno://rfcs/rfc-019-vcs-contract" reason: "Accepted suggestions trigger VCS commit operations" - xri: "kno://rfcs/rfc-018-provenance-assertion" reason: "Suggestion provenance follows assertion model" quality: completeness: 0.85 last_reviewed: "2026-03-05" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY # ============================================================================= _history: retention: hybrid format: snapshot versions: - version: "0.1.0" date: "2026-03-05" author: "claude" summary: "Initial suggestion schema" changes: - "Created as Layer 3 schema extending document-schema.kno" - "Defined suggestion lifecycle (draft/submitted/review/accepted/rejected/withdrawn)" - "Defined amendment types (patch/replacement/addition)" - "Defined target, resolution, and relationship predicates" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft description: | ## What is a Suggestion? A **suggestion** is a proposed amendment to an existing .kno entity. It encapsulates what should change, why, and who is proposing it. ## Suggestion Lifecycle ``` draft → submitted → review → accepted / rejected / withdrawn ``` | Status | Meaning | |-----------|--------------------------------------------------| | draft | Work in progress, editable by author | | submitted | Proposed for review, no further edits | | review | Under active maintainer review | | accepted | Incorporated into a new version of target entity | | rejected | Declined by maintainer with reason | | withdrawn | Retracted by the original author | ## Valid Status Transitions ``` draft → submitted (author submits for review) draft → withdrawn (author retracts before submission) submitted → review (maintainer picks up) submitted → withdrawn (author retracts) review → accepted (maintainer accepts, new version created) review → rejected (maintainer declines with reason) review → withdrawn (author retracts during review) ``` ## Amendment Types | Type | Use Case | |-------------|-------------------------------------------------| | patch | Small fix — provide unified diff | | replacement | Replace a section — provide new content | | addition | Add new content — provide content and location | ## Acceptance Flow When a suggestion is accepted: 1. Maintainer provides merged content (target entity + suggestion applied) 2. A new version of the target entity is committed via VCS 3. The commit metadata includes `trigger: "synthesis"` and the suggestion XRI 4. The suggestion's `resolution` field is populated with the new version ref ## Relationship Predicates | Predicate | Direction | Meaning | |------------|--------------------|------------------------------------------| | `amends` | suggestion → entity| Proposes a change to a specific version | | `supersedes` | entity → entity | One version replaces another (on accept) | ## Stale Suggestion Policy Suggestions against non-current versions of the target entity are considered stale. They are archived internally but not surfaced in public API responses (Q8 resolution). # =========================================================================== # SCHEMA DEFINITION # =========================================================================== schema: # ------------------------------------------------------------------------- # Required Fields # ------------------------------------------------------------------------- required: - id - type - title - status - target - amendment - author # ------------------------------------------------------------------------- # Field Definitions # ------------------------------------------------------------------------- properties: # --- INHERITED FROM IDENTITY.KNO (Layer 1) --- id: type: string description: "Suggestion ULID" slug: type: string description: "Human-readable slug for the suggestion" pattern: "^[a-z0-9][a-z0-9-]*$" type: type: string const: suggestion description: "Entity type, always 'suggestion'" version: type: string description: "Semantic version of this suggestion entity" pattern: "^\\d+\\.\\d+\\.\\d+$" # --- INHERITED FROM DOCUMENT.KNO (Layer 2) --- title: type: string description: "Human-readable title for the suggestion" examples: - "Clarify Named XRI syntax with ABNF grammar" - "Add versioning requirements to Section 5" # --- SUGGESTION-SPECIFIC FIELDS --- status: type: string enum: [draft, submitted, review, accepted, rejected, withdrawn] description: "Current lifecycle state of the suggestion" target: type: object description: "The entity being amended" required: [xri, version] properties: xri: type: string description: "XRI of the target entity (e.g., pspace://rfc:rfc-001-kno-format)" version: type: string description: "Version of the target entity this suggestion applies to" section: type: string description: "Specific section within the entity (e.g., '3.2')" amendment: type: object description: "The proposed change" required: [type, description] properties: type: type: string enum: [patch, replacement, addition] description: "Kind of amendment" description: type: string description: "Human-readable description of the proposed change" content: type: string description: "The proposed new content (for replacement/addition types)" diff: type: string description: "Unified diff showing the change (for patch type)" author: type: object description: "Who proposed the suggestion" required: [xri] properties: xri: type: string description: "XRI of the contributor (e.g., pspace://user/01HXYZ...)" name: type: string description: "Display name of the contributor" resolution: type: object description: "Populated when the suggestion reaches a terminal state" properties: versionRef: type: string description: "VCS version ref if accepted (ULID of the new version)" incorporatedIn: type: string description: "Version number of the target entity that incorporated this suggestion" review_notes: type: string description: "Maintainer notes (for accepted or rejected)" # --- TEMPORAL --- created: type: string format: date-time description: "ISO 8601 timestamp of suggestion creation" updated: type: string format: date-time description: "ISO 8601 timestamp of last update" # --- RELATIONSHIPS --- relationships: type: object properties: amends: type: array description: "Target entities this suggestion proposes to change" items: type: object properties: xri: type: string reason: type: string # ------------------------------------------------------------------------- # Example Instance # ------------------------------------------------------------------------- example: | $schema: suggestion@0.1.0 id: 01KXYZ123ABC456DEF789GHI slug: clarify-named-xri-syntax type: suggestion version: 0.1.0 title: "Clarify Named XRI syntax with ABNF grammar" status: submitted target: xri: "pspace://rfc:rfc-001-kno-format" version: "0.2.0" section: "3.2" amendment: type: patch description: "Add formal ABNF grammar to Section 3.2 for Named XRI syntax" diff: | --- a/content.kno § 3.2 +++ b/content.kno § 3.2 @@ -1,3 +1,10 @@ ### 3.2 Named XRI Syntax -Named XRIs use the pattern `pspace://type:slug`. +Named XRIs follow this grammar (ABNF): +``` +named-xri = "pspace://" type-name ":" slug +type-name = 1*ALPHA +slug = 1*( ALPHA / DIGIT / "-" ) +``` author: xri: "pspace://user/01HXYZ123ABC456DEF789" name: "Jane Contributor" created: "2026-03-15T10:00:00Z" updated: "2026-03-15T10:00:00Z" relationships: amends: - xri: "pspace://rfc:rfc-001-kno-format" reason: "Proposes clarification to Section 3.2" provenance: origin: id: 01KXYZ123ABC456DEF789GHI timestamp: "2026-03-15T10:00:00Z" tool: pspace-api