# Quality Schema — Layer 1 Primitive # KNO Schema Version: 0.5.1 # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (Layer 1 self-reference) # ============================================================================= id: 01KGK3V73JPJWTYJA47KV0WV9F slug: quality-schema type: spec version: 0.0.1 # ============================================================================= # STANDARD TIER # ============================================================================= title: "Quality Schema" purpose: "Define the composable building block for entity quality metadata" # ============================================================================= # RICH TIER — Relationships (Edge Maximization) # ============================================================================= provenance: origin: id: 01KGK3V73JPJWTYJA47KV0WV9F timestamp: "2026-02-04T01:47:56Z" tool: manual-migration taxonomy: topics: - quality - validation - review - completeness - schema-composition keywords: - quality - completeness - review - validation - assertion - confidence relationships: depends_on: - xri: "kno://specs/kno-spec" reason: "Defines the kno@0.0.9 schema this conforms to" related_to: - xri: "kno://specs/identity-schema" reason: "Sibling Layer 1 primitive" - xri: "kno://specs/history-schema" reason: "Sibling Layer 1 primitive" - xri: "kno://concepts/provenance" reason: "Attestation is related to quality" enables: - xri: "kno://specs/document-schema" reason: "Base type that composes this" - xri: "kno://specs/spec-schema" reason: "Domain schema with quality tracking" - xri: "kno://specs/rfc-schema" reason: "Domain schema with review process" implements: - xri: "kno://principles/P5" reason: "Schema-Driven Quality principle" - xri: "kno://requirements/REQ-17" reason: "Validation & Assertion requirement" quality: completeness: 0.9 last_reviewed: "2026-01-06" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: version: 1 created: "2026-01-06T12:00:00Z" created_by: "claude" modified: "2026-01-06T12:00:00Z" modified_by: "claude" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft description: | Quality is a **Layer 1 primitive** — a composable building block that provides quality metadata fields for any .kno entity. **P5 (Schema-Driven Quality):** Schemas define what "best" means. Quality is objective, not subjective. Schemas are the contracts. This schema defines: - **quality**: Quality metadata block (completeness, review status) - **validation**: Assertion records (who validated, when, result) - **confidence**: Machine-generated confidence scores ## Quality vs Provenance | Concern | Answers | Schema | |----------------|------------------------------------------|-------------| | **Quality** | How complete/reviewed is this entity? | quality-schema.kno | | **Provenance** | Who vouches for this entity's validity? | provenance.kno | Quality tracks COMPLETENESS and REVIEW STATE. Provenance tracks ATTESTATION and OWNERSHIP. ## Composition Pattern Schemas that include quality declare: ```yaml composes: - quality@0.1 ``` This brings in quality block and validation assertions. changelog: - version: "0.1.0" changes: - "Initial Layer 1 quality schema" - "Extracted from kno-spec-schema.kno quality block" - "Added validation assertion records" - "Added confidence scores for machine-generated content" schema: # ------------------------------------------------------------------------- # QUALITY METADATA BLOCK # ------------------------------------------------------------------------- quality_block: description: | The quality block provides quality metadata for any .kno entity. Tracks completeness, review status, and who reviewed. fields: quality: type: object required: false description: "Quality metadata block" fields: completeness: type: number minimum: 0.0 maximum: 1.0 description: | Self-assessed or computed completeness score. 0.0 = stub/placeholder 0.5 = partial, missing key sections 0.8 = mostly complete, minor gaps 1.0 = fully complete examples: [0.5, 0.8, 0.95, 1.0] review_status: type: enum values: - draft # Initial creation, not reviewed - review # Under review - approved # Reviewed and approved - rejected # Reviewed and rejected - deprecated # No longer current - archived # Historical only description: "Current review state" default: draft last_reviewed: type: string format: date description: "Date of last review (ISO 8601 date)" examples: ["2026-01-06"] reviewed_by: type: string description: | Who performed the review. Can be user id, team, or automated system. examples: ["claude", "max", "pspace-core-team", "automated-lint"] next_review: type: string format: date description: "When next review is due" examples: ["2026-06-01"] review_notes: type: string description: "Notes from the reviewer" examples: ["Approved with minor suggestions for clarity"] # ------------------------------------------------------------------------- # VALIDATION ASSERTIONS (REQ-17) # ------------------------------------------------------------------------- validation: description: | Validation is the PROCESS of checking conformance. Assertion is the RECORD that validation occurred. This enables trust without re-validation — if a trusted validator has asserted, downstream consumers can rely on it. fields: validation: type: object required: false description: "Validation assertion records" fields: assertions: type: array description: "List of validation assertions" items: type: object fields: validator: type: string description: | Who/what performed validation. Can be: agent identifier, service name, user id examples: ["kno-validator@0.1", "claude", "ci-pipeline"] timestamp: type: string format: date-time description: "When validation occurred" examples: ["2026-01-06T12:00:00Z"] schema_version: type: string description: "Which schema version was validated against" examples: ["kno@0.0.9", "user@0.3"] result: type: enum values: - pass # All checks passed - fail # One or more checks failed - partial # Some checks passed, some skipped - skipped # Validation skipped (e.g., offline) description: "Validation result" violations: type: array description: "List of violations if result is fail/partial" items: type: object fields: rule: type: string description: "Rule that was violated" examples: ["id_required", "canonical_id_format"] severity: type: enum values: [error, warning, info] description: "Severity of violation" message: type: string description: "Human-readable violation message" path: type: string description: "JSON path to violating field" examples: ["$.id", "$.relationships.depends_on[0]"] signature: type: string description: | Cryptographic signature of the assertion. Used for federated trust — allows verification without re-running validation. examples: ["ed25519:abc123..."] last_validated: type: string format: date-time description: "When last successful validation occurred" schema_version: type: string description: "Schema version of last validation" # ------------------------------------------------------------------------- # CONFIDENCE SCORES (machine-generated content) # ------------------------------------------------------------------------- confidence: description: | Confidence scores for machine-generated or inferred content. When agents/LLMs generate or modify content, confidence indicates how certain the generation was. fields: confidence: type: object required: false description: "Machine-generated confidence metadata" fields: overall: type: number minimum: 0.0 maximum: 1.0 description: | Overall confidence in this entity. Combined score from field-level confidences. examples: [0.85, 0.92] fields: type: object additionalProperties: type: number minimum: 0.0 maximum: 1.0 description: | Per-field confidence scores. Key is JSON path, value is confidence. examples: "$.title": 0.95 "$.purpose": 0.88 "$.relationships.depends_on": 0.75 generated_by: type: string description: "Model/agent that generated this content" examples: ["claude-3-opus", "pspace-inference@0.1"] generated_at: type: string format: date-time description: "When content was generated" human_verified: type: boolean default: false description: "Whether a human has verified the generated content" verified_by: type: string description: "Who verified the generated content" examples: ["max", "pspace-reviewer"] verified_at: type: string format: date-time description: "When verification occurred" # =========================================================================== # COMPOSITION PATTERN # =========================================================================== composition: description: | Quality is a COMPOSABLE schema. Other schemas include quality fields by declaring composition. When a schema composes quality: - quality block becomes available - validation assertions become available - confidence scores become available (for AI-generated content) example: | # In document-schema.kno: composes: - identity@0.1 - history@0.1 - quality@0.1 # Brings in quality, validation, confidence # =========================================================================== # VALIDATION RULES # =========================================================================== validation: rules: - name: "completeness_range" severity: error message: "completeness must be between 0.0 and 1.0" check: "quality.completeness >= 0.0 && quality.completeness <= 1.0" when: "exists(quality.completeness)" - name: "reviewed_has_reviewer" severity: warning message: "Reviewed files should have reviewed_by" check: "exists(quality.reviewed_by)" when: "quality.review_status in ['approved', 'rejected']" - name: "validation_has_timestamp" severity: error message: "Validation assertions must have timestamps" check: "all(validation.assertions, exists(timestamp))" when: "exists(validation.assertions)" - name: "confidence_has_generator" severity: warning message: "Confidence scores should indicate what generated them" check: "exists(confidence.generated_by)" when: "exists(confidence.overall)" - name: "human_verified_has_verifier" severity: warning message: "Human-verified content should have verifier" check: "exists(confidence.verified_by)" when: "confidence.human_verified == true" # ============================================================================= # SOURCE (P4 — for this schema itself) # ============================================================================= source: | # This schema was extracted from the quality block in kno-spec-schema.kno # and expanded into a full Layer 1 composable primitive. # # Original location: kno-spec-schema.kno > spec.schema.rich.fields.quality # # Design decisions: # 1. Validation assertions per REQ-17 (trust without re-validation) # 2. Confidence scores for AI-generated content transparency # 3. Separation from provenance (attestation vs completeness) source_format: yaml source_hash: "sha256:tbd" # ============================================================================= # CONTAINER TIER — Navigation Index # ============================================================================= _index: - path: "identity" line: 14 keywords: [id, type, version, quality] - path: "spec/fields" line: 100 keywords: [completeness, last_reviewed, review_status, reviewed_by] - path: "spec/confidence" line: 180 keywords: [confidence, ai_generated, model, human_verified] - path: "spec/assertions" line: 250 keywords: [assertions, validates, validator, REQ-17] - path: "validation" line: 350 keywords: [rules, completeness_range, review_status_enum] contains: - xri: "#identity" role: section title: "Identity Metadata" keywords: [id, type, version] - xri: "#spec" role: section title: "Specification Content" keywords: [fields, confidence, assertions] - xri: "#source" role: section title: "Source Provenance" keywords: [source, origin, extraction]