📐 JSON Schemas

StockBud uses JSON Schema (Draft-07) for data validation across all components. These schemas define the structure of portfolios, trades, market data, and more.

All schemas are available in kb_catalog/schemas/ and can be used for TypeScript type generation.

Schema Catalog

Schema	Description
💼 Portfolio	Positions, portfolio insights, and allocation targets
📈 Trading	Orders, trades, signals, and strategies
🏛️ Market Data	Quotes, OHLCV bars, options, and news
🔌 MCP Server	Tool definitions, requests, and responses
🤖 AI Agents	Personas, memory, and behavioral patterns
📊 Metrics	Performance tracking and analytics
⚙️ Configuration	System config and deployment settings
🔔 Notifications	Alerts, templates, and preferences

Using Schemas

TypeScript Type Generation

Generate TypeScript types from our JSON schemas:

# Using json-schema-to-typescript
npx json-schema-to-typescript \
  -i kb_catalog/schemas/*.json \
  -o types/

Python Validation

import json
import jsonschema
 
# Load the schema
with open('kb_catalog/schemas/portfolio.json') as f:
    schema = json.load(f)
 
# Validate your data
portfolio_data = {
    "account_id": "abc123",
    "account_value": 125000.00,
    "cash_balance": 25000.00,
    "positions": []
}
 
jsonschema.validate(portfolio_data, schema)
print("✅ Valid portfolio data!")

OpenAPI Integration

Reference schemas in your OpenAPI spec:

components:
  schemas:
    Portfolio:
      $ref: './kb_catalog/schemas/portfolio.json#/definitions/Portfolio'
    Position:
      $ref: './kb_catalog/schemas/portfolio.json#/definitions/Position'

Schema Versioning

All schemas follow semantic versioning:

Version Part	When to Update
Major	Breaking changes (removed fields, type changes)
Minor	New optional fields, new definitions
Patch	Bug fixes, description updates

Current version: 1.0.0

Data Flow

Market Data ──► Trading Signals ──► Orders ──► Trades
     │               │                │          │
     ▼               ▼                ▼          ▼
Portfolios ◄── Positions ◄────────────────────────┘
     │
     ▼
AI Analysis ──► Insights ──► Notifications

Contributing

Found an issue with a schema? Submit a PR to kb_catalog/schemas/ with your proposed changes.

⚠️ Schema changes may break existing integrations. Always increment the version appropriately and document changes.

JSON Schemas

On this page