# =============================================================================
# Concept Registry (Ontology)
# =============================================================================
#
# Master dictionary of semantic concepts. Defines what things *mean* in the
# business domain: names, definitions, and hierarchical relationships.
#
# This file is the single source of truth for concept identifiers. Semantic
# annotations in ontology_mappings.yaml reference concepts by their `id` here.
#
# Predicates from knowledge_schema.yaml:
#   - kind       – Must be one of the node_kinds (entity, process, event,
#                  attribute, rule, system, concept, metric).
#   - broader    – Parent concept id; denotes inverse of is_a (narrower is_a
#                  broader). Typed edges between concepts (depends_on, describes,
#                  etc.) live in concept_relationships.yaml.
#
# Per-concept keys:
#   id         – Unique PascalCase identifier (required).
#   label      – Human-readable display name (required).
#   broader    – Parent concept id (omit for top-level). Semantics: is_a.
#   definition – What this concept means (recommended).
#   tags       – Categorization tags (optional).
#   kind       – Node kind from knowledge_schema.yaml (required).
#
# =============================================================================

scheme:
  id: StatFYITradingDomain
  title: StatFYI Trading Domain Ontology
  version: "1.0.0"
  description: >-
    Shared vocabulary for trading, portfolio, and data-platform domains.
    Concepts are organised in a SKOS-style hierarchy (broader / narrower).
    Node kinds and relationship types follow data/seed/knowledge_schema.yaml.

