# =============================================================================
# Knowledge Ontology Schema
# =============================================================================
#
# Meta-schema defining the valid relationship types and node kinds for the
# pycharter knowledge graph.  This file is the single source of truth --
# schema_loader.py reads it at startup and validators reference it at runtime.
#
# relationship_types  - typed edges between concepts or fields
# node_kinds          - classification buckets for concepts
#
# =============================================================================

version: 1

# -----------------------------------------------------------------------------
# Relationship types
#
# Each entry carries:
#   meaning      – one-line explanation
#   graph_shape  – visual layout hint for the frontend graph renderer
#   inverse      – name of the inverse edge (auto-created on traversal)
#   symmetric    – true when the relationship is its own inverse
# -----------------------------------------------------------------------------
relationship_types:
  is_a:
    meaning: "X is a kind of Y"
    graph_shape: taxonomy_tree
    inverse: has_subtype

  has:
    meaning: "X contains or owns Y"
    graph_shape: composition_tree
    inverse: part_of

  depends_on:
    meaning: "X requires Y to function"
    graph_shape: dag
    inverse: depended_on_by

  derived_from:
    meaning: "X is computed from Y"
    graph_shape: dag
    inverse: derives

  precedes:
    meaning: "X happens before Y"
    graph_shape: timeline
    inverse: follows

  causes:
    meaning: "X leads to or triggers Y"
    graph_shape: causal_chain
    inverse: caused_by

  implements:
    meaning: "X realizes or is a concrete form of Y"
    graph_shape: abstraction_layers
    inverse: implemented_by

  governs:
    meaning: "X constrains or regulates Y"
    graph_shape: rule_graph
    inverse: governed_by

  describes:
    meaning: "X is a property or attribute of Y"
    graph_shape: attribute_map
    inverse: described_by

  equivalent_to:
    meaning: "X represents the same thing as Y"
    graph_shape: equivalence_set
    inverse: equivalent_to
    symmetric: true

  related_to:
    meaning: "X is loosely associated with Y"
    graph_shape: generic
    inverse: related_to
    symmetric: true

  references:
    meaning: "X points to or cites Y (foreign-key style)"
    graph_shape: dag
    inverse: referenced_by

  same_as:
    meaning: "X and Y denote the identical real-world entity"
    graph_shape: equivalence_set
    inverse: same_as
    symmetric: true

# -----------------------------------------------------------------------------
# Node kinds — concept classification buckets
# -----------------------------------------------------------------------------
node_kinds:
  entity: "A thing with identity (customer, product, system)"
  process: "A sequence of steps (checkout, onboarding)"
  event: "Something that happens at a point in time (payment failure, login)"
  attribute: "A property or measurement (churn risk score, age)"
  rule: "A constraint or policy (GDPR, rate limit)"
  system: "An external system or service (Stripe, Auth0)"
  concept: "An abstract idea (scalability, consistency)"
  metric: "A computed business measure (monthly active users, Sharpe ratio)"
