Add transaction link schema and related functionality; update examples and tests

jwaspin · jwaspin · commit 592107b4380a · 2026-04-04T22:54:25.000-06:00
diff --git a/README.md b/README.md
@@ -210,6 +210,24 @@ const transactionSplit = {
 };
 ```
 
+### TransactionLink
+
+Validates links between related transactions, such as transfers recorded in separate accounts.
+
+```typescript
+const transactionLink = {
+  id: string;
+  sourceTransactionId: string;
+  destinationTransactionId: string;
+  createdAt: string;
+  updatedAt: string | null;
+  deletedAt?: string | null;
+  version?: number;
+};
+```
+
+Cross-transaction rules like matching dates, matching amounts, or opposite signs are not enforced by this schema and should be handled in application logic.
+
 ### LucaSchema
 
 Validates the full ledger export.
@@ -223,6 +241,7 @@ const lucaSchema = {
   recurringTransactions: RecurringTransaction[];
   recurringTransactionEvents: RecurringTransactionEvent[];
   transactions: Transaction[];
+  transactionLinks?: TransactionLink[];
   transactionSplits: TransactionSplit[];
 };
 ```
@@ -251,7 +270,7 @@ import {
 - `validate(schemaKey, data)` → `{ valid: boolean, errors: AjvError[] }`
 - `validateCollection(schemaKey, array)` → `{ valid: boolean, errors: [{ index, entity, errors }] }`
 - `getDateFieldPaths(schemaKey)` → `string[]` of `format: date` fields for a schema key
-- `getDateFieldPathsByCollection()` → `{ accounts, categories, statements, recurringTransactions, recurringTransactionEvents, transactions, transactionSplits }`
+- `getDateFieldPathsByCollection()` → `{ accounts, categories, statements, recurringTransactions, recurringTransactionEvents, transactions, transactionLinks, transactionSplits }`
 - `getValidFields(schemaKey)` → `Set<string>` of all fields (includes common fields when applicable)
 - `getRequiredFields(schemaKey)` → `Set<string>` of required fields (includes common required fields)
 - `stripInvalidFields(schemaKey, data)` → new object with only schema-defined keys
diff --git a/examples/README.md b/examples/README.md
@@ -19,6 +19,7 @@ This file is a complete, valid Luca Schema document. It is intended to:
 - **Recurring transactions**: Multiple frequencies and states.
 - **Recurring transaction events**: Modified and deleted occurrences.
 - **Transactions**: A mix of states and categories, some linked to statements.
+- **Transaction links**: Related transaction pairs used to model transfers across accounts.
 - **Transaction splits**: One split transaction showing sums that match the parent.
 
 ### Data characteristics
diff --git a/examples/luca-schema-example.json b/examples/luca-schema-example.json
@@ -660,6 +660,24 @@
       "createdAt": "2024-02-01T00:00:00Z",
       "updatedAt": null
     },
+    {
+      "id": "75b5faeb-acde-4c4c-8401-0bf2c4f1e9d1",
+      "accountId": "cf9df9b9-9fc0-424b-a137-47e9ba144c73",
+      "date": "2024-02-01",
+      "authorizedAt": null,
+      "postedAt": "2024-02-01T00:00:00Z",
+      "currency": "USD",
+      "amount": -100000,
+      "description": "Transfer to High Yield Savings",
+      "memo": "Monthly savings transfer",
+      "categoryId": null,
+      "statementId": null,
+      "aggregationServiceId": "plaid_txn_016b",
+      "transactionState": "COMPLETED",
+      "deletedAt": null,
+      "createdAt": "2024-02-01T00:00:00Z",
+      "updatedAt": null
+    },
     {
       "id": "e2984e2a-baa9-4240-ae84-9794cfe96620",
       "accountId": "c5742bfc-835e-4baa-8e1c-71afba58297f",
@@ -733,6 +751,15 @@
       "updatedAt": "2024-03-12T10:00:00Z"
     }
   ],
