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 fields sit at the root level alongside the VFDS domain fields — the same pattern used by OHDS and OCEADS. VFDS does not use a payload wrapper.

{
  // VODS envelope (required)
  "vods_version": "1.0",
  "export_id":   "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "export_date": "2026-03-11T00:00:00Z",
  "export_mode": "tracked",

  // VFDS root structure
  "vfds_version": "1.0.0",
  "exported_at": "2026-03-11T00:00:00Z",
  "app_version": "0.1.0",
  "vault": { },
  "flow": { },
  "position": { },
  "debt": { },
  "wealth": { },
  "protection": { },
  "goals": { },
  "milestones": [ ],
  "notifications": [ ],
  "settings": { }
}

Annotations (//) are shown for readability. Valid JSON does not permit comments.

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 string decimal representations in the major currency unit (e.g., "10.50" for ten dollars and fifty cents, not 1050). Implementations MUST NOT use floating-point arithmetic for monetary calculations. Fiat currencies MUST preserve at least 2 decimal places; BTC MUST preserve 8. Using strings avoids IEEE 754 precision loss that affects every floating-point number system.
• 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
• C8
  All interest_rate fields are string decimal representations of the annual percentage rate (APR) where "5.25" means 5.25% per year. Not a decimal fraction — "5.25", not "0.0525".

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>",
  "expires_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.00",
  "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.00",
  "currency_code": "<ISO 4217>",
  "type": "<TransactionType>",
  "category_id": "<uuid?>",
  "date": "<ISO 8601>",
  "member_id": "<uuid?>",
  "created_at": "<ISO 8601>"
}

TransactionType: income | expense

Receipts

{
  "id": "<uuid>",
  "image_path": "<string>",
  "captured_at": "<ISO 8601>",
  "amount": "0.00",
  "merchant": "<string?>",
  "category": "<string?>",
  "notes": "<string?>",
  "linked_transaction_id": "<uuid?>",
  "currency_code": "<ISO 4217>",
  "ocr_text": "<string?>"
}

Subscriptions

{
  "id": "<uuid>",
  "name": "<string>",
  "monthly_cost": "0.00",
  "currency_code": "<ISO 4217>",
  "category": "<string?>",
  "frequency": "<RecurringFrequency>",
  "next_due_date": "<ISO 8601?>",
  "icon": "<string?>",
  "is_active": true,
  "created_at": "<ISO 8601>"
}

Donations

{
  "id": "<uuid>",
  "organization": "<string>",
  "amount": "0.00",
  "currency_code": "<ISO 4217>",
  "frequency": "<RecurringFrequency?>",
  "icon": "<string?>",
  "recurring": false,
  "created_at": "<ISO 8601>"
}

Budget Categories

{
  "id": "<uuid>",
  "name": "<string>",
  "budgeted": "0.00",
  "spent": "0.00",
  "rollover": false,
  "currency_code": "<ISO 4217>",
  "icon": "<string?>",
  "color": "<string?>"
}

Recurring Transactions

{
  "id": "<uuid>",
  "name": "<string>",
  "amount": "0.00",
  "currency_code": "<ISO 4217>",
  "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.00",
  "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.00",
  "loan_balance": "0.00",
  "currency_code": "<ISO 4217>",
  "ownership_entity_id": "<uuid?>",
  "last_updated": "<ISO 8601>"
}

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

Liabilities

{
  "id": "<uuid>",
  "name": "<string>",
  "type": "<LiabilityType>",
  "balance": "0.00",
  "interest_rate": "0.00",
  "minimum_payment": "0.00",
  "currency_code": "<ISO 4217>",
  "debt_account_id": "<uuid?>",
  "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.00",
  "total_assets": "0.00",
  "total_liabilities": "0.00",
  "recorded_at": "<ISO 8601>"
}

Debt Layer

Debt payoff engine — accounts and active strategy selection.

{
  "accounts": [
    {
      "id": "<uuid>",
      "name": "<string>",
      "debt_type": "<DebtType>",
      "balance": "0.00",
      "interest_rate": "0.00",
      "minimum_payment": "0.00",
      "credit_limit": "0.00",
      "due_day": 1,
      "is_revolving": false,
      "currency_code": "<ISO 4217>"
    }
  ],
  "payoff_strategy": "<DebtPayoffStrategy>"
}

DebtType: credit_card | mortgage | auto_loan | student_loan | personal_loan | home_equity | medical | business_loan | tax_debt | other

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.00",
  "price_per_share": "0.00",
  "cost_basis": "0.00",
  "currency_code": "<ISO 4217>",
  "ownership_entity_id": "<uuid?>",
  "dividend_per_share": "0.00",
  "dividend_frequency": "<DividendFrequency?>",
  "notes": "<string?>"
}

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

DividendFrequency: monthly | quarterly | semiannual | annual | irregular

Watchlist

