# User Domain Schema — Layer 2 Entity Type
# KNO Schema Version: 0.0.6
#
# Layer 2 domain schema for User entities — people with identity and connections.
# This is a CORE ENTITY in Possibility's entity model.
#
# EXTENDS: document-schema.kno (Layer 2 base)
# COMPOSES: identity-schema, history-schema, quality-schema (Layer 1)
# ENABLES: User instances in content/users/

# =============================================================================
# BASIC TIER (required per kno-spec.kno)
# =============================================================================
$schema: kno@0.0.9
id: 01KGK3V73J91DJ8F8DPJMV3SSX
slug: user-schema
type: spec
version: 0.0.1

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "User Domain Schema"
purpose: |
  Define the schema for User entities — people with identity and connections.

  A User represents a person in the Possibility system. Users can have:
  - **Identity** — Canonical ID, display name, email, avatar
  - **External connections** — OAuth providers (GitHub, Google, etc.)
  - **Personas** — Roles in different organizational contexts
  - **Metadata** — Location, bio, timestamps

  This schema defines the structure that UserCard.astro renders.

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73J91DJ8F8DPJMV3SSX
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - entities
    - users
    - identity
    - domain-schemas
  keywords:
    - user
    - person
    - identity
    - profile
    - account

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

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification v0.0.6"

  composes:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: canonical_id, local_ids, equiv_ids pattern"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation, confidence"

  related_to:
    - xri: "kno://specs/organization-schema"
      reason: "Users belong to organizations via personas"

  enables:
    - xri: "kno://content/users/*"
      reason: "User instance files"
    - xri: "kno://content/examples/user-example"
      reason: "Example user entity"

quality:
  completeness: 0.9
  last_reviewed: "2026-01-14"
  review_status: draft
  reviewed_by: "claude"

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

  changelog:
    - version: "0.0.1"
      date: "2026-01-14"
      author: "claude"
      summary: "Initial user domain schema"
      changes:
        - "Created fresh from first principles per bedrock"
        - "Removed deprecated facets field (kno-spec v0.0.6)"
        - "Designed to match UserCard.astro component expectations"
        - "Added personas for multi-org representation"

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

  description: |
    ## User Entity Structure

    A User entity represents a person with identity and connections.
    The schema is designed for:

    1. **Display** — UserCard.astro renders the profile
    2. **Federation** — equiv_ids enable cross-system identity
    3. **Authorization** — personas define org-scoped roles

    ## Required vs Optional Fields

    | Field | Required | Purpose |
    |-------|----------|---------|
    | id | Yes | Unique identifier (ULID format: usr_*) |
    | type | Yes | Always "user" |
    | version | Yes | Semantic version |
    | name | Yes | Display name |
    | email | No | Contact email (enables Gravatar) |
    | identity | No | Federated identity block |
    | personas | No | Organizational roles |

  schema:
    type: object
    required:
      - id
      - type
      - version
      - name
    properties:
      # -----------------------------------------------------------------------
      # BASIC TIER (required)
      # -----------------------------------------------------------------------
      $schema:
        type: string
        description: "KNO schema version"
        const: "kno@0.0.9"

      id:
        type: string
        description: "Unique identifier (ULID format preferred: usr_*)"
        pattern: "^[a-zA-Z0-9_-]+$"
        examples:
          - "usr_01HXYZ789ABC"
          - "alex-chen"

      type:
        type: string
        description: "Entity type"
        const: "user"

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

      # -----------------------------------------------------------------------
      # STANDARD TIER (recommended)
      # -----------------------------------------------------------------------
      title:
        type: string
        description: "Human-readable title (usually same as name)"

      conforms_to:
        type: string
        description: "Schema this entity conforms to"
        const: "user-schema"

      # -----------------------------------------------------------------------
      # USER-SPECIFIC FIELDS
      # -----------------------------------------------------------------------
      name:
        type: string
        description: "Display name"
        examples:
          - "Alex Chen"

      email:
        type: string
        format: email
        description: "Primary email address (enables Gravatar)"
        examples:
          - "alex@example.com"

      bio:
        type: string
        description: "Short biography or description"
        examples:
          - "Software engineer passionate about knowledge systems."

      location:
        type: string
        description: "Geographic location"
        examples:
          - "San Francisco, CA"

      avatar_url:
        type: string
        format: uri
        description: "URL to avatar image (optional — falls back to Gravatar)"

      # -----------------------------------------------------------------------
      # FEDERATED IDENTITY (composed from identity-schema)
      # -----------------------------------------------------------------------
      identity:
        type: object
        description: "Federated identity for cross-system resolution"
        properties:
          canonical_id:
            type: string
            description: "Immutable, persistent identifier (never changes)"
            examples:
              - "usr_01HXYZ789ABC"

          local_ids:
            type: array
            description: "Human-friendly usernames/handles (can change)"
            items:
              type: string
            examples:
              - ["alexchen", "alex-c"]

          equiv_ids:
            type: array
            description: "External system identifiers for federation"
            items:
              type: object
              required:
                - provider
                - id
              properties:
                provider:
                  type: string
                  description: "OAuth provider name"
                  examples:
                    - "github"
                    - "google"
                id:
                  type: string
                  description: "User ID in the external system"
                verified:
                  type: boolean
                  description: "Whether this connection is verified"
                verified_at:
                  type: string
                  format: date-time

          avatar_url:
            type: string
            format: uri
            description: "Avatar URL from identity provider"

      # -----------------------------------------------------------------------
      # PERSONAS (multi-organization representation)
      # -----------------------------------------------------------------------
      personas:
        type: array
        description: |
          A user can have multiple personas, each representing them in a
          different organizational context with different permissions.
        items:
          type: object
          properties:
            id:
              type: string
              description: "Unique persona identifier"
              examples:
                - "persona_alex_pco"

            representing_org:
              type: string
              description: "Organization ID this persona represents the user for"
              examples:
                - "org_pco"

            role:
              type: string
              description: "Role within the representing organization"
              examples:
                - "contributor"
                - "admin"

            title:
              type: string
              description: "Job title or position"
              examples:
                - "Software Engineer"

            active:
              type: boolean
              description: "Whether this persona is currently active"
              default: true

      # -----------------------------------------------------------------------
      # LINKS (external profiles)
      # -----------------------------------------------------------------------
      links:
        type: array
        description: "External profile links"
        items:
          type: object
          required:
            - type
            - url
          properties:
            type:
              type: string
              description: "Link type"
              examples:
                - "github"
                - "website"
                - "linkedin"
            url:
              type: string
              format: uri
            label:
              type: string
              description: "Display label"

      # -----------------------------------------------------------------------
      # SKILLS (for discovery)
      # -----------------------------------------------------------------------
      skills:
        type: array
        description: "Skills and expertise"
        items:
          type: string
        examples:
          - ["TypeScript", "Rust", "Knowledge Graphs"]

      # -----------------------------------------------------------------------
      # METADATA
      # -----------------------------------------------------------------------
      metadata:
        type: object
        properties:
          created_at:
            type: string
            format: date-time
          updated_at:
            type: string
            format: date-time