Return Schemas
Data structures and validation rules for each return type
Base Structure
{
"type": "monthly",
"period": {
"start": "2024-01-01",
"end": "2024-01-31"
},
"pfa": {
"code": "PFA123",
"name": "Example PFA Ltd"
},
"contributions": {
// See Contribution Details schema
},
"investments": {
// See Investment Summary schema
},
"portfolio": {
// See Portfolio Details schema
},
"compliance": {
// See Compliance Data schema
},
"attachments": [
// See Attachments schema
]
}
Contribution Details
{
"total_contributions": {
"employee": 0.00,
"employer": 0.00
},
"contributions_by_sector": [
{
"sector": "public",
"employee": 0.00,
"employer": 0.00
},
{
"sector": "private",
"employee": 0.00,
"employer": 0.00
}
],
"contribution_count": {
"total": 0,
"processed": 0,
"pending": 0,
"rejected": 0
}
}
Investment Summary
{
"total_aum": 0.00,
"asset_allocation": {
"equities": {
"amount": 0.00,
"percentage": 0.00
},
"fixed_income": {
"amount": 0.00,
"percentage": 0.00
},
"money_market": {
"amount": 0.00,
"percentage": 0.00
},
"alternative_investments": {
"amount": 0.00,
"percentage": 0.00
}
},
"performance": {
"ytd_return": 0.00,
"1yr_return": 0.00,
"3yr_return": 0.00
}
}
Portfolio Details
{
"holdings": [
{
"security_type": "equity",
"security_name": "Example Stock",
"quantity": 0,
"cost_basis": 0.00,
"market_value": 0.00,
"unrealized_gain": 0.00
}
],
"transactions": [
{
"date": "2024-01-15",
"type": "buy",
"security_name": "Example Bond",
"quantity": 0,
"price": 0.00,
"total": 0.00
}
]
}
Compliance Data
{
"investment_limits": {
"equities": {
"limit": 25.00,
"actual": 0.00,
"compliant": true
},
"fixed_income": {
"limit": 80.00,
"actual": 0.00,
"compliant": true
}
},
"risk_metrics": {
"var_95": 0.00,
"sharpe_ratio": 0.00,
"tracking_error": 0.00
},
"violations": []
}
Attachments
[
{
"type": "valuation_report",
"filename": "valuation_2024_01.pdf",
"content_type": "application/pdf",
"size": 1048576,
"hash": "sha256:abc123..."
}
]
Important Validation Rules
Period Validation: Start and end dates must be within the same month
Currency: All monetary values must be in Nigerian Naira (NGN)
Asset Allocation: Percentages must sum to 100%
PEN Validation: All PEN numbers must be valid and registered
Required Attachments: Valuation report is mandatory