Scenario Schema

Scenario Schema

The SaveableScenario schema represents a complete mortgage scenario with all applicant details, properties, loans, income, expenses, and liabilities.

Overview

A scenario consists of multiple components that together describe the complete financial picture:

• Households: Applicant groups (individuals or couples)
• Income: All income sources (PAYG, self-employed, rental, etc.)
• Securities: Properties involved in the transaction
• Home Loans: Proposed or existing mortgage products
• Liabilities: Credit cards, personal loans, etc.
• Living Expenses: Household spending
• Links: Connections between loans and securities

Full Schema Structure

interface SaveableScenario {
  households: Household[];
  income: Income[];
  securities: Security[];
  home_loans: HomeLoan[];
  liabilities: Liability[];
  living_expenses: LivingExpense[];
  rental_income: RentalIncome[];
  self_employed_income: SelfEmployedIncome[];
  home_loan_security_links: HomeLoanSecurityLink[];
  additional_info: AdditionalInfo;
}

Detailed Field Descriptions

Households

Represents applicants/borrowers and their household configuration.

Field	Type	Required	Description
id	string	Yes	Unique identifier for this household
status	enum	Yes	Relationship status: 'single', 'couple', 'de_facto', 'divorced', 'separated', 'widowed'
num_adults	number	Yes	Number of adults in household (1-2)
num_dependants	number	Yes	Number of dependent children
postcode	number	Yes	Australian postcode (1000-9999)
shared_with_households	string[]	Yes	IDs of other households sharing expenses

Example:

{
  "id": "household-1",
  "status": "couple",
  "num_adults": 2,
  "num_dependants": 2,
  "postcode": 2000,
  "shared_with_households": []
}

Income

Income sources for applicants. All monetary values are annual unless specified otherwise.

Field	Type	Required	Description
id	string	Yes	Unique identifier
which_household	number	Yes	Index of household (0-based)
name	string	Yes	Income source name/description
payg	number	Yes	PAYG (base salary) annual income
casual	number	Yes	Casual employment income
commission	number	Yes	Commission income
overtime	number	Yes	Overtime income
bonus	number	Yes	Bonus income
allowances	number	Yes	Allowances (car, housing, etc.)
superannuation_income	number	Yes	Super/pension income
centrelink	number	Yes	Government benefits
child_support_received	number	Yes	Child support received
other_income	number	Yes	Other miscellaneous income

Example:

{
  "id": "income-1",
  "which_household": 0,
  "name": "Primary Employment",
  "payg": 120000,
  "casual": 0,
  "commission": 15000,
  "overtime": 5000,
  "bonus": 10000,
  "allowances": 0,
  "superannuation_income": 0,
  "centrelink": 0,
  "child_support_received": 0,
  "other_income": 0
}

Securities (Properties)

Properties involved in the mortgage transaction.

Field	Type	Required	Description
id	string	Yes	Unique identifier
address	string	Yes	Property address
postcode	string	Yes	Property postcode
transaction_type	enum	Yes	'purchasing', 'refinancing', 'owned'
applicant_ownership	number[]	Yes	Ownership percentage per applicant (must sum to 100)
value	number	Yes	Property value in AUD
property_type	enum	Yes	'house', 'unit', 'townhouse', 'apartment', 'land', etc.
property_purpose	enum	Yes	'owner_occupied' or 'investment'
rental_type	enum	No	'residential' or 'commercial' (for investment properties)
weekly_rental_income	number	No	Weekly rental income if investment property
monthly_rental_expense	number	No	Monthly rental expenses (strata, rates, etc.)

Example:

{
  "id": "property-1",
  "address": "123 Main Street, Sydney NSW 2000",
  "postcode": "2000",
  "transaction_type": "purchasing",
  "applicant_ownership": [50, 50],
  "value": 850000,
  "property_type": "house",
  "property_purpose": "owner_occupied",
  "rental_type": "residential",
  "weekly_rental_income": 0,
  "monthly_rental_expense": 0
}

