VFDS v1.0

Overview

VFDS defines the portable data format for household financial sovereignty and trust lifecycle data. It is a domain specialization of VODS (Veydrin Open Data Standard) and inherits its privacy contract, versioning conventions, and export envelope.

VFDS covers the full financial picture of an individual, household, or trust — including cash flow, net worth, debt, wealth holdings, insurance, goals, and the complete trust ownership hierarchy. All data is structured for offline-first, encrypted, local-only storage. No fields assume network connectivity or cloud persistence.

VODS Compliance

A VFDS export is a valid VODS document. The VODS envelope wraps all VFDS content:

{
  "vods_version": "1.0.0",
  "standard": "vfds",
  "standard_version": "1.0.0",
  "exported_at": "2026-03-11T00:00:00Z",
  "app_id": "org.ninthstar.nemorith",
  "app_version": "0.1.0",
  "payload": { /* VFDS root structure */ }
}

Conventions

• C1
  All identifiers are UUIDs (string)
• C2
  All timestamps are ISO 8601 UTC (e.g. 2026-03-11T14:23:00Z)
• C3
  All monetary values are double in the smallest expressible unit of the stated currency
• C4
  Currency codes follow ISO 4217 (3-letter, uppercase)
• C5
  ? suffix denotes optional/nullable fields
• C6
  Computed fields are derived at runtime and must not be persisted in exports
• C7
  Enum values are lowercase snake_case strings

Root Structure

{
  "vfds_version": "1.0.0",
  "exported_at": "<ISO 8601>",
  "app_version": "<string>",
  "vault": { },
  "flow": { },
  "position": { },
  "debt": { },
  "wealth": { },
  "protection": { },
  "goals": { },
  "milestones": [ ],
  "notifications": [ ],
  "settings": { }
}

Vault

The vault is the root container. All financial data, members, documents, and the ownership tree belong to a vault.

{
  "id": "<uuid>",
  "name": "<string>",
  "tier": "<VaultTier>",
  "base_currency_code": "<ISO 4217>",
  "trust_type": "<TrustType?>",
  "lifecycle_stage": "<LifecycleStage?>",
  "created_at": "<ISO 8601>",
  "updated_at": "<ISO 8601>",
  "members": [ ],
  "role_permissions": [ ],
  "documents": [ ],
  "ownership_entities": [ ]
}

VaultTier

TrustType (trust tier only)

LifecycleStage (trust tier only)

Vault > Members

{
  "id": "<uuid>",
  "name": "<string>",
  "role": "<MemberRole>",
  "joined_at": "<ISO 8601>",
  "avatar_initials": "<string?>",
  "is_owner": false
}

Vault > Role Permissions

Role permissions define what each role can access per layer. Stored per vault to allow customization.

{
  "role": "<MemberRole>",
  "layer_permissions": {
    "flow": "<PermissionLevel>",
    "position": "<PermissionLevel>",
    "debt": "<PermissionLevel>",
    "wealth": "<PermissionLevel>",
    "protection": "<PermissionLevel>",
    "documents": "<PermissionLevel>",
    "milestones": "<PermissionLevel>",
    "members": "<PermissionLevel>",
    "settings": "<PermissionLevel>",
    "trust_lifecycle": "<PermissionLevel>"
  },
  "can_invite_members": false,
  "can_export_data": false,
  "can_initiate_conversion": false,
  "can_trigger_succession": false,
  "can_modify_roles": false
}

PermissionLevel: none | read_only | read_write | admin

Vault > Documents

Encrypted document references. File content is never included in a VFDS export — only metadata. Actual files remain in the encrypted local vault.

{
  "id": "<uuid>",
  "name": "<string>",
  "category": "<DocumentCategory>",
  "size_bytes": 0,
  "notes": "<string?>",
  "added_at": "<ISO 8601>",
  "is_locked": false
}

DocumentCategory: trust_instrument | will_testament | insurance | property_deed | operating_agreement | power_of_attorney | tax_record | other

Vault > Ownership Entities

The ownership map is a self-referential tree. Each entity may have a parent_id pointing to another entity in the same array. Entities with parent_id: null are root nodes. The tree is infinitely nestable.