# =============================================================================
# Top-level concepts (no broader)
# =============================================================================
concepts:

  # ---------------------------------------------------------------------------
  # Identifier family
  # ---------------------------------------------------------------------------
  - id: Identifier
    label: Identifier
    kind: concept
    definition: A value that uniquely distinguishes one entity or record from another.

  - id: EntityIdentifier
    label: Entity Identifier
    broader: Identifier
    kind: attribute
    definition: A unique identifier scoped to a specific business entity.

  - id: OrderIdentifier
    label: Order Identifier
    broader: EntityIdentifier
    kind: entity
    definition: Unique identifier for an order in the trading system.
    tags: [identifier, primary_key]

  - id: SignalIdentifier
    label: Signal Identifier
    broader: EntityIdentifier
    kind: entity
    definition: Unique identifier for a trading signal.
    tags: [identifier, primary_key]

  - id: SessionIdentifier
    label: Session Identifier
    broader: EntityIdentifier
    kind: entity
    definition: Unique identifier for a trading session.
    tags: [identifier, primary_key]

  - id: AccountIdentifier
    label: Account Identifier
    broader: EntityIdentifier
    kind: entity
    definition: Unique identifier for a trading or brokerage account.
    tags: [identifier]

  - id: PortfolioIdentifier
    label: Portfolio Identifier
    broader: EntityIdentifier
    kind: entity
    definition: Unique identifier for a portfolio.
    tags: [identifier, primary_key]

  - id: RunIdentifier
    label: Run Identifier
    broader: EntityIdentifier
    kind: entity
    definition: Unique identifier for an optimization or computation run.
    tags: [identifier, primary_key]

  - id: ContactIdentifier
    label: Contact Identifier
    broader: Identifier
    kind: attribute
    definition: A value used to reach or address a person (email, phone, etc.).

  - id: EmailAddress
    label: Email Address
    broader: ContactIdentifier
    kind: attribute
    definition: Primary email address for a contact. Must be valid and deliverable.
    tags: [pii, contact]

  # ---------------------------------------------------------------------------
  # Descriptive attributes
  # ---------------------------------------------------------------------------
  - id: DescriptiveAttribute
    label: Descriptive Attribute
    kind: concept
    definition: A human-readable property that describes an entity.

  - id: EntityName
    label: Entity Name
    broader: DescriptiveAttribute
    kind: attribute
    definition: Human-readable name or label for an entity.

  - id: FullName
    label: Full Name
    broader: DescriptiveAttribute
    kind: attribute
    definition: Concatenation of given name and family name for display.

  - id: FreeTextNote
    label: Free Text Note
    broader: DescriptiveAttribute
    kind: attribute
    definition: Optional unstructured notes or comments.

  # ---------------------------------------------------------------------------
  # Numeric measures
  # ---------------------------------------------------------------------------
  - id: NumericMeasure
    label: Numeric Measure
    kind: concept
    definition: A quantitative value representing a count, amount, or score.

  - id: OrderQuantity
    label: Order Quantity
    broader: NumericMeasure
    kind: metric
    definition: Requested quantity in lots or units.

  - id: FilledQuantity
    label: Filled Quantity
    broader: NumericMeasure
    kind: metric
    definition: Quantity executed so far.

  - id: SignalStrength
    label: Signal Strength
    broader: NumericMeasure
    kind: metric
    definition: Score or confidence of a trading signal.

  - id: MonetaryAmount
    label: Monetary Amount
    broader: NumericMeasure
    kind: metric
    definition: A financial value denominated in a currency. Positive for credits, negative for debits.

  # ---------------------------------------------------------------------------
  # State / lifecycle
  # ---------------------------------------------------------------------------
  - id: State
    label: State
    kind: concept
    definition: A discrete stage in an entity's lifecycle governed by a finite-state machine.

  - id: OrderLifecycleState
    label: Order Lifecycle State
    broader: State
    kind: attribute
    definition: "Current FSM state for an order (e.g. PENDING_NEW, OPEN, FILLED, CANCELED)."

  - id: SignalLifecycleState
    label: Signal Lifecycle State
    broader: State
    kind: attribute
    definition: Current FSM state for a trading signal.

  - id: SessionLifecycleState
    label: Session Lifecycle State
    broader: State
    kind: attribute
    definition: "Current FSM state for a trading session (e.g. PRE_MARKET, EXECUTING, POST_MARKET)."

  - id: PortfolioLifecycleState
    label: Portfolio Lifecycle State
    broader: State
    kind: attribute
    definition: "Current FSM state for a portfolio (e.g. MONITORING, REBALANCING, DEACTIVATED)."

  - id: CycleLifecycleState
    label: Cycle Lifecycle State
    broader: State
    kind: attribute
    definition: "Current FSM state for an optimization cycle (e.g. DATA_COLLECTION, OPTIMIZING, COMPLETED)."

  - id: LifecycleStatus
    label: Lifecycle Status
    broader: State
    kind: attribute
    definition: "General lifecycle status of an entity (e.g. active, draft, archived)."

  # ---------------------------------------------------------------------------
  # Temporal attributes
  # ---------------------------------------------------------------------------
  - id: TemporalAttribute
    label: Temporal Attribute
    kind: concept
    definition: A point-in-time or duration value used for ordering, auditing, or scheduling.

  - id: CreationTimestamp
    label: Creation Timestamp
    broader: TemporalAttribute
    kind: attribute
    definition: ISO 8601 timestamp when the record was first created.

  - id: LastUpdateTimestamp
    label: Last Update Timestamp
    broader: TemporalAttribute
    kind: attribute
    definition: ISO 8601 timestamp of the most recent update.

  - id: SessionStart
    label: Session Start
    broader: TemporalAttribute
    kind: event
    definition: When a trading session started.

  - id: SessionEnd
    label: Session End
    broader: TemporalAttribute
    kind: event
    definition: When a trading session ended.

  - id: CycleStart
    label: Cycle Start
    broader: TemporalAttribute
    kind: event
    definition: When an optimization cycle started.

  - id: CycleEnd
    label: Cycle End
    broader: TemporalAttribute
    kind: event
    definition: When an optimization cycle reached a terminal state.

  - id: LastRebalanceTime
    label: Last Rebalance Time
    broader: TemporalAttribute
    kind: event
    definition: When the last rebalance cycle completed.

  # ---------------------------------------------------------------------------
  # Trading instruments
  # ---------------------------------------------------------------------------
  - id: TradingInstrument
    label: Trading Instrument
    kind: entity
    definition: A financial product or security that can be traded on a market.

  - id: InstrumentSymbol
    label: Instrument Symbol
    broader: TradingInstrument
    kind: attribute
    definition: Exchange or venue symbol for a traded instrument (ticker).

  # ---------------------------------------------------------------------------
  # Trading actions
  # ---------------------------------------------------------------------------
  - id: TradingAction
    label: Trading Action
    kind: concept
    definition: A directional decision in a trading workflow (buy, sell, long, short).

  - id: OrderSide
    label: Order Side
    broader: TradingAction
    kind: attribute
    definition: Direction of an order (buy or sell).

  - id: SignalDirection
    label: Signal Direction
    broader: TradingAction
    kind: attribute
    definition: Directional bias of a signal (long or short).

  # ---------------------------------------------------------------------------
  # Processes (sequence of steps; from knowledge_schema node_kinds)
  # ---------------------------------------------------------------------------
  - id: Process
    label: Process
    kind: concept
    definition: A sequence of steps or activities that transform inputs into outputs.

  - id: RebalancingProcess
    label: Rebalancing Process
    broader: Process
    kind: process
    definition: Workflow that adjusts portfolio weights to meet target allocation.

  - id: SignalGenerationProcess
    label: Signal Generation Process
    broader: Process
    kind: process
    definition: Pipeline that produces trading signals from market or reference data.

  # ---------------------------------------------------------------------------
  # Rules (constraints or policies; from knowledge_schema node_kinds)
  # ---------------------------------------------------------------------------
  - id: Rule
    label: Rule
    kind: concept
    definition: A constraint or policy that governs behaviour or validation.

  - id: ComplianceRule
    label: Compliance Rule
    broader: Rule
    kind: rule
    definition: Policy or regulation that trading or data handling must satisfy.

  - id: TradingRule
    label: Trading Rule
    broader: Rule
    kind: rule
    definition: Constraint on order placement, position size, or execution (e.g. risk limits).

  # ---------------------------------------------------------------------------
  # Systems (external system or service; from knowledge_schema node_kinds)
  # ---------------------------------------------------------------------------
  - id: System
    label: System
    kind: concept
    definition: An external system or service that integrates with the platform.

  - id: TradingVenue
    label: Trading Venue
    broader: System
    kind: system
    definition: Exchange or execution venue where orders are sent (e.g. broker, ECN).

  - id: MarketDataSystem
    label: Market Data System
    broader: System
    kind: system
    definition: External service providing prices, reference data, or analytics.
