{
  "$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"
      }
    }
  ]
}