# Spec Schema — Layer 3 Specialized Document Type
# KNO Schema Version: 0.5.1
#
# Layer 3 schema that extends document-schema.kno for specifications.
# A schema is a schema — this one defines the structure for other schemas.
#
# PURPOSE: Define the structure for all .kno schema files.
# Every file with `type: spec` should conform to this schema.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
# ENABLES: All domain schemas (user.kno, brand.kno, etc.)

# =============================================================================
# SCHEMA DECLARATION (RFC-007)
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# IDENTITY (composed from identity-schema.kno)
# =============================================================================
id: 01KGK3V73HZTT0NAZVK7FY67N4
slug: spec-schema
type: spec
version: 0.0.2

# =============================================================================
# STANDARD TIER (inherited from document-schema.kno)
# =============================================================================
title: "Spec Schema"
purpose: |
  Define the schema for specification documents.

  **What is a spec?** A spec is a document that defines the structure,
  fields, and validation rules for a category of .kno entities.
  A spec is just another .kno file — schemas describing schemas emerge
  from relationships, not from a special "meta" designation.

  **Layer 3 Position**: Spec extends document (Layer 2), which composes
  identity, history, and quality (Layer 1). This means every spec
  automatically gets:
  - Identity fields (id, canonical_id, local_ids)
  - History tracking (_history, changelog)
  - Quality metadata (completeness, review_status)
  - Document fields (title, purpose, audience)

  **What specs enable**: All domain schemas (Layer 4) are instances
  of spec-schema.kno. When you write `type: spec` in user.kno, you're
  declaring conformance to this schema.

