💼 StockBud.io Portfolio Schema

Version: 1.0.0

Schema for portfolio data structures used in StockBud.io trading system

Overview

This schema defines 4 data structures:

Position - Individual position within a portfolio...
Portfolio - Complete portfolio structure...
PortfolioInsight - AI-generated portfolio insight or analysis...
PortfolioTarget - Target portfolio allocation generated by AI strategies...

Definitions

Position

Individual position within a portfolio

Properties

Property	Type	Required	Description
`symbol`	`string`	✓	Stock symbol
`quantity`	`number`	✓	Position quantity (can be fractional)
`market_value`	`number`	✓	Current market value of position
`cost_basis`	`number`	✓	Total cost basis of position
`unrealized_pnl`	`number`		Unrealized profit/loss
`realized_pnl`	`number`		Realized profit/loss
`side`	`enum: 'long', 'short'`	✓	Position side
`average_entry_price`	`number`		Average entry price
`current_price`	`number`		Current market price
`weight`	`number`		Position weight as percentage of portfolio
`sector`	`string`		Sector classification
`last_update`	`string`		Last position update timestamp

TypeScript

interface Position {
  /** Stock symbol */
  symbol: string;
  /** Position quantity (can be fractional) */
  quantity: number;
  /** Current market value of position */
  market_value: number;
  /** Total cost basis of position */
  cost_basis: number;
  /** Unrealized profit/loss */
  unrealized_pnl?: number;
  /** Realized profit/loss */
  realized_pnl?: number;
  /** Position side */
  side: "long" | "short";
  /** Average entry price */
  average_entry_price?: number;
  /** Current market price */
  current_price?: number;
  /** Position weight as percentage of portfolio */
  weight?: number;
  /** Sector classification */
  sector?: string;
  /** Last position update timestamp */
  last_update?: string;
}

Portfolio

Complete portfolio structure

Properties

Property	Type	Required	Description
`account_id`	`string`	✓	Unique account identifier
`account_type`	`enum: 'paper', 'live'`		Account type
`account_value`	`number`	✓	Total account value
`cash_balance`	`number`	✓	Available cash balance
`buying_power`	`number`		Current buying power
`day_trade_buying_power`	`number`		Day trading buying power
`equity`	`number`		Total equity value
`portfolio_value`	`number`		Total portfolio value including cash
`positions`	`Array<Position>`	✓	Array of current positions
`daily_pnl`	`number`		Daily profit/loss
`total_pnl`	`number`		Total profit/loss
`margin_used`	`number`		Amount of margin currently used
`maintenance_margin`	`number`		Required maintenance margin
`last_sync`	`string`		Last synchronization timestamp
`created_at`	`string`		Portfolio creation timestamp
`updated_at`	`string`		Last update timestamp

TypeScript

interface Portfolio {
  /** Unique account identifier */
  account_id: string;
  /** Account type */
  account_type?: "paper" | "live";
  /** Total account value */
  account_value: number;
  /** Available cash balance */
  cash_balance: number;
  /** Current buying power */
  buying_power?: number;
  /** Day trading buying power */
  day_trade_buying_power?: number;
  /** Total equity value */
  equity?: number;
  /** Total portfolio value including cash */
  portfolio_value?: number;
  /** Array of current positions */
  positions: Position[];
  /** Daily profit/loss */
  daily_pnl?: number;
  /** Total profit/loss */
  total_pnl?: number;
  /** Amount of margin currently used */
  margin_used?: number;
  /** Required maintenance margin */
  maintenance_margin?: number;
  /** Last synchronization timestamp */
  last_sync?: string;
  /** Portfolio creation timestamp */
  created_at?: string;
  /** Last update timestamp */
  updated_at?: string;
}

PortfolioInsight

AI-generated portfolio insight or analysis

Properties

Property	Type	Required	Description
`type`	`enum: 'risk_analysis', 'performance_analysis', 'diversification_analysis', 'sector_allocation', 'position_sizing', 'rebalancing_suggestion', 'market_opportunity', 'risk_warning'`	✓	Type of insight
`severity`	`enum: 'low', 'medium', 'high', 'critical'`	✓	Severity level of the insight
`confidence`	`number`	✓	Confidence level of the insight (0-1)
`title`	`string`	✓	Brief insight title
`message`	`string`	✓	Detailed insight message
`recommendations`	`Array<string>`		List of actionable recommendations
`affected_symbols`	`Array<string>`		Symbols affected by this insight
`data`	`object`		Additional data supporting the insight
`timestamp`	`string`		Insight generation timestamp
`expires_at`	`string`		When this insight expires