Home Loans

Proposed or existing mortgage loans.

Field	Type	Required	Description
id	string	Yes	Unique identifier
product_type	enum	Yes	'variable_package', 'variable_basic', 'fixed', 'line_of_credit', 'construction'
existing_or_proposed	enum	Yes	'existing' or 'proposed'
loan_type	enum	Yes	'owner_occupied' or 'investment'
lvr	number	Yes	Loan-to-value ratio (0-100)
loan_amount	number	Yes	Loan amount in AUD
term	number	Yes	Loan term in years
interest_only_period	number	Yes	Interest-only period in years (0 if P&I)
lvr_behavior	string	Yes	How to calculate LVR: 'use-input' or auto-calculate

Example:

{
  "id": "loan-1",
  "product_type": "variable_package",
  "existing_or_proposed": "proposed",
  "loan_type": "owner_occupied",
  "lvr": 80,
  "loan_amount": 680000,
  "term": 30,
  "interest_only_period": 0,
  "lvr_behavior": "use-input"
}

Liabilities

Existing debts and credit commitments.

Field	Type	Required	Description
id	string	Yes	Unique identifier
loan_type	enum	Yes	'credit_card', 'personal_loan', 'car_loan', 'student_loan', 'other_liability'
limit	number	Yes	Credit limit or total debt amount
monthly_repayment	number	Yes	Monthly repayment amount
rate	number	Yes	Interest rate (percentage)
remaining_term	number	Yes	Remaining term in months

Example:

{
  "id": "liability-1",
  "loan_type": "credit_card",
  "limit": 15000,
  "monthly_repayment": 300,
  "rate": 19.5,
  "remaining_term": 0
}

Living Expenses

Household living expenses for servicing calculations.

Field	Type	Required	Description
id	string	Yes	Unique identifier
simple_basic_expense	number	Yes	Simple monthly basic living expenses
use_detailed_basic_expense	boolean	Yes	Whether to use detailed expense breakdown
primary_residence	number	Yes	Primary residence costs (rent/mortgage)
phone_internet_media	number	Yes	Communications and media
food_and_groceries	number	Yes	Food and grocery spending
transport	number	Yes	Transport costs
utilities	number	Yes	Electricity, gas, water
clothing	number	Yes	Clothing expenses
medical	number	Yes	Medical and health costs
education	number	Yes	Education expenses
childcare	number	Yes	Childcare costs
insurance	number	Yes	Insurance premiums
recreation	number	Yes	Recreation and entertainment

Example:

{
  "id": "expenses-1",
  "simple_basic_expense": 3000,
  "use_detailed_basic_expense": false,
  "primary_residence": 2500,
  "phone_internet_media": 200,
  "food_and_groceries": 800,
  "transport": 400,
  "utilities": 300,
  "clothing": 150,
  "medical": 100,
  "education": 200,
  "childcare": 500,
  "insurance": 150,
  "recreation": 300
}

Home Loan Security Links

Links loans to their security properties.

Field	Type	Required	Description
home_loan_id	string	Yes	ID of the home loan
security_id	string	Yes	ID of the security property

Example:

{
  "home_loan_id": "loan-1",
  "security_id": "property-1"
}

Additional Info

Additional configuration and flags for the scenario.

Field	Type	Required	Description
useDependantAges	boolean	Yes	Whether to use specific dependent ages in calculations

Example:

{
  "useDependantAges": false
}

Complete Example

Here’s a complete minimal scenario for a single applicant purchasing their first home:

{
  "households": [{
    "id": "h1",
    "status": "single",
    "num_adults": 1,
    "num_dependants": 0,
    "postcode": 2000,
    "shared_with_households": []
  }],
  "income": [{
    "id": "i1",
    "which_household": 0,
    "name": "Primary Job",
    "payg": 95000,
    "casual": 0,
    "commission": 0,
    "overtime": 0,
    "bonus": 0,
    "allowances": 0,
    "superannuation_income": 0,
    "centrelink": 0,
    "child_support_received": 0,
    "other_income": 0
  }],
  "securities": [{
    "id": "s1",
    "address": "10 Example St, Sydney NSW 2000",
    "postcode": "2000",
    "transaction_type": "purchasing",
    "applicant_ownership": [100],
    "value": 750000,
    "property_type": "unit",
    "property_purpose": "owner_occupied",
    "weekly_rental_income": 0,
    "monthly_rental_expense": 0
  }],
  "home_loans": [{
    "id": "l1",
    "product_type": "variable_package",
    "existing_or_proposed": "proposed",
    "loan_type": "owner_occupied",
    "lvr": 80,
    "loan_amount": 600000,
    "term": 30,
    "interest_only_period": 0,
    "lvr_behavior": "use-input"
  }],
  "liabilities": [],
  "living_expenses": [{
    "id": "e1",
    "simple_basic_expense": 2500,
    "use_detailed_basic_expense": false,
    "primary_residence": 0,
    "phone_internet_media": 150,
    "food_and_groceries": 500,
    "transport": 200,
    "utilities": 200,
    "clothing": 100,
    "medical": 50,
    "education": 0,
    "childcare": 0,
    "insurance": 100,
    "recreation": 200
  }],
  "rental_income": [],
  "self_employed_income": [],
  "home_loan_security_links": [{
    "home_loan_id": "l1",
    "security_id": "s1"
  }],
  "additional_info": {
    "useDependantAges": false
  }
}

Validation Rules

Household Validation

• num_adults must be 1 or 2
• num_dependants must be non-negative
• postcode must be between 1000-9999 (Australian postcodes)
• For couples, num_adults should be 2

Income Validation

• All income values must be non-negative
• which_household must reference valid household index
• At least one income field should be greater than 0 for realistic scenarios

Property Validation

• value must be greater than 0
• applicant_ownership percentages must sum to 100
• If property_purpose is 'investment', should have weekly_rental_income greater than 0

Loan Validation

• loan_amount must be greater than 0
• lvr must be between 0-100
• term typically 1-30 years
• interest_only_period must not exceed term
• Loan should be linked to a security via home_loan_security_links

Expense Validation

• All expense values must be non-negative
• If use_detailed_basic_expense is true, detailed fields override simple_basic_expense

Common Patterns

Multiple Applicants (Couple)

{
  "households": [{
    "id": "h1",
    "status": "couple",
    "num_adults": 2,
    "num_dependants": 1,
    "postcode": 2000,
    "shared_with_households": []
  }],
  "income": [
    {
      "id": "i1",
      "which_household": 0,
      "name": "Applicant 1",
      "payg": 95000,
      // ... other fields
    },
    {
      "id": "i2",
      "which_household": 0,
      "name": "Applicant 2",
      "payg": 75000,
      // ... other fields
    }
  ]
}

Investment Property

{
  "securities": [{
    "id": "s1",
    "address": "5 Investment Ave, Melbourne VIC 3000",
    "postcode": "3000",
    "transaction_type": "purchasing",
    "applicant_ownership": [100],
    "value": 600000,
    "property_type": "unit",
    "property_purpose": "investment",
    "rental_type": "residential",
    "weekly_rental_income": 550,
    "monthly_rental_expense": 400
  }]
}

Refinancing Existing Loan

{
  "securities": [{
    "transaction_type": "refinancing",
    // ... other fields
  }],
  "home_loans": [{
    "existing_or_proposed": "existing",
    "loan_amount": 450000,
    // ... other fields
  }]
}

Next Steps

• View servicing result schema - Understand calculation outputs
• Create scenario endpoint - Use this schema to create scenarios
• Update scenario endpoint - Modify existing scenarios

---

Last updated: 2025-11-03