# Organization Domain Schema — Layer 2 Entity Type
# KNO Schema Version: 0.0.6
#
# Layer 2 domain schema for Organization entities — containers for users and possibilities.
# 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: Organization instances in content/organizations/

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

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Organization Domain Schema"
purpose: |
  Define the schema for Organization entities — containers for users and possibilities.

  An Organization represents a company, team, or group in the Possibility system.
  Organizations can have:
  - **Identity** — Name, tagline, logo, website
  - **Legal** — Entity type, jurisdiction
  - **Members** — Users with roles in this org
  - **Ownership** — Founders and beneficial owners
  - **Metadata** — Location, founding date, team size

  This schema defines the structure that OrgProfile.astro renders.

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73KE6AKBP3YD2X9BP96
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - entities
    - organizations
    - companies
    - domain-schemas
  keywords:
    - organization
    - company
    - team
    - group
    - legal-entity

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/user-schema"
      reason: "Organizations contain users as members"

  enables:
    - xri: "kno://content/organizations/*"
      reason: "Organization instance files"
    - xri: "kno://content/examples/organization-example"
      reason: "Example organization 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 organization domain schema"
      changes:
        - "Created fresh from first principles per bedrock"
        - "Removed deprecated facets field (kno-spec v0.0.6)"
        - "Designed to match OrgProfile.astro component expectations"
        - "Added legal and ownership facets"

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

  description: |
    ## Organization Entity Structure

    An Organization entity represents a company, team, or group.
    The schema is designed for:

    1. **Display** — OrgProfile.astro renders the profile
    2. **Federation** — equiv_ids enable cross-system identity
    3. **Membership** — members define who belongs to the org

    ## Required vs Optional Fields

    | Field | Required | Purpose |
    |-------|----------|---------|
    | id | Yes | Unique identifier (ULID format: org_*) |
    | type | Yes | Always "organization" |
    | version | Yes | Semantic version |
    | name | Yes | Organization name |
    | metadata | No | Description, website, logo |
    | legal | No | Entity type, jurisdiction |
    | ownership | No | Founders, beneficial owners |
    | members | No | User memberships |

  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: org_*)"
        pattern: "^[a-zA-Z0-9_-]+$"
        examples:
          - "org_01HXYZ789ABC"
          - "possibility-co"

      type:
        type: string
        description: "Entity type"
        const: "organization"

      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: "organization-schema"

      # -----------------------------------------------------------------------
      # ORGANIZATION-SPECIFIC FIELDS
      # -----------------------------------------------------------------------
      name:
        type: string
        description: "Organization name"
        examples:
          - "Possibility"
          - "Acme Corp"

      # -----------------------------------------------------------------------
      # METADATA
      # -----------------------------------------------------------------------
      metadata:
        type: object
        description: "Organization metadata"
        properties:
          tagline:
            type: string
            description: "Short tagline or slogan"
            examples:
              - "Turn possibilities into reality"

          description:
            type: string
            description: "Full description of the organization"

          website:
            type: string
            format: uri
            description: "Primary website URL"
            examples:
              - "https://possibility.space"

          logo_url:
            type: string
            format: uri
            description: "URL to organization logo"

          founded:
            type: string
            description: "Year founded"
            examples:
              - "2025"

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

          team_size:
            type: string
            description: "Team size range"
            examples:
              - "1-10"
              - "11-50"

          created_at:
            type: string
            format: date-time

          updated_at:
            type: string
            format: date-time

      # -----------------------------------------------------------------------
      # 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:
              - "org_01HXYZ789ABC"

          local_ids:
            type: array
            description: "Human-friendly aliases (can change)"
            items:
              type: string
            examples:
              - ["pspace", "possibility-co"]

          equiv_ids:
            type: array
            description: "External system identifiers for federation"
            items:
              type: object
              required:
                - provider
                - id
              properties:
                provider:
                  type: string
                  description: "External system provider"
                  examples:
                    - "github"
                    - "stripe"
                    - "mercury"
                id:
                  type: string
                  description: "Organization ID in the external system"

      # -----------------------------------------------------------------------
      # LEGAL ENTITY INFORMATION
      # -----------------------------------------------------------------------
      legal:
        type: object
        description: "Legal entity information"
        properties:
          entity_type:
            type: string
            description: "Legal entity type"
            examples:
              - "LLC"
              - "C-Corp"
              - "Non-profit"

          jurisdiction:
            type: string
            description: "Legal jurisdiction"
            examples:
              - "Delaware, USA"
              - "California, USA"

          ein:
            type: string
            description: "Employer Identification Number (redacted in examples)"

      # -----------------------------------------------------------------------
      # OWNERSHIP
      # -----------------------------------------------------------------------
      ownership:
        type: object
        description: "Ownership information"
        properties:
          founders:
            type: array
            description: "Founding members"
            items:
              type: object
              properties:
                name:
                  type: string
                user_id:
                  type: string
                  description: "XRI to user entity"
                role:
                  type: string
                ownership_percent:
                  type: number

      # -----------------------------------------------------------------------
      # MEMBERS
      # -----------------------------------------------------------------------
      members:
        type: array
        description: "Organization members"
        items:
          type: object
          properties:
            user_id:
              type: string
              description: "XRI to user entity"
            name:
              type: string
            role:
              type: string
              examples:
                - "admin"
                - "member"
                - "owner"
            title:
              type: string
              description: "Job title"

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

      # -----------------------------------------------------------------------
      # FOCUS AREAS (for discovery)
      # -----------------------------------------------------------------------
      focus_areas:
        type: array
        description: "Areas of focus or expertise"
        items:
          type: string
        examples:
          - ["Knowledge Systems", "Developer Tools"]