# Glossary Schema — Layer 3 Specialized Document Type
# KNO Schema Version: 0.7.0
# CHANGELOG:
#   0.7.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18.
#                            The glossary is public reference knowledge consumed via
#                            the four-surface contract.
#
# Layer 3 schema that extends document-schema.kno for glossaries.
# A glossary is a collection of term definitions.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
# ENABLES: Glossary instances (content/glossary.kno)

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# IDENTITY (composed from identity-schema.kno)
# =============================================================================
id: 01KGK3V73F25JTJ3G4XDMA7EKP
slug: glossary-schema
type: schema
version: 0.7.0

# =============================================================================
# VISIBILITY DECLARATION (REQ-18) — collection default
# =============================================================================
# Glossary entities (content/glossary.kno and any future per-term files) are
# public reference knowledge by default. Per REQ-18, individual entities MAY
# override with their own `visibility:` field (last-write-wins at the entity
# level). Drives the four-surface contract per kno-system_architecture.md
# § Agent Surface Integration and public-surface-parity.instructions.md.
visibility: public

# =============================================================================
# STANDARD TIER (inherited from document-schema.kno)
# =============================================================================
title: "Glossary Schema"
purpose: |
  Define the schema for glossary documents — collections of term definitions.

  **What is a Glossary?** A glossary aggregates definitions of terms used
  within a domain. Each term has a name, definition, and optional metadata
  like category, related terms, and examples.

  **Architecture**:
  - Glossary = Collection container (this schema defines it)
  - Terms = Individual entries within the glossary
  - Definition entities = Standalone term files (optional, for complex terms)

  **Layer 3 Position**: Glossary extends document (Layer 2), which composes
  identity, history, and quality (Layer 1).

# =============================================================================
# RICH TIER — Relationships (Edge Maximization)
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73F25JTJ3G4XDMA7EKP
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - terminology
    - definitions
    - reference
    - vocabulary
  keywords:
    - glossary
    - terms
    - definitions
    - vocabulary
    - terminology

relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "RFC-001 defines kno@0.0.9 schema"

  composes:
    # Inherited through document-schema.kno:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: id, canonical_id, local_ids, equiv_ids"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation, confidence"

  enables:
    - xri: "kno://content/glossary/*"
      reason: "Glossary instances"

  related_to:
    - xri: "kno://specs/spec-schema"
      reason: "Sibling Layer 3 type"
    - xri: "kno://specs/rfc-schema"
      reason: "Sibling Layer 3 type"
    - xri: "kno://specs/guide-schema"
      reason: "Sibling Layer 3 type"
    - xri: "kno://specs/definition-schema"
      reason: "Term definitions (can be standalone entities)"

  implements:
    - xri: "kno://principles/P9"
      reason: "Temporal/Historical — glossaries in Hive are versioned"
    - xri: "kno://principles/VCS-Mandatory-Rule"
      reason: "Generated glossaries promoted to Hive MUST be recorded in VCS"

quality:
  completeness: 0.85
  last_reviewed: "2026-01-09"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY (P9 Temporal)
