# Personal Loan Funded Cost Index data dictionary

Status: draft for protocol 0.4 public-source collections

## Dataset rules

- JSON uses `null` for unknown values. Zero means the source established zero.
- Percentages are stored in percentage points: `8.99` means 8.99%.
- Dollar amounts are stored in dollars unless a field explicitly names another unit.
- Dates use `YYYY-MM-DD`.
- Every reported value links to at least one `source_id` and source locator.
- Brand, platform, creditor, parent, servicer, and funding vehicle remain separate.

## Source register

| Field | Type | Rule |
|---|---|---|
| `source_id` | Text | Stable key; never reused |
| `publisher` | Text | Entity responsible for the source |
| `title` | Text | Source title |
| `source_type` | Controlled text | `official_product_page`, `official_terms`, `sec_filing`, `official_investor_release`, `regulator`, or `other_primary` |
| `url` | URL | Direct source URL |
| `published_date` | Date or null | Date published or filed |
| `effective_date` | Date or null | Date the source says the terms became effective |
| `checked_date` | Date | Verification date |
| `source_locator` | Text | Page, section, table, or line description |
| `supports` | Array | Record types or fields supported |
| `rights_note` | Text | Link/excerpt/archive treatment |
| `quality_status` | Controlled text | `verified`, `conflict_open`, or `discovery_only` |

## Shelf terms

| Field | Type | Rule |
|---|---|---|
| `record_id` | Text | Stable product snapshot key |
| `brand_name` | Text | Consumer-facing brand on snapshot date |
| `product_name` | Text | Exact public product or study label |
| `provider_role` | Controlled text | Direct lender, marketplace, platform, bank, credit union, or mixed |
| `product_class` | Text | Unsecured closed-end personal installment loan |
| `advertised_apr_min` | Number or null | Provider-reported APR floor |
| `advertised_apr_max` | Number or null | Provider-reported APR ceiling |
| `apr_conditions` | Text | Discounts, term, state, and eligibility conditions |
| `origination_fee_min` | Number or null | Percent of face principal |
| `origination_fee_max` | Number or null | Percent of face principal |
| `origination_fee_flat_min` | Number or null | Lowest flat-dollar fee when the provider uses a state-specific flat schedule |
| `origination_fee_flat_max` | Number or null | Highest flat-dollar fee when the provider uses a state-specific flat schedule |
| `fee_name` | Text or null | Provider's term, such as origination or administrative fee |
| `fee_treatment` | Controlled text | Deducted, financed, upfront, variable, none, or unknown |
| `loan_amount_min` | Number or null | Published minimum face amount |
| `loan_amount_max` | Number or null | Published maximum face amount |
| `term_months` | Array or null | Exact options when published |
| `term_months_min` | Number or null | Lowest published term |
| `term_months_max` | Number or null | Highest published term |
| `prepayment_penalty` | Boolean or null | Must be established by source |
| `soft_pull_to_check_rate` | Boolean or null | Initial rate-check treatment |
| `hard_pull_stage` | Text or null | Provider-described stage |
| `direct_pay_available` | Boolean or null | Payment to eligible creditors |
| `geography` | Text | National statement or exact limits |
| `representative_example` | Object or null | Source-provided amount, rate, fee, APR, term, proceeds, and payment |
| `source_ids` | Array | Supporting sources |
| `missing_fields` | Array | Required fields not established |
| `conflict_status` | Controlled text | `none` or `open` |
| `conflict_note` | Text or null | Exact unresolved conflict |
| `limitations` | Array | Record-specific limits |
| `quality_status` | Controlled text | `verified_pilot`, `partial_pilot`, or `hold` |

## Entity crosswalk

| Field | Type | Rule |
|---|---|---|
| `entity_record_id` | Text | Stable dated relationship key |
| `brand_name` | Text | Consumer-facing brand |
| `brand_effective_date` | Date or null | Start of recorded branding when known |
| `former_brand_names` | Array | Names preserved with dates when known |
| `platform_entity` | Text or `varies` or null | Platform or program manager |
| `creditor_entity` | Text or `varies` or null | Legal lender |
| `creditor_rule` | Text | State, product, or offer dependency |
| `parent_entity` | Text or null | Corporate parent |
| `servicer_entity` | Text or `varies` or null | Servicer when established |
| `funding_channels` | Array | Retained, whole-loan, securitization, or other disclosed channels |
| `source_ids` | Array | Supporting sources |
| `limitations` | Array | Unresolved entity boundaries |

## Funded evidence

| Field | Type | Rule |
|---|---|---|
| `funded_record_id` | Text | Stable statistic key |
| `brand_name` | Text | Brand mapped to the reported program |
| `reporting_entity` | Text | Entity making the disclosure |
| `product_scope` | Text | Exact product population |
| `evidence_class` | Controlled text | One of the protocol evidence classes |
| `comparability_class` | Controlled text | `A`, `B`, `C`, or `N` |
| `period_start` | Date or null | Cohort or reporting start |
| `period_end` | Date | Cohort, reporting, or as-of end |
| `publication_date` | Date or null | Filing or disclosure date when established |
| `loan_count` | Number or null | Source-defined number of loans |
| `origination_volume` | Number or null | Source-defined dollar volume |
| `outstanding_balance` | Number or null | Source-defined balance outstanding at the period end |
| `average_original_balance` | Number or null | Average original amount |
| `average_outstanding_balance` | Number or null | Outstanding balance statistic |
| `rung_derived_average_outstanding_balance` | Number or null | Reproducible Rung calculation from a reported approximate count and balance; never presented as source-reported |
| `weighted_average_borrower_rate` | Number or null | Borrower note rate; never investor yield |
| `weighted_average_apr` | Number or null | Borrower APR |
| `weighted_average_coupon` | Number or null | Portfolio coupon, separately labeled |
| `reported_interest_rate` | Number or null | Regulator-defined portfolio interest-rate field; never presented as borrower APR |
| `weighted_average_term_months` | Number or null | Source-defined term statistic |
| `risk_distribution` | Object or null | Rating, FICO, or other source-defined groups |
| `funding_distribution` | Object or null | Retained, investor, and balance-sheet shares |
| `transaction_note_issuance` | Number or null | Principal amount of transaction notes; never treated as origination volume |
| `eligible_for_cost_comparison` | Boolean | False for mixed or investor-only measures |
| `source_ids` | Array | Supporting sources |
| `limitations` | Array | Scope and comparison warnings |

