# Definition Schema — Layer 3 Specialized Document Type
# Version: 0.3.0
# Status: Draft
# Last Updated: 2026-04-28
# CHANGELOG:
#   0.3.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18.
#                            Definitions are public reference knowledge consumed via
#                            the four-surface contract.
#
# Layer 3 schema that extends document-schema.kno for term definitions.
# A definition is a single term/concept for glossaries and reference docs.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
# ENABLES: Definition instances (content/definitions/*.kno)
# AGGREGATED BY: glossary-schema.kno

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

# =============================================================================
# IDENTITY (composed from identity-schema.kno)
# =============================================================================
id: 01KGK3V73H63R9TZFVXT2FQMBP
slug: definition-schema
type: schema
version: 0.2.0

# =============================================================================
# VISIBILITY DECLARATION (REQ-18) — collection default
# =============================================================================
# Definition entities (content/definitions/*.kno) 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
# =============================================================================
title: "Definition Schema"
purpose: |
  Define the schema for term definitions — individual glossary entries.

  **What is a Definition?** A definition is a single term or concept with
  structured metadata. Definitions are atomic, referenceable, and aggregatable.

  **Architecture**:
  - Definition = Single term entity (this schema defines it)
  - Glossary = Collection of definitions (aggregates via _contains or refs)
  - Converter = Transforms markdown → definitions (glossary-md-converter.kno)

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

# =============================================================================
# RICH TIER — Taxonomy
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73H63R9TZFVXT2FQMBP
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - glossary
    - terminology
    - reference
    - documentation
    - vocabulary
  keywords:
    - definition
    - term
    - glossary
    - vocabulary
    - concept

# =============================================================================
# RICH TIER — Relationships (Edge Maximization)
# =============================================================================
relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type for all documents"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Defines kno@0.0.9 schema structure"

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

  enables:
    # Definition instances
    - xri: "kno://content/definitions/*"
      reason: "All definition entities in content/definitions/"

  part_of:
    - xri: "kno://specs/glossary-schema"
      reason: "Definitions are aggregated by glossaries"

  related_to:
    - xri: "kno://specs/spec-schema"
      reason: "Sibling Layer 3 type"
    - xri: "kno://specs/glossary-schema"
      reason: "Container for definitions"