+  "transactionLinks": [
+    {
+      "id": "d6ae6cc3-5949-4bb2-8187-d1be36df94a1",
+      "sourceTransactionId": "75b5faeb-acde-4c4c-8401-0bf2c4f1e9d1",
+      "destinationTransactionId": "08bfed71-ab12-4898-ac9c-f2980eefa945",
+      "createdAt": "2024-02-01T00:05:00Z",
+      "updatedAt": null
+    }
+  ],
   "transactionSplits": [
     {
       "id": "fbc07cc4-1ade-442c-962f-b893b599a16d",
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@luca-financial/luca-schema",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Schemas for the Luca Ledger application",
   "author": "Johnathan Aspinwall",
   "main": "dist/esm/index.js",
diff --git a/src/examples/lucaSchema.json b/src/examples/lucaSchema.json
@@ -99,6 +99,39 @@
       "transactionState": "SCHEDULED",
       "createdAt": "2024-01-10T00:00:00Z",
       "updatedAt": "2024-01-15T00:00:00Z"
+    },
+    {
+      "id": "10000000-0000-0000-0000-000000000004",
+      "accountId": "00000000-0000-0000-0000-000000000001",
+      "categoryId": null,
+      "statementId": null,
+      "amount": -5000,
+      "date": "2024-01-12",
+      "description": "ATM cash withdrawal",
+      "transactionState": "COMPLETED",
+      "createdAt": "2024-01-12T09:00:00Z",
+      "updatedAt": "2024-01-12T09:00:00Z"
+    },
+    {
+      "id": "10000000-0000-0000-0000-000000000005",
+      "accountId": "00000000-0000-0000-0000-000000000005",
+      "categoryId": null,
+      "statementId": null,
+      "amount": 5000,
+      "date": "2024-01-12",
+      "description": "Cash from Main Street Bank",
+      "transactionState": "COMPLETED",
+      "createdAt": "2024-01-12T09:05:00Z",
+      "updatedAt": "2024-01-12T09:05:00Z"
+    }
+  ],
+  "transactionLinks": [
+    {
+      "id": "12000000-0000-0000-0000-000000000001",
+      "sourceTransactionId": "10000000-0000-0000-0000-000000000004",
+      "destinationTransactionId": "10000000-0000-0000-0000-000000000005",
+      "createdAt": "2024-01-12T09:05:00Z",
+      "updatedAt": null
     }
   ],
   "transactionSplits": []
diff --git a/src/examples/transactionLinks.json b/src/examples/transactionLinks.json
@@ -0,0 +1,9 @@
+[
+  {
+    "id": "12000000-0000-0000-0000-000000000001",
+    "sourceTransactionId": "10000000-0000-0000-0000-000000000011",
+    "destinationTransactionId": "10000000-0000-0000-0000-000000000012",
+    "createdAt": "2024-03-05T10:05:00Z",
+    "updatedAt": null
+  }
+]
diff --git a/src/examples/transactions.json b/src/examples/transactions.json
@@ -118,5 +118,29 @@
     "transactionState": "COMPLETED",
     "createdAt": "2024-02-20T00:00:00Z",
     "updatedAt": "2024-03-01T00:00:00Z"
+  },
+  {
+    "id": "10000000-0000-0000-0000-000000000011",
+    "accountId": "00000000-0000-0000-0000-000000000001",
+    "categoryId": null,
+    "statementId": null,
+    "amount": -25000,
+    "date": "2024-03-05",
+    "description": "Transfer to High-Yield Savings",
+    "transactionState": "COMPLETED",
+    "createdAt": "2024-03-05T10:00:00Z",
+    "updatedAt": "2024-03-05T10:00:00Z"
+  },
+  {
+    "id": "10000000-0000-0000-0000-000000000012",
+    "accountId": "00000000-0000-0000-0000-000000000002",
+    "categoryId": null,
+    "statementId": null,
+    "amount": 25000,
+    "date": "2024-03-05",
+    "description": "Transfer from Everyday Checking",
+    "transactionState": "COMPLETED",
+    "createdAt": "2024-03-05T10:05:00Z",
+    "updatedAt": "2024-03-05T10:05:00Z"
   }
 ]
diff --git a/src/index.js b/src/index.js
@@ -8,6 +8,7 @@ import {
   recurringTransactionEvent,
   statement,
   transaction,
+  transactionLink,
   transactionSplit
 } from './schemas/index.js';
 import { enums, LucaSchemas } from './enums.js';