{
  "id": "<uuid>",
  "name": "<string>",
  "type": "<EntityType>",
  "parent_id": "<uuid?>",
  "value": 0.0,
  "currency_code": "<ISO 4217?>",
  "notes": "<string?>",
  "created_at": "<ISO 8601>"
}

EntityType: trust | llc | brokerage | bank_account | real_estate | vehicle | insurance | retirement_account | crypto | business_interest | personal_property | beneficiary | other

Data Layers

VFDS organizes financial data into seven primary layers beneath the vault container. Each layer is independently versioned within the root structure.

Flow Layer

Cash flow tracking — transactions, budget categories, recurring items, and bill reminders.

Transactions

{
  "id": "<uuid>",
  "description": "<string>",
  "amount": 0.0,
  "currency_code": "<ISO 4217>",
  "type": "<TransactionType>",
  "category_id": "<uuid?>",
  "date": "<ISO 8601>",
  "created_at": "<ISO 8601>"
}

TransactionType: income | expense

Budget Categories

{
  "id": "<uuid>",
  "name": "<string>",
  "budgeted": 0.0,
  "spent": 0.0,
  "icon": 0,
  "color": 0
}

Recurring Transactions

{
  "id": "<uuid>",
  "name": "<string>",
  "amount": 0.0,
  "is_income": false,
  "frequency": "<RecurringFrequency>",
  "category": "<string>",
  "next_due_date": "<ISO 8601>",
  "is_active": true
}

RecurringFrequency: weekly | biweekly | monthly | quarterly | yearly

Bill Reminders

{
  "id": "<uuid>",
  "name": "<string>",
  "amount": 0.0,
  "currency_code": "<ISO 4217>",
  "frequency": "<BillFrequency>",
  "due_day": 1,
  "autopay": false,
  "category": "<string?>",
  "is_active": true,
  "created_at": "<ISO 8601>"
}

BillFrequency: weekly | biweekly | monthly | quarterly | semiannual | annual

Position Layer

Net worth snapshot — assets, liabilities, and historical snapshots.

Assets

{
  "id": "<uuid>",
  "name": "<string>",
  "type": "<AssetType>",
  "value": 0.0,
  "currency_code": "<ISO 4217>",
  "last_updated": "<ISO 8601>"
}

AssetType: cash | savings | investment | retirement | real_estate | vehicle | personal_property | other

Liabilities

{
  "id": "<uuid>",
  "name": "<string>",
  "type": "<LiabilityType>",
  "balance": 0.0,
  "interest_rate": 0.0,
  "minimum_payment": 0.0,
  "currency_code": "<ISO 4217>",
  "last_updated": "<ISO 8601>"
}

LiabilityType: mortgage | auto_loan | student_loan | credit_card | personal_loan | medical_debt | other

Net Worth Snapshots

{
  "id": "<uuid>",
  "net_worth": 0.0,
  "total_assets": 0.0,
  "total_liabilities": 0.0,
  "recorded_at": "<ISO 8601>"
}

Debt Layer

Debt payoff engine — accounts and active strategy selection.

{
  "accounts": [
    {
      "id": "<uuid>",
      "name": "<string>",
      "balance": 0.0,
      "interest_rate": 0.0,
      "minimum_payment": 0.0,
      "currency_code": "<ISO 4217>"
    }
  ],
  "payoff_strategy": "<DebtPayoffStrategy>"
}

DebtPayoffStrategy: avalanche | snowball | custom

Wealth Layer

Portfolio holdings — all asset classes with current valuation.

{
  "id": "<uuid>",
  "name": "<string>",
  "ticker": "<string?>",
  "asset_class": "<AssetClass>",
  "shares": 0.0,
  "price_per_share": 0.0,
  "cost_basis": 0.0,
  "currency_code": "<ISO 4217>"
}

AssetClass: stock | etf | mutual_fund | crypto | bond | real_estate | private_equity | annuity | retirement_account | other

Protection Layer

Insurance policy inventory and coverage gap tracking.