# =============================================================================
# RICH TIER — Quality
# =============================================================================
quality:
  completeness: 0.8
  last_reviewed: "2026-01-09"
  review_status: draft
  reviewed_by: "claude"

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

  versions:
    - version: "0.2.0"
      date: "2026-02-02"
      author: "claude"
      summary: "Extended for playbook component classification (Issue #51)"
      changes:
        - "Added pattern_type field for semantic classification"
        - "Enum values: principle, anti-pattern, rule, term"
        - "Backwards-compatible: field is optional"
    - version: "0.1.0"
      date: "2026-01-09"
      author: "claude"
      summary: "Promoted from holding-pen with conformance fixes"
      changes:
        - "Promoted from specs/holding-pen/glossary-term.kno.yaml"  # kno-yaml-allowed: provenance entry preserves historical filename at promotion time
        - "Updated $schema to kno@0.0.9"
        - "Added _history block for P9 compliance"
        - "Updated relationships to use XRI format"
        - "Renamed from glossary-term to definition-schema"
        - "Removed deprecated RFC references"

    - version: "0.0.1"
      date: "2025-12-04"
      author: "pspace-core-team"
      summary: "Initial draft in holding-pen"
      changes:
        - "Initial definition entity spec"
        - "Supports structured term definitions"

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

  description: |
    A **Definition** entity represents a single term or concept with structured
    metadata for display in glossaries and cross-referencing.

    ## Design Principles

    1. **Atomic**: One definition per file, referenceable by ID
    2. **Structured**: Consistent fields for term, definition, usage, references
    3. **Aggregatable**: Can be collected into glossaries via _contains or refs
    4. **Derivable**: Can be auto-generated from markdown glossaries
    5. **Historical**: Each definition tracks its own change history (P9)

    ## Use Cases

    - Glossary terms for project documentation
    - API/SDK terminology definitions
    - Domain-specific vocabulary
    - Standards and specification terms

    ## Authoring Flow

    ```
    content/definitions/*.kno   (canonical per-term entities, authored directly)
           │
           ▼ (aggregation via refs)
    content/glossary.kno        (glossary container)
    ```

    > Historical note: terms used to be authored in `docs/reference/glossary.md`
    > and converted via `scripts/archived/convert-glossary-to-definitions.ts`.
    > That source-of-truth was inverted in #2166; the markdown file is now a stub.

  # ===========================================================================
  # SCHEMA DEFINITION
  # ===========================================================================
  schema:
    type: object
    required:
      - $schema
      - id
      - type
      - version
      - term
      - definition

    properties:
      # -----------------------------------------------------------------------
      # KNO HEADER (from kno-spec)
      # -----------------------------------------------------------------------
      $schema:
        type: string
        description: "Schema reference, always kno@0.0.9 or higher"
        pattern: "^kno@\\d+\\.\\d+\\.\\d+$"
        examples: ["kno@0.0.9"]

      # -----------------------------------------------------------------------
      # IDENTITY (from identity-schema.kno)
      # -----------------------------------------------------------------------
      id:
        type: string
        description: "Unique identifier (usually 'def-' + slugified term)"
        pattern: "^[a-z][a-z0-9-]*$"
        examples: ["def-possibility", "def-kno", "def-kaml"]

      type:
        type: string
        const: definition
        description: "Entity type, always 'definition'"

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

      # -----------------------------------------------------------------------
      # STANDARD TIER (from document-schema.kno)
      # -----------------------------------------------------------------------
      title:
        type: string
        description: "Optional title (usually same as term)"

      purpose:
        type: string
        description: "Optional description of why this definition exists"

      # REMOVED: facets (DC-2: domain/category are inferred, not declared)

      # -----------------------------------------------------------------------
      # DEFINITION-SPECIFIC FIELDS
      # -----------------------------------------------------------------------
      term:
        type: string
        description: "The term being defined (display form)"
        examples: ["Possibility", "KNO", "KAML", "X-Ray Mode"]

      part_of_speech:
        type: string
        enum:
          - noun
          - verb
          - adjective
          - adverb
          - abbreviation
          - acronym
          - phrase
        description: "Grammatical category of the term"

      pronunciation:
        type: string
        description: "Phonetic pronunciation guide"
        examples: ["know", "camel", "pico"]

      definition:
        type: string
        description: "The primary definition (markdown supported)"
        examples: ["The fundamental unit of the Possibility ecosystem."]

      etymology:
        type: string
        description: "Origin or derivation of the term"

      usage:
        type: string
        description: "Example sentence showing the term in context"

      variants:
        type: array
        items:
          type: object
          properties:
            form:
              type: string
            description:
              type: string
        description: "Alternative forms of the term"

      attributes:
        type: array
        items:
          type: string
        description: "Key characteristics of the defined concept"

      # -----------------------------------------------------------------------
      # REFERENCES
      # -----------------------------------------------------------------------
      spec:
        type: string
        description: "Path or XRI to spec defining this concept"
        examples: ["specs/possibility.kno", "kno://specs/possibility"]

      see_also:
        type: array
        items:
          type: string
        description: "Related term IDs for cross-referencing"

      external_links:
        type: array
        items:
          type: object
          properties:
            label:
              type: string
            url:
              type: string
              format: uri
        description: "External references (W3C, Wikipedia, etc.)"

      # -----------------------------------------------------------------------
      # CATEGORIZATION
      # -----------------------------------------------------------------------
      category:
        type: string
        description: "Glossary category this definition belongs to"
        examples: ["core-concepts", "technical-terms"]

      pattern_type:
        type: string
        enum:
          - principle
          - anti-pattern
          - rule
          - term
        description: |
          Semantic classification for playbook-derived definitions.
          - principle: Foundational belief or value guiding behavior
          - anti-pattern: Common mistake or practice to avoid
          - rule: Explicit constraint or requirement
          - term: Standard glossary term (default)
        examples: ["principle", "anti-pattern"]

      # REMOVED: tags (DC-2: use taxonomy.keywords for discovery)

      # -----------------------------------------------------------------------
      # DEPRECATION
      # -----------------------------------------------------------------------
      deprecated:
        type: boolean
        default: false
        description: "Whether this term is deprecated"

      superseded_by:
        type: string
        description: "ID of term that supersedes this one"

      # -----------------------------------------------------------------------
      # HISTORY (from history-schema.kno)
      # -----------------------------------------------------------------------
      _history:
        type: object
        description: "Version history for P9 compliance"

      # -----------------------------------------------------------------------
      # QUALITY (from quality-schema.kno)
      # -----------------------------------------------------------------------
      quality:
        type: object
        description: "Quality metadata"