@@ -30,6 +31,7 @@ const schemas = {
   recurringTransaction,
   recurringTransactionEvent,
   transaction,
+  transactionLink,
   transactionSplit,
   enums: enumsSchema
 };
@@ -43,6 +45,7 @@ export const recurringTransactionSchema = schemas.recurringTransaction;
 export const recurringTransactionEventSchema =
   schemas.recurringTransactionEvent;
 export const transactionSchema = schemas.transaction;
+export const transactionLinkSchema = schemas.transactionLink;
 export const transactionSplitSchema = schemas.transactionSplit;
 
 export {
diff --git a/src/lucaValidator.js b/src/lucaValidator.js
@@ -9,6 +9,7 @@ import statementSchemaJson from './schemas/statement.json' with { type: 'json' }
 import recurringTransactionSchemaJson from './schemas/recurringTransaction.json' with { type: 'json' };
 import recurringTransactionEventSchemaJson from './schemas/recurringTransactionEvent.json' with { type: 'json' };
 import transactionSchemaJson from './schemas/transaction.json' with { type: 'json' };
+import transactionLinkSchemaJson from './schemas/transactionLink.json' with { type: 'json' };
 import transactionSplitSchemaJson from './schemas/transactionSplit.json' with { type: 'json' };
 
 const schemas = {
@@ -19,6 +20,7 @@ const schemas = {
   recurringTransaction: recurringTransactionSchemaJson,
   recurringTransactionEvent: recurringTransactionEventSchemaJson,
   transaction: transactionSchemaJson,
+  transactionLink: transactionLinkSchemaJson,
   transactionSplit: transactionSplitSchemaJson
 };
 
@@ -193,6 +195,7 @@ export function getDateFieldPaths(schemaKey) {
  *   recurringTransactions: Array<string>,
  *   recurringTransactionEvents: Array<string>,
  *   transactions: Array<string>,
+ *   transactionLinks: Array<string>,
  *   transactionSplits: Array<string>
  * }}
  */
@@ -204,6 +207,7 @@ export function getDateFieldPathsByCollection() {
     recurringTransactions: getDateFieldPaths('recurringTransaction'),
     recurringTransactionEvents: getDateFieldPaths('recurringTransactionEvent'),
     transactions: getDateFieldPaths('transaction'),
+    transactionLinks: getDateFieldPaths('transactionLink'),
     transactionSplits: getDateFieldPaths('transactionSplit')
   };
 }
diff --git a/src/schemas/enums.json b/src/schemas/enums.json
@@ -11,6 +11,7 @@
     "RECURRING_TRANSACTION": "recurringTransaction",
     "RECURRING_TRANSACTION_EVENT": "recurringTransactionEvent",
     "TRANSACTION": "transaction",
+    "TRANSACTION_LINK": "transactionLink",
     "TRANSACTION_SPLIT": "transactionSplit"
   },
   "$defs": {
diff --git a/src/schemas/index.js b/src/schemas/index.js
@@ -6,6 +6,7 @@ import statement from './statement.json' with { type: 'json' };
 import recurringTransaction from './recurringTransaction.json' with { type: 'json' };
 import recurringTransactionEvent from './recurringTransactionEvent.json' with { type: 'json' };
 import transaction from './transaction.json' with { type: 'json' };
+import transactionLink from './transactionLink.json' with { type: 'json' };
 import transactionSplit from './transactionSplit.json' with { type: 'json' };
 import enums from './enums.json' with { type: 'json' };
 
@@ -18,6 +19,7 @@ export {
   recurringTransaction,
   recurringTransactionEvent,
   transaction,
+  transactionLink,
   transactionSplit,
   enums
 };
@@ -31,6 +33,7 @@ export default {
   recurringTransaction,
   recurringTransactionEvent,
   transaction,
+  transactionLink,
   transactionSplit,
   enums
 };
diff --git a/src/schemas/lucaSchema.json b/src/schemas/lucaSchema.json
@@ -68,6 +68,14 @@
         "$ref": "./transaction.json"
       }
     },