# =============================================================================
# RICH TIER — Relationships (Edge Maximization)
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73HZTT0NAZVK7FY67N4
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - specifications
    - schemas
    - entity-definitions
    - validation
  keywords:
    - spec
    - schema
    - definition
    - validation
    - fields
    - properties
    - required

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:
    # Layer 4 domain schemas (all have type: spec)
    - xri: "kno://specs/user-schema"
      reason: "User domain schema"
    - xri: "kno://specs/organization-schema"
      reason: "Organization domain schema"
    - xri: "kno://specs/brand-schema"
      reason: "Brand domain schema"
    - xri: "kno://specs/connector-schema"
      reason: "Connector domain schema"
    - xri: "kno://specs/workflow-schema"
      reason: "Workflow domain schema"
    - xri: "kno://specs/activity-schema"
      reason: "Activity domain schema"
    - xri: "kno://specs/corpus-schema"
      reason: "Corpus domain schema"
    - xri: "kno://specs/playbook-schema"
      reason: "Playbook domain schema"

  related_to:
    - xri: "kno://specs/rfc-schema"
      reason: "Sibling Layer 3 type (normative documents)"
    - xri: "kno://specs/glossary-schema"
      reason: "Sibling Layer 3 type (terminology)"
    - xri: "kno://specs/guide-schema"
      reason: "Sibling Layer 3 type (how-to)"
    - xri: "kno://tools/validator"
      reason: "Uses specs for validation"

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

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

  versions:
    - version: "0.0.1"
      date: "2026-01-06"
      author: "claude"
      summary: "Version alignment to 0.0.x; remove meta-schema terminology"
      changes:
        - "Reset version to 0.0.1 (early stage 3-point versioning)"
        - "Removed 'meta-schema' terminology — a schema is a schema"
        - "Updated $schema URL to https://schemas.possibility.space/kno@0.0.9"
        - "Updated purpose to reflect P6 (emergent structure)"
    - version: "0.5.0"
      date: "2026-01-06"
      author: "claude"
      summary: "Layer 3 refactor; extends document-schema.kno"
      changes:
        - "Refactored as Layer 3 schema extending document-schema.kno"
        - "Added composes/extends/enables relationships"
        - "Reorganized spec.schema for clarity"
        - "Added _history block"
    - version: "0.1.0"
      date: "2025-12-05"
      author: "pspace-core-team"
      summary: "Initial spec schema"

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

  description: |
    ## What is a Spec?

    A **spec** is a document that defines the structure, validation rules,
    and semantic meaning of a category of .kno entities.

    ## Spec vs Instance

    | Aspect | Spec | Instance |
    |--------|------|----------|
    | `type` | `spec` | Entity type (e.g., `user`) |
    | Purpose | Define structure | Contain data |
    | `spec.schema` | Present (defines fields) | Absent |
    | Example | `user.kno` | `alice.kno` |

    ## Layer 3 Inheritance

    Spec extends document, which composes Layer 1 primitives:

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

    This means every spec automatically has:
    - `id`, `canonical_id`, `local_ids`, `equiv_ids` (from identity)
    - `_history`, `changelog` (from history)
    - `quality`, `completeness`, `review_status` (from quality)
    - `title`, `purpose` (from document)

    ## Spec-Specific Fields

    Beyond inherited fields, specs add:
    - `spec.status` — Lifecycle state (Draft, Active, Deprecated, Superseded)
    - `spec.schema` — Field definitions and validation rules
    - `spec.examples` — Usage examples
    - `spec.notes` — Design decisions and rationale

  # ===========================================================================
  # SCHEMA DEFINITION
  # ===========================================================================
  schema:
    # -------------------------------------------------------------------------
    # Required Fields
    # -------------------------------------------------------------------------
    required:
      - id # From identity-schema.kno
      - type # Must be "spec"
      - version # Semantic version
      - title # From document-schema.kno
      - spec # Spec-specific content

    # -------------------------------------------------------------------------
    # Field Definitions
    # -------------------------------------------------------------------------
    properties:
      # --- INHERITED FROM IDENTITY.KNO (Layer 1) ---
      id:
        type: string
        description: "Unique identifier for the spec (e.g., 'user', 'brand')"
        pattern: "^[a-z][a-z0-9-]*$"
        examples:
          - "user"
          - "organization"
          - "kno-spec"

      canonical_id:
        type: string
        description: "Immutable machine-generated ID (ULID)"
        pattern: "^[0-9A-HJKMNP-TV-Z]{26}$"

      local_ids:
        type: object
        description: "System-specific identifiers"
        additionalProperties:
          type: string

      equiv_ids:
        type: array
        items:
          type: string
          format: uri
        description: "Equivalent identities in external systems"

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

      version:
        type: string
        description: "Semantic version of this spec"
        pattern: "^\\d+\\.\\d+\\.\\d+$"
        examples:
          - "0.1.0"
          - "1.0.0"

      title:
        type: string
        description: "Human-readable title"
        examples:
          - "User Entity Specification"
          - "Brand Schema"

      purpose:
        type: string
        description: "Extended description of what this spec defines"

      # REMOVED: audience field (DC-1: all .kno files serve all audiences)
      # REMOVED: facets field (deprecated in kno-spec v0.0.6; domain/category derivable from $schema and XRI)

      # --- INHERITED FROM HISTORY.KNO (Layer 1) ---
      _history:
        type: object
        description: "Version history (P9 Temporal)"
        properties:
          retention:
            type: string
            enum: [full, "recent:N", none]
          format:
            type: string
            enum: [snapshot, diff, hash]
          versions:
            type: array
            items:
              type: object

      # --- INHERITED FROM QUALITY.KNO (Layer 1) ---
      quality:
        type: object
        description: "Quality metadata"
        properties:
          completeness:
            type: number
            minimum: 0
            maximum: 1
          last_reviewed:
            type: string
            format: date
          review_status:
            type: string
            enum: [draft, review, approved, deprecated]
          reviewed_by:
            type: string

      # --- SPEC-SPECIFIC FIELDS ---
      spec:
        type: object
        required:
          - status
        description: "Specification content and schema definition"
        properties:
          status:
            type: string
            enum: [Draft, Active, Deprecated, Superseded]
            description: "Current lifecycle status"

          supersedes:
            type: string
            description: "ID of spec this supersedes"

          superseded_by:
            type: string
            description: "ID of spec that supersedes this"

          description:
            type: string
            description: "Detailed specification content (markdown)"

          schema:
            type: object
            description: "Field definitions and validation rules"
            properties:
              required:
                type: array
                items:
                  type: string
                description: "List of required field names"

              properties:
                type: object
                description: "Field definitions"
                additionalProperties:
                  type: object
                  properties:
                    type:
                      type: string
                      description: "JSON Schema type"
                    description:
                      type: string
                    pattern:
                      type: string
                    enum:
                      type: array
                    examples:
                      type: array
                    format:
                      type: string

          examples:
            type: array
            description: "Usage examples"
            items:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                code:
                  type: string

          notes:
            type: string
            description: "Design decisions and rationale"

      # --- RELATIONSHIPS (from kno-spec) ---
      relationships:
        type: object
        description: "Connections to other entities"
        properties:
          extends:
            type: array
            items:
              type: string
            description: "Parent schema(s) this extends"
          depends_on:
            type: array
            items:
              type: string
          composes:
            type: array
            items:
              type: string
          enables:
            type: array
            items:
              type: string
          related_to:
            type: array
            items:
              type: string

      taxonomy:
        type: object
        description: "Classification for discoverability"

  # ===========================================================================
  # EXAMPLES
  # ===========================================================================
  examples:
    - title: "Minimal Spec"
      description: "Smallest valid spec definition"
      code: |
        $schema: kno@0.0.9

        id: minimal-example
        type: spec
        version: 0.1.0
        title: "Minimal Example Schema"

        spec:
          status: Draft
          schema:
            required:
              - id
            properties:
              id:
                type: string

    - title: "Domain Schema with Layer 1 Composition"
      description: "How a domain schema declares Layer 1 composition"
      code: |
        $schema: kno@0.0.9

        id: product
        type: spec
        version: 0.1.0
        title: "Product Schema"
        purpose: "Define the structure for product entities"

        relationships:
          composes:
            - identity   # Gets id, canonical_id, etc.
            - history    # Gets _history
            - quality    # Gets quality block
          extends:
            - document   # Gets title, purpose, audience

        spec:
          status: Draft
          schema:
            required:
              - id
              - name
              - price
            properties:
              name:
                type: string
              price:
                type: number
                minimum: 0
              description:
                type: string

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

    1. **Self-Describing**: This spec (`spec-schema.kno`) is itself a spec,
       demonstrating the meta-circular nature of the schema system.

    2. **Composition Over Inheritance**: Rather than "inheriting" from
       document-schema.kno, we use `extends` relationship to declare lineage
       and `composes` to pull in Layer 1 primitives.

    3. **Schema Lifecycle**:
       - Draft → Active → Deprecated/Superseded
       - Breaking changes require major version bump
       - Deprecation requires `superseded_by` pointer

    4. **Validation Strategy**: The `spec.schema` block uses a subset
       of JSON Schema for field definitions, enabling tooling to
       validate instances against specs.

    ## Open Questions

    - Should `composes` merge fields or just declare intent?
    - How to handle conflicting field definitions in composition?
    - Should we support spec inheritance chains (A extends B extends C)?

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 18
    keywords: [id, type, version, spec-schema]
  - path: "spec/fields"
    line: 80
    keywords: [title, purpose, status, composes, required_sections]
  - path: "spec/composition"
    line: 180
    keywords: [composes, extends, Layer-1, Layer-2, Layer-3]
  - path: "spec/sections"
    line: 280
    keywords: [required_sections, recommended_sections, optional_sections]
  - path: "spec/validation"
    line: 380
    keywords: [rules, severity, check, pattern]
  - path: "notes"
    line: 450
    keywords: [composition, inheritance, open-questions]

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [id, type, version]
  - xri: "#spec"
    role: section
    title: "Spec Schema"
    keywords: [composition, sections, validation]
  - xri: "#notes"
    role: section
    title: "Design Notes"
    keywords: [composition, open-questions]