# =============================================================================
# EXAMPLES
# =============================================================================
examples:
  - title: "Minimal Definition"
    description: "Smallest valid definition"
    code: |
      $schema: kno@0.0.9
      id: def-example
      type: definition
      version: 0.1.0
      term: "Example"
      definition: "A sample used to illustrate a concept."

  - title: "Full Definition with History"
    description: "Complete definition with all optional fields"
    code: |
      $schema: kno@0.0.9
      id: def-kaml
      type: definition
      version: 0.2.0

      term: "KAML"
      part_of_speech: abbreviation
      pronunciation: "camel"
      definition: |
        Knowledge-Adapted Markup Language. The markup language that
        .kno files use, built on YAML with microsyntax for semantic
        addressing and hierarchical containment.

      etymology: "Knowledge-Adapted Markup Language"
      usage: "KAML is to .kno as Markdown is to .md"

      variants:
        - form: "KAML"
          description: "Standard written form"
        - form: "camel"
          description: "Phonetic pronunciation"

      attributes:
        - "Built on YAML 1.2 serialization"
        - "Adds XRI addressing, _contains, _index"
        - "Agent-optimized retrieval"

      spec: "kno://specs/kaml-spec"
      see_also: ["def-kno", "def-yaml"]
      category: "core-concepts"

      _history:
        retention: full
        versions:
          - version: "0.2.0"
            date: "2026-01-09"
            author: "claude"
            summary: "Updated for KAML spec release"
          - version: "0.1.0"
            date: "2026-01-06"
            summary: "Initial definition"

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

  1. **ID Prefix**: Use `def-` prefix for definition IDs to distinguish from
     other entity types (e.g., `def-kaml` vs `kaml-spec`).

  2. **Category vs Tags**: `category` is singular (one primary category per
     definition); `tags` are multiple (for filtering/search).

  3. **Deprecation**: Use `deprecated: true` + `superseded_by: def-new-term`
     to mark outdated definitions while preserving history.

  4. **History Retention**: Definitions should use `retention: full` because
     terminology changes are important to track over time.

  ## Migration from Markdown

  Definitions can be auto-generated from markdown glossaries using
  `glossary-md-converter.kno`. The converter parses:
  - `### Term` → term field
  - Definition paragraph → definition field
  - `**Usage:**` block → usage field
  - `**See Also:**` → see_also array
  - `**Spec:**` → spec field

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 18
    keywords: [id, type, version, definition-schema]
  - path: "spec/fields"
    line: 100
    keywords: [term, definition, category, tags, see_also]
  - path: "spec/examples"
    line: 300
    keywords: [minimal, full, deprecated, superseded]
  - path: "notes"
    line: 410
    keywords: [id-prefix, category-vs-tags, deprecation, migration]

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [id, type, version]
  - xri: "#spec"
    role: section
    title: "Definition Schema"
    keywords: [fields, examples, validation]
  - xri: "#notes"
    role: section
    title: "Design Notes"
    keywords: [decisions, migration]