## Likely borrower credit orientation

| Field | Type | Rule |
|---|---|---|
| `profile_record_id` | Text | Stable program-and-date key |
| `brand_name` | Text | Consumer-facing brand |
| `orientation_category` | Controlled text | `nonprime_center`, `broad_credit_spectrum`, `prime_center`, or `not_established` |
| `reader_label` | Text | Plain-language explanation of the evidence-backed center; never an approval claim |
| `observed_or_stated_center` | Text | Exact conclusion, naming whether it is observed or stated |
| `market_reach` | Text | Breadth or channel context that prevents overreading the category |
| `evidence_type` | Controlled text | Funded distribution or average, transaction/channel evidence, stated market, internal grade, or insufficient evidence |
| `numeric_evidence` | Object or null | Source-defined score, income, grade, or distribution values |
| `evidence_population` | Text or null | Borrowers, balances, pool, channel, or stated market described by the source |
| `period_end` | Date | Evidence as-of or reporting-period end |
| `source_ids` | Array | Supporting sources |
| `confidence` | Controlled text | `high`, `medium`, or `low` under protocol rules |
| `eligibility_inference_prohibited` | Boolean | Always true; the classification cannot predict qualification |
| `limitations` | Array | Distribution, channel, vintage, and interpretation limits |

## State variation matrix

| Field | Type | Rule |
|---|---|---|
| `state_record_id` | Text | Stable brand-and-snapshot key |
| `brand_name` | Text | Consumer-facing brand |
| `availability_status` | Controlled text | Plain classification of how completely the public source establishes jurisdiction coverage |
| `national_baseline` | Text | National offer or the closest published baseline before state rules |
| `included_jurisdictions` | Array or null | Named jurisdictions where the product is available; null means not established |
| `excluded_jurisdictions` | Array or null | Named jurisdictions excluded by the source or derived as the complement of an exact included list |
| `membership_or_relationship_rule` | Text or null | Customer or membership condition that changes access, amount, term, or price |
| `state_specific_rules` | Array | Jurisdiction set, rule type, and source-faithful rule text |
| `source_ids` | Array | Supporting official sources |
| `unknowns` | Array | State fields still not established; an empty array is required when complete |
| `quality_status` | Controlled text | `open`, `partial`, or `verified` |

## State-by-lender comparison

The detailed comparison contains 51 rows per program: the 50 states and District of Columbia. It separates a confirmed answer from a disclosure gap.

| Field | Type | Rule |
|---|---|---|
| `state_comparison_id` | Text | Stable jurisdiction, program, and snapshot key |
| `jurisdiction_code` | Text | Two-letter state code or `DC` |
| `jurisdiction_name` | Text | Display name |
| `availability_status` | Controlled text | `confirmed_available`, `confirmed_unavailable`, `named_state_rule_availability_not_established`, or `not_established` |
| `availability_basis` | Text | Plain explanation of the evidence threshold used for the status |
| `complete_public_availability_map` | Boolean | True only when an official source accounts for all 51 jurisdictions |
| `national_*` | Number or null | Shelf APR, fee, and amount fields shown for context; never silently treated as a state quote |
| `state_amount_min_override` | Number or null | Published state minimum that replaces the national minimum |
| `state_amount_max_override` | Number or null | Published state maximum that replaces the national maximum |
| `membership_or_relationship_rule` | Text or null | Access rule that applies before state-specific underwriting |
| `named_state_variation` | Boolean | True when at least one rule names the jurisdiction |
| `state_rule_types` | Array | Types of rules that name the jurisdiction |
| `state_rule_summary` | Array | Source-faithful rule text for the jurisdiction |
| `general_variation_notes` | Array | Published variation that is known to exist but not mapped to named states |
| `source_ids` | Array | Official sources supporting the state record |
| `uncertainty_note` | Text or null | Public fields still not established |

## Scenario fields

| Field | Type | Rule |
|---|---|---|
| `scenario_id` | Text | Stable formula-output key |
| `brand_name` | Text | Provider whose public fee structure supplies the input |
| `target_cash` | Number | Desired cash after a deducted fee |
| `fee_rate` | Number | Percentage-point input |
| `fee_basis` | Controlled text | Range minimum, midpoint, maximum, representative example, no-fee variant, or the same basis suffixed for a deducted/optional-deduction variant |
| `face_amount_required` | Number or null | `target_cash / (1 - fee_rate / 100)` |
| `fee_dollars` | Number or null | Required face amount less target cash |
| `cash_delivered_ratio` | Number | `1 - fee_rate / 100` |
| `within_published_amount_range` | Boolean or null | Whether rounded face amount fits the public range; null when either published bound is unknown |
| `unavailable_reason` | Text or null | Reason the target cannot be delivered under published limits |
| `source_ids` | Array | Fee and amount evidence |
| `calculation_id` | Text | Formula version |

## Quality fields

Each dataset also carries `schema_version`, `dataset_version`, `status`, `checked_date`, `protocol_version`, and a top-level limitations list. Released calculations require a separate independent-check record.