$schema: http://json-schema.org/draft-07/schema#
$id: https://github.com/avadisabelle/coaia-narrative/schema/data-model/relation.json
title: COAIA Relation
description: >-
  Relation structure connecting entities in the COAIA knowledge graph. Relations define typed
  connections with optional metadata for context and strength.
type: object
required:
  - from
  - to
  - relationType
properties:
  from:
    type: string
    description: Source entity name (must match an existing entity's name field)
  to:
    type: string
    description: Target entity name (must match an existing entity's name field)
  relationType:
    type: string
    description: Type of relationship between entities
    enum:
      - creates_tension_with
      - advances_toward
      - telescopes_into
      - flows_into
      - wampum_holds_accountable
      - wampum_witnesses
      - part_of
      - related_to
      - depends_on
      - influences
      - precedes
      - follows
      - contains
      - member_of
      - owns
      - created_by
      - mentions
      - references
      - custom
  metadata:
    type: object
    description: Optional metadata providing additional context about the relation
    properties:
      createdAt:
        type: string
        format: date-time
        description: ISO 8601 timestamp of relation creation
      strength:
        type: number
        description: Strength or weight of the relation (0-1 scale)
        minimum: 0
        maximum: 1
      context:
        type: string
        description: Contextual information about when/where/why this relation exists
      description:
        type: string
        description: Human-readable description of the relation
examples:
  - from: chart_123_current_reality
    to: chart_123_desired_outcome
    relationType: creates_tension_with
    metadata:
      description: The gap between current reality and desired outcome creates productive structural tension
      createdAt: '2026-02-13T07:00:00Z'
  - from: chart_123_action_1
    to: chart_123_desired_outcome
    relationType: advances_toward
    metadata:
      description: Completing this action step moves the system closer to the desired outcome
      strength: 0.8
  - from: chart_123_action_1
    to: chart_456
    relationType: telescopes_into
    metadata:
      description: This action has been broken down into a detailed sub-chart
  - from: chart_123_action_1
    to: chart_123_current_reality
    relationType: flows_into
    metadata:
      description: Upon completion, this action's result becomes part of current reality
      createdAt: '2026-02-13T08:00:00Z'