+    "transactionLinks": {
+      "type": "array",
+      "description": "List of links between related transactions",
+      "uniqueItems": true,
+      "items": {
+        "$ref": "./transactionLink.json"
+      }
+    },
     "transactionSplits": {
       "type": "array",
       "description": "List of transaction splits",
diff --git a/src/schemas/transactionLink.json b/src/schemas/transactionLink.json
@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/LucaFinancial/LucaSchema/main/src/schemas/transactionLink.json",
+  "title": "Transaction Link",
+  "description": "Links two related transactions, such as transfer legs recorded in separate accounts.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "./common.json"
+    }
+  ],
+  "properties": {
+    "sourceTransactionId": {
+      "type": "string",
+      "title": "Source Transaction ID",
+      "format": "uuid",
+      "description": "UUID of the source transaction in the link."
+    },
+    "destinationTransactionId": {
+      "type": "string",
+      "title": "Destination Transaction ID",
+      "format": "uuid",
+      "description": "UUID of the destination transaction in the link."
+    }
+  },
+  "unevaluatedProperties": false,
+  "required": ["sourceTransactionId", "destinationTransactionId"]
+}
diff --git a/src/tests/exampleFile.test.js b/src/tests/exampleFile.test.js
@@ -15,7 +15,7 @@ describe('luca-schema-example.json', () => {
   });
 
   test('example file contains all entity types', () => {
-    // Verify all required arrays are present and non-empty
+    // Verify the example includes all supported collections
     expect(exampleData.categories).toBeDefined();
     expect(exampleData.categories.length).toBeGreaterThan(0);
 
@@ -34,6 +34,9 @@ describe('luca-schema-example.json', () => {
     expect(exampleData.transactions).toBeDefined();
     expect(exampleData.transactions.length).toBeGreaterThan(0);
 
+    expect(exampleData.transactionLinks).toBeDefined();
+    expect(exampleData.transactionLinks.length).toBeGreaterThan(0);
+
     expect(exampleData.transactionSplits).toBeDefined();
     expect(exampleData.transactionSplits.length).toBeGreaterThan(0);
   });
@@ -43,6 +46,9 @@ describe('luca-schema-example.json', () => {
     const accountIds = new Set(exampleData.accounts.map(a => a.id));
     const categoryIds = new Set(exampleData.categories.map(c => c.id));
     const transactionIds = new Set(exampleData.transactions.map(t => t.id));
+    const transactionById = new Map(
+      exampleData.transactions.map(t => [t.id, t])
+    );
     const statementIds = new Set(exampleData.statements.map(s => s.id));
     const recurringTransactionIds = new Set(
       exampleData.recurringTransactions.map(r => r.id)
@@ -64,6 +70,16 @@ describe('luca-schema-example.json', () => {
       }
     });
 
+    // Verify transaction links reference valid transactions
+    exampleData.transactionLinks.forEach(link => {
+      expect(transactionIds.has(link.sourceTransactionId)).toBe(true);
+      expect(transactionIds.has(link.destinationTransactionId)).toBe(true);
+      expect(link.sourceTransactionId).not.toBe(link.destinationTransactionId);
+      expect(transactionById.get(link.sourceTransactionId)?.accountId).not.toBe(
+        transactionById.get(link.destinationTransactionId)?.accountId
+      );
+    });
+
     // Verify transaction splits reference valid transactions and categories
     exampleData.transactionSplits.forEach(split => {
       expect(transactionIds.has(split.transactionId)).toBe(true);
diff --git a/src/tests/lucaSchema.test.js b/src/tests/lucaSchema.test.js
diff --git a/src/tests/test-fixtures.js b/src/tests/test-fixtures.js
diff --git a/src/tests/transactionLink.test.js b/src/tests/transactionLink.test.js

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@luca-financial/luca-schema",`
`3`		`- "version": "3.1.0",`
	`3`	`+ "version": "3.2.0",`
`4`	`4`	`"description": "Schemas for the Luca Ledger application",`
`5`	`5`	`"author": "Johnathan Aspinwall",`
`6`	`6`	`"main": "dist/esm/index.js",`