{
  "id": "<uuid>",
  "provider": "<string>",
  "type": "<InsuranceType>",
  "premium": 0.0,
  "premium_frequency": "monthly",
  "coverage_amount": 0.0,
  "deductible": 0.0,
  "renewal_date": "<ISO 8601?>"
}

InsuranceType: health | life | auto | homeowners | renters | umbrella | disability | long_term_care | dental | vision | other

Goals Layer

Financial goals with progress tracking.

{
  "id": "<uuid>",
  "name": "<string>",
  "target_amount": 0.0,
  "current_amount": 0.0,
  "category": "<GoalCategory>",
  "deadline": "<ISO 8601?>",
  "created_at": "<ISO 8601>",
  "is_completed": false
}

GoalCategory: emergency | house | retirement | education | vehicle | travel | custom

Milestones

Cross-layer milestone records. May reference net worth targets, savings goals, or lifecycle events.

{
  "id": "<uuid>",
  "title": "<string>",
  "description": "<string>",
  "target_amount": 0.0,
  "current_amount": 0.0,
  "target_date": "<ISO 8601?>",
  "status": "<MilestoneStatus>",
  "currency_code": "<ISO 4217>"
}

MilestoneStatus: upcoming | in_progress | achieved

Notifications / Audit Log

Activity log and in-app notification records.

{
  "id": "<uuid>",
  "title": "<string>",
  "body": "<string>",
  "type": "<NotificationType>",
  "created_at": "<ISO 8601>",
  "is_read": false,
  "route": "<string?>"
}

NotificationType: info | warning | milestone | security | sync

Settings

App-level preferences. Exported for cross-device restore. Not vault-specific.

Cross-References

Currency Reference

Static reference data. Not user data — not exported in VFDS payloads. Embedded in app.

Document Bundle Format (.vfds-bundle)

A standard VFDS export (vfds.json) contains document metadata only — file contents are never embedded in the JSON payload. For full backup, restore, and migration including actual document files, implementations must produce a VFDS Bundle.

Structure

bundle_manifest.json

{
  "bundle_version": "1.0.0",
  "vfds_version": "1.0.0",
  "created_at": "<ISO 8601>",
  "vault_id": "<uuid>",
  "vault_name": "<string>",
  "document_count": 0,
  "total_encrypted_bytes": 0,
  "encryption": {
    "algorithm": "AES-256-GCM",
    "kdf": "PBKDF2-SHA512",
    "iterations": 310000,
    "salt": "<base64>",
    "iv_per_file": true
  }
}

File Encryption

Each document is encrypted independently:

The encryption key is derived from a user-supplied passphrase via PBKDF2-SHA512 using the salt stored in bundle_manifest.json. The same key covers all files in the bundle. The passphrase is never stored.

Import / Restore Rules

• I1
  Validate document count. bundle_manifest.document_count must match the number of .enc files present — abort if mismatch.
• I2
  Parse before import. Validate vfds.json against the declared vfds_version before importing any data.
• I3
  Decrypt with verification. Decrypt each .enc file using the passphrase-derived key — if any file fails GCM tag verification, abort the entire import and surface the error.
• I4
  Match by UUID. Match each decrypted file to its corresponding vault.documents record by UUID.
• I5
  Warn on partial export. Warn the user if vault.documents references UUIDs with no corresponding .enc file.
• I6
  Never silently drop documents. Surface every mismatch to the user.

Suggested UX Labels

Privacy Notes

• P1
  No document contents in exports. Document file contents are never included in VFDS exports — only metadata.
• P2
  PII sensitivity. Member names and financial values are sensitive PII — exports must be encrypted in transit and at rest.
• P3
  No silent transmission. VFDS exports must not be sent to any server without explicit user action.
• P4
  No computed field persistence. Computed fields are derived at runtime and must not be persisted or exported.
• P5
  VODS privacy contract. This standard inherits the VODS privacy contract in full.

Versioning

VFDS follows semantic versioning:

Implementations must store the vfds_version on export and validate it on import. Unknown fields should be preserved, not discarded, to support forward compatibility.

Totals (v1.0.0)