# =============================================================================
_history:
  retention: full
  format: snapshot

  versions:
    - version: "0.6.0"
      date: "2026-02-21"
      author: "claude"
      summary: "Added VCS-Mandatory Rule cross-reference"
      changes:
        - "Added implements relationship for P9 and VCS-Mandatory-Rule"
        - "Generated glossaries promoted to Hive must be VCS-recorded"

    - version: "0.5.2"
      date: "2026-01-09"
      author: "claude"
      summary: "Added refs field for P9-compliant aggregation"
      changes:
        - "Added 'refs' field for XRI references to external definitions"
        - "Updated $schema to kno@0.0.9"
        - "Renamed id from 'glossary' to 'glossary-schema'"
        - "Documented hybrid pattern: inline terms + external refs"

    - version: "0.5.0"
      date: "2026-01-06"
      author: "claude"
      summary: "Initial Layer 3 glossary schema"
      changes:
        - "Created as Layer 3 schema extending document-schema.kno"
        - "Defined terms array structure"
        - "Added categories for term organization"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  description: |
    ## What is a Glossary?

    A **glossary** is a document that defines terms used within a domain.
    It serves as the authoritative reference for terminology.

    ## Structure

    A glossary contains:
    - **terms**: Array of term definitions
    - **categories**: Optional groupings for terms
    - **content_ref**: Optional reference to markdown source

    ## Term Definition

    Each term has:
    - `term`: The word or phrase being defined (required)
    - `definition`: Explanation of the term (required)
    - `category`: Grouping for organization
    - `aliases`: Alternative names for the term
    - `related`: Links to related terms
    - `examples`: Usage examples

    ## Layer 3 Inheritance

    ```
    glossary-schema.kno
    └── extends: document-schema.kno
        └── composes: identity-schema.kno, history-schema.kno, quality-schema.kno
    ```

  # ===========================================================================
  # SCHEMA DEFINITION
  # ===========================================================================
  schema:
    # -------------------------------------------------------------------------
    # Required Fields
    # -------------------------------------------------------------------------
    required:
      - id # From identity-schema.kno
      - title # From document-schema.kno
      - terms # Glossary-specific: term definitions

    # -------------------------------------------------------------------------
    # Field Definitions
    # -------------------------------------------------------------------------
    properties:
      # --- INHERITED FROM IDENTITY.KNO (Layer 1) ---
      id:
        type: string
        description: "Unique identifier for the glossary"
        pattern: "^[a-z][a-z0-9-]*$"
        examples:
          - "pspace-glossary"
          - "kno-terms"

      # --- INHERITED FROM DOCUMENT.KNO (Layer 2) ---
      type:
        type: string
        const: glossary
        description: "Entity type, always 'glossary'"

      version:
        type: string
        description: "Semantic version"
        pattern: "^\\d+\\.\\d+\\.\\d+$"

      title:
        type: string
        description: "Human-readable title"
        examples:
          - "Possibility Glossary"
          - "KNO Terminology"

      purpose:
        type: string
        description: "Description of what this glossary covers"

      # REMOVED: audience field (DC-1: all .kno files serve all audiences)
      # REMOVED: facets (DC-2: domain/category are inferred, not declared)

      # --- GLOSSARY-SPECIFIC FIELDS ---
      terms:
        type: array
        description: "Array of term definitions"
        items:
          type: object
          required:
            - term
            - definition
          properties:
            term:
              type: string
              description: "The word or phrase being defined"
            definition:
              type: string
              description: "Explanation of the term"
            category:
              type: string
              description: "Category for grouping"
            aliases:
              type: array
              items:
                type: string
              description: "Alternative names for this term"
            related:
              type: array
              items:
                type: string
              description: "Related term names"
            examples:
              type: array
              items:
                type: string
              description: "Usage examples"
            see_also:
              type: array
              items:
                type: string
                format: uri
              description: "External references"

      categories:
        type: array
        description: "Category definitions for organizing terms"
        items:
          type: object
          required:
            - id
            - title
          properties:
            id:
              type: string
              description: "Category identifier"
            title:
              type: string
              description: "Display name"
            description:
              type: string
              description: "Category description"

      definitions_dir:
        type: string
        description: "Directory containing definition entity files"
        examples:
          - "definitions/"

      # --- AGGREGATION (P9-Compliant Pattern) ---
      # Use 'refs' to aggregate external definition entities.
      # Each definition file has its own _history for P9 compliance.
      refs:
        type: array
        description: "XRIs to external definition entities (P9 pattern)"
        items:
          type: string
          format: uri
          pattern: "^kno://"
        examples:
          - ["kno://content/definitions/kaml", "kno://content/definitions/kno"]
          - ["kno://content/definitions/*"]

      # --- HYBRID: Inline + External ---
      # 'terms' for simple inline definitions (no individual history)
      # 'refs' for external definitions (each has _history)
      # Both can coexist: inline for simple, external for complex terms.

      content_ref:
        type: string
        description: "Optional reference to historical markdown source (deprecated since #2166)"
        examples:
          - "../docs/reference/glossary.md"

      # --- METADATA ---
      metadata:
        type: object
        description: "Glossary statistics"
        properties:
          last_updated:
            type: string
            format: date
          term_count:
            type: integer
          word_count:
            type: integer

      # --- INHERITED FROM HISTORY.KNO (Layer 1) ---
      _history:
        type: object
        description: "Version history"

      # --- INHERITED FROM QUALITY.KNO (Layer 1) ---
      quality:
        type: object

      # --- RELATIONSHIPS ---
      relationships:
        type: object

      taxonomy:
        type: object

  # ===========================================================================
  # EXAMPLES
  # ===========================================================================
  examples:
    - title: "Minimal Glossary"
      description: "Smallest valid glossary"
      code: |
        $schema: kno@0.0.9

        id: minimal-glossary
        type: glossary
        version: 0.1.0
        title: "Minimal Glossary"

        terms:
          - term: "KNO"
            definition: "Knowledge Notation Object"
          - term: "XRI"
            definition: "Cross-Reference Identifier"

    - title: "Glossary with Refs (P9 Pattern)"
      description: "Aggregating external definition files for P9 compliance"
      code: |
        $schema: kno@0.0.9

        id: pspace-glossary
        type: glossary
        version: 0.4.0
        title: "Possibility Glossary"

        # External definitions (each has own _history for P9)
        refs:
          - "kno://content/definitions/possibility"
          - "kno://content/definitions/kno"
          - "kno://content/definitions/kaml"
          - "kno://content/definitions/xray"

        categories:
          - id: core
            title: "Core Concepts"
          - id: technical
            title: "Technical Terms"

    - title: "Hybrid Glossary"
      description: "Both inline terms and external refs"
      code: |
        $schema: kno@0.0.9

        id: hybrid-glossary
        type: glossary
        version: 0.1.0
        title: "Hybrid Glossary"

        # Complex terms as external files (with history)
        refs:
          - "kno://content/definitions/possibility"
          - "kno://content/definitions/organization"

        # Simple terms inline (no individual history)
        terms:
          - term: "API"
            definition: "Application Programming Interface"
          - term: "UUID"
            definition: "Universally Unique Identifier"

  # ===========================================================================
  # NOTES
  # ===========================================================================
  notes: |
    ## Design Decisions

    1. **Inline vs External Terms**: Terms can be defined inline in the
       `terms` array or as separate definition entity files. Inline is
       simpler; external allows richer metadata per term.

    2. **Categories**: Optional but recommended for glossaries with
       many terms. Categories enable grouped display and filtering.

    3. **Migration Support**: The `content_ref` field supports gradual
       migration from markdown glossaries to structured .kno format.

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [id, type, version]
  - xri: "#spec"
    role: section
    title: "Glossary Schema"
    keywords: [fields, aggregation, categories]
  - xri: "#notes"
    role: section
    title: "Design Notes"
    keywords: [categories, migration]

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 18
    keywords: [id, type, version, glossary-schema]
  - path: "spec/fields"
    line: 100
    keywords: [title, scope, definitions, content_ref, categories]
  - path: "spec/aggregation"
    line: 200
    keywords: [aggregates, definition-schema, _contains]
  - path: "spec/examples"
    line: 300
    keywords: [minimal, full, categorized]
  - path: "notes"
    line: 380
    keywords: [inline-vs-reference, categories, migration]