{
  "id": "<uuid>",
  "ticker": "<string>",
  "name": "<string>",
  "sector": "<string?>",
  "price_target": "0.00",
  "current_price": "0.00",
  "currency_code": "<ISO 4217>",
  "price_updated_at": "<ISO 8601?>",
  "notes": "<string?>",
  "added_at": "<ISO 8601>"
}

Protection Layer

Insurance policy inventory and coverage gap tracking.

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

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

Beneficiary Designations

{
  "id": "<uuid>",
  "account_name": "<string>",
  "account_type": "<string>",
  "beneficiary": "<string>",
  "allocation": "<string>",
  "tier": "<BeneficiaryTier>",
  "last_reviewed": "<ISO 8601?>",
  "issue": "<string?>",
  "created_at": "<ISO 8601>"
}

BeneficiaryTier: primary | contingent

Goals Layer

Financial goals with progress tracking.

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

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

Life Events

{
  "id": "<uuid>",
  "name": "<string>",
  "target_date": "<ISO 8601?>",
  "estimated_cost": "0.00",
  "current_saved": "0.00",
  "currency_code": "<ISO 4217>",
  "icon": "<string?>",
  "color": "<string?>",
  "active": true,
  "created_at": "<ISO 8601>"
}

Milestones

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

{
  "id": "<uuid>",
  "title": "<string>",
  "description": "<string>",
  "target_amount": "0.00",
  "current_amount": "0.00",
  "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 .vfds-bundle file is a ZIP archive. 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

A machine-readable schema for automated validation is available at vfds-v1.0.schema.json.

• 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.

Conformance Rules

An application claims VFDS v1.0 conformance by satisfying all VODS v1.0 conformance rules (see VODS spec §6) and the following VFDS-specific rules. A machine-readable schema is available at vfds-v1.0.schema.json.

Producer conformance

An application producing VFDS exports MUST satisfy:

• F1
  VFDS version declared. Every export includes vfds_version with the spec version used.
• F2
  VODS envelope present. Every export includes the four required VODS fields (vods_version, export_id, export_date, export_mode) at the root level alongside the VFDS fields.
• F3
  Vault required. Every export includes a non-empty vault object with at minimum id, name, tier, base_currency_code, created_at, and updated_at.
• F4
  Monetary values as strings. All monetary values are serialized as string decimals per C3. No floating-point numbers for money.
• F5
  Interest rates as APR strings. All interest_rate fields are string decimals representing annual percentage rate per C8.
• F6
  No computed fields. Computed values (net worth, gain/loss, percentages, remaining budget) MUST NOT appear in exports per C6.
• F7
  No document contents. Document file contents are never included in the JSON export — only metadata. Actual files go in a .vfds-bundle if needed.
• F8
  Cross-references valid. All UUID references (category_id, ownership_entity_id, debt_account_id, member_id, parent_id) MUST point to records that exist within the same export.
• F9
  Anonymization honoured. In anonymous mode, all member names, vault names, and entity names MUST be redacted or pseudonymized. In tracked mode, stable pseudonyms per VODS §3.

Consumer conformance

An application importing VFDS data MUST satisfy:

• F10
  Version check. Validate vfds_version before processing. Reject documents with an unsupported major version.
• F11
  Unknown fields preserved. Fields not recognized by the consumer SHOULD be preserved on re-export, not silently dropped.
• F12
  Bundle validation. When importing a .vfds-bundle, validate the manifest, verify document count, and verify GCM authentication tags before processing per I1–I6.
• F13
  No silent transmission. Imported data MUST NOT be sent to any server without explicit user action.

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)

Security Considerations

VFDS inherits the security considerations defined in VODS §8. The following are specific to financial data.

Threat model

VFDS documents contain highly sensitive financial information — account balances, debt details, net worth, insurance policies, trust instruments, and estate succession data. Adversaries include unauthorized household members, lost or stolen devices, compromised backup storage, malicious import files, and succession disputes. Implementations MUST treat all VFDS data as confidential by default.

Bundle encryption

The .vfds-bundle format uses AES-256-GCM with PBKDF2-SHA512 key derivation. Implementations SHOULD enforce a minimum passphrase strength (12+ characters or equivalent entropy). Passphrases MUST NOT be stored. The salt and nonce MUST be generated from a cryptographically secure random source.

Authorization enforcement

The role_permissions model defines access levels (none, read, write, admin) per member per layer. These are advisory in the export format — implementations MUST enforce them at the application layer. Exported data MUST NOT include layers the exporting user does not have read access to.

Input validation

Consumers importing VFDS data MUST validate bundle_manifest.json integrity before processing. Free-text fields (description, notes, body) MUST be sanitized before rendering. Implementations SHOULD enforce maximum document counts per bundle and reject bundles exceeding reasonable size limits.

Computed field prohibition

Convention C6 prohibits computed fields in exports. Implementations MUST NOT persist derived values (net worth, loss rates, progress percentages) in exported data — they MUST be recalculated on import.

Glossary

Financial and trust terminology used in this specification. Implementers who are not financial professionals should reference this section when building VFDS-conforming applications.

Normative References

VFDS inherits all normative references from VODS §9. The following additional references apply.

Changelog