TypeScript

interface PortfolioInsight {
  /** Type of insight */
  type: "risk_analysis" | "performance_analysis" | "diversification_analysis" | "sector_allocation" | "position_sizing" | "rebalancing_suggestion" | "market_opportunity" | "risk_warning";
  /** Severity level of the insight */
  severity: "low" | "medium" | "high" | "critical";
  /** Confidence level of the insight (0-1) */
  confidence: number;
  /** Brief insight title */
  title: string;
  /** Detailed insight message */
  message: string;
  /** List of actionable recommendations */
  recommendations?: string[];
  /** Symbols affected by this insight */
  affected_symbols?: string[];
  /** Additional data supporting the insight */
  data?: Record<string, unknown>;
  /** Insight generation timestamp */
  timestamp?: string;
  /** When this insight expires */
  expires_at?: string;
}

PortfolioTarget

Target portfolio allocation generated by AI strategies

Properties

Property	Type	Required	Description
`strategy_name`	`string`	✓	Name of the strategy that generated this target
`target_weights`	`object`	✓	Target weights by symbol
`cash_target`	`number`		Target cash allocation
`rebalance_threshold`	`number`		Threshold for triggering rebalancing
`confidence`	`number`		Confidence in this target allocation
`risk_score`	`number`		Risk score of target portfolio (0-10)
`expected_return`	`number`		Expected annual return
`expected_volatility`	`number`		Expected annual volatility
`rationale`	`string`		Explanation of the target allocation
`generated_at`	`string`	✓	Target generation timestamp
`valid_until`	`string`		Target validity expiration

TypeScript

interface PortfolioTarget {
  /** Name of the strategy that generated this target */
  strategy_name: string;
  /** Target weights by symbol */
  target_weights: Record<string, unknown>;
  /** Target cash allocation */
  cash_target?: number;
  /** Threshold for triggering rebalancing */
  rebalance_threshold?: number;
  /** Confidence in this target allocation */
  confidence?: number;
  /** Risk score of target portfolio (0-10) */
  risk_score?: number;
  /** Expected annual return */
  expected_return?: number;
  /** Expected annual volatility */
  expected_volatility?: number;
  /** Explanation of the target allocation */
  rationale?: string;
  /** Target generation timestamp */
  generated_at: string;
  /** Target validity expiration */
  valid_until?: string;
}

Usage Example

import type { Position, Portfolio, PortfolioInsight, PortfolioTarget } from '@stockbud/schemas';
 
// Create a new Position
const example: Position = {
  symbol: "example-value",
  quantity: 0,
  market_value: 0,
  cost_basis: 0,
  side: "example-value",
};

Full JSON Schema

Click to expand raw JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "StockBud.io Portfolio Schema",
  "description": "Schema for portfolio data structures used in StockBud.io trading system",
  "version": "1.0.0",
  "type": "object",
  "definitions": {
    "Position": {
      "type": "object",
      "description": "Individual position within a portfolio",
      "required": [
        "symbol",
        "quantity",
        "market_value",
        "cost_basis",
        "side"
      ],
      "properties": {
        "symbol": {
          "type": "string",
          "pattern": "^[A-Z]{1,5}$",
          "description": "Stock symbol"
        },
        "quantity": {
          "type": "number",
          "description": "Position quantity (can be fractional)"
        },
        "market_value": {
          "type": "number",
          "minimum": 0,
          "description": "Current market value of position"
        },
        "cost_basis": {
          "type": "number",
          "minimum": 0,
          "description": "Total cost basis of position"
        },
        "unrealized_pnl": {
          "type": "number",
          "description": "Unrealized profit/loss"
        },
        "realized_pnl": {
          "type": "number",
          "description": "Realized profit/loss"
        },
        "side": {
          "type": "string",
          "enum": [
            "long",
            "short"
          ],
          "description": "Position side"
        },
        "average_entry_price": {
          "type": "number",
          "minimum": 0,
          "description": "Average entry price"
        },
        "current_price": {
          "type": "number",
          "minimum": 0,
          "description": "Current market price"
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Position weight as percentage of portfolio"
        },
        "sector": {
          "type": "string",
          "description": "Sector classification"
        },
        "last_update": {
          "type": "string",
          "format": "date-time",
          "description": "Last position update timestamp"
        }
      }
    },
    "Portfolio": {
      "type": "object",
      "description": "Complete portfolio structure",
      "required": [
        "account_id",
        "account_value",
        "cash_balance",
        "positions"
      ],
      "properties": {
        "account_id": {
          "type": "string",
          "description": "Unique account identifier"
        },
        "account_type": {
          "type": "string",
          "enum": [
            "paper",
            "live"
          ],
          "description": "Account type"
        },
        "account_value": {
          "type": "number",
          "minimum": 0,
          "description": "Total account value"
        },
        "cash_balance": {
          "type": "number",
          "minimum": 0,
          "description": "Available cash balance"
        },
        "buying_power": {
          "type": "number",
          "minimum": 0,
          "description": "Current buying power"
        },
        "day_trade_buying_power": {
          "type": "number",
          "minimum": 0,
          "description": "Day trading buying power"
        },
        "equity": {
          "type": "number",
          "minimum": 0,
          "description": "Total equity value"
        },
        "portfolio_value": {
          "type": "number",
          "minimum": 0,
          "description": "Total portfolio value including cash"
        },
        "positions": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Position"
          },
          "description": "Array of current positions"
        },
        "daily_pnl": {
          "type": "number",
          "description": "Daily profit/loss"
        },
        "total_pnl": {
          "type": "number",
          "description": "Total profit/loss"
        },
        "margin_used": {
          "type": "number",
          "minimum": 0,
          "description": "Amount of margin currently used"
        },
        "maintenance_margin": {
          "type": "number",
          "minimum": 0,
          "description": "Required maintenance margin"
        },
        "last_sync": {
          "type": "string",
          "format": "date-time",
          "description": "Last synchronization timestamp"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Portfolio creation timestamp"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Last update timestamp"
        }
      }
    },
    "PortfolioInsight": {
      "type": "object",
      "description": "AI-generated portfolio insight or analysis",
      "required": [
        "type",
        "severity",
        "confidence",
        "title",
        "message"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "risk_analysis",
            "performance_analysis",
            "diversification_analysis",
            "sector_allocation",
            "position_sizing",
            "rebalancing_suggestion",
            "market_opportunity",
            "risk_warning"
          ],
          "description": "Type of insight"
        },
        "severity": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "critical"
          ],
          "description": "Severity level of the insight"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Confidence level of the insight (0-1)"
        },
        "title": {
          "type": "string",
          "description": "Brief insight title"
        },
        "message": {
          "type": "string",
          "description": "Detailed insight message"
        },
        "recommendations": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "List of actionable recommendations"
        },
        "affected_symbols": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Symbols affected by this insight"
        },
        "data": {
          "type": "object",
          "description": "Additional data supporting the insight"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "Insight generation timestamp"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "When this insight expires"
        }
      }
    },
    "PortfolioTarget": {
      "type": "object",
      "description": "Target portfolio allocation generated by AI strategies",
      "required": [
        "strategy_name",
        "target_weights",
        "generated_at"
      ],
      "properties": {
        "strategy_name": {
          "type": "string",
          "description": "Name of the strategy that generated this target"
        },
        "target_weights": {
          "type": "object",
          "patternProperties": {
            "^[A-Z]{1,5}$": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          },
          "description": "Target weights by symbol"
        },
        "cash_target": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Target cash allocation"
        },
        "rebalance_threshold": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "default": 0.05,
          "description": "Threshold for triggering rebalancing"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Confidence in this target allocation"
        },
        "risk_score": {
          "type": "number",
          "minimum": 0,
          "maximum": 10,
          "description": "Risk score of target portfolio (0-10)"
        },
        "expected_return": {
          "type": "number",
          "description": "Expected annual return"
        },
        "expected_volatility": {
          "type": "number",
          "minimum": 0,
          "description": "Expected annual volatility"
        },
        "rationale": {
          "type": "string",
          "description": "Explanation of the target allocation"
        },
        "generated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Target generation timestamp"
        },
        "valid_until": {
          "type": "string",
          "format": "date-time",
          "description": "Target validity expiration"
        }
      }
    }
  },
  "properties": {
    "portfolio": {
      "$ref": "#/definitions/Portfolio"
    },
    "insights": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/PortfolioInsight"
      }
    },
    "targets": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/PortfolioTarget"
      }
    }
  }
}

StockBud.io Portfolio Schema

On this page