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

?>