Add isSameSign flag to transaction and recurring transaction links

- Introduced `isSameSign` boolean flag to indicate whether linked amounts should share the same sign or use opposite signs.
- Updated related schemas, examples, and tests to reflect the new flag.
- Enhanced validation tests to ensure proper handling of the `isSameSign` property.

Author: jwaspin

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.1] - 2026-04-05
+
+### Changed
+
+- Require `isSameSign` on both `transactionLink` and `recurringTransactionLink` so linked amounts can explicitly indicate same-sign versus opposite-sign matching behavior.
+- Update bundled examples, fixtures, tests, and README documentation to reflect the new required link-sign behavior flag.
+
 ## [3.3.0] - 2026-04-05
 
 ### Added

README.md

@@ -219,6 +219,7 @@ const recurringTransactionLink = {
   id: string;
   sourceRecurringTransactionId: string;
   destinationRecurringTransactionId: string;
+  isSameSign: boolean;
   createdAt: string;
   updatedAt: string | null;
   deletedAt?: string | null;
@@ -235,14 +236,15 @@ const transactionLink = {
   id: string;
   sourceTransactionId: string;
   destinationTransactionId: string;
+  isSameSign: boolean;
   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.
+`isSameSign` indicates whether linked amounts should share the same sign (`true`) or use opposite signs (`false`) while still matching by absolute value. Cross-transaction rules like matching dates or verifying absolute-value equality are not enforced by this schema and should be handled in application logic.
 
 ### LucaSchema
 

examples/luca-schema-example.json

@@ -406,6 +406,7 @@
       "id": "54b10a24-6511-48c2-bf3c-1cc7a794e2ab",
       "sourceRecurringTransactionId": "be4ac69f-89d0-444d-bf22-d4d8ec1b34a8",
       "destinationRecurringTransactionId": "37017f0d-8b46-47eb-929a-28e98ba9f84a",
+      "isSameSign": false,
       "createdAt": "2024-01-01T00:05:00Z",
       "updatedAt": null
     }
@@ -795,6 +796,7 @@
       "id": "d6ae6cc3-5949-4bb2-8187-d1be36df94a1",
       "sourceTransactionId": "75b5faeb-acde-4c4c-8401-0bf2c4f1e9d1",
       "destinationTransactionId": "08bfed71-ab12-4898-ac9c-f2980eefa945",
+      "isSameSign": false,
       "createdAt": "2024-02-01T00:05:00Z",
       "updatedAt": null
     }

src/examples/lucaSchema.json

@@ -99,6 +99,7 @@
       "id": "42000000-0000-0000-0000-000000000001",
       "sourceRecurringTransactionId": "40000000-0000-0000-0000-000000000011",
       "destinationRecurringTransactionId": "40000000-0000-0000-0000-000000000012",
+      "isSameSign": false,
       "createdAt": "2024-01-10T00:05:00Z",
       "updatedAt": null
     }
@@ -170,6 +171,7 @@
       "id": "12000000-0000-0000-0000-000000000001",
       "sourceTransactionId": "10000000-0000-0000-0000-000000000004",
       "destinationTransactionId": "10000000-0000-0000-0000-000000000005",
+      "isSameSign": false,
       "createdAt": "2024-01-12T09:05:00Z",
       "updatedAt": null
     }

src/examples/recurringTransactionLinks.json

@@ -3,6 +3,7 @@
     "id": "42000000-0000-0000-0000-000000000001",
     "sourceRecurringTransactionId": "40000000-0000-0000-0000-000000000011",
     "destinationRecurringTransactionId": "40000000-0000-0000-0000-000000000012",
+    "isSameSign": false,
     "createdAt": "2024-03-01T09:00:00Z",
     "updatedAt": null
   }

src/examples/transactionLinks.json

@@ -3,6 +3,7 @@
     "id": "12000000-0000-0000-0000-000000000001",
     "sourceTransactionId": "10000000-0000-0000-0000-000000000011",
     "destinationTransactionId": "10000000-0000-0000-0000-000000000012",
+    "isSameSign": false,
     "createdAt": "2024-03-05T10:05:00Z",
     "updatedAt": null
   }

src/schemas/recurringTransactionLink.json

@@ -21,11 +21,17 @@
       "title": "Destination Recurring Transaction ID",
       "format": "uuid",
       "description": "UUID of the destination recurring transaction in the link."
+    },
+    "isSameSign": {
+      "type": "boolean",
+      "title": "Is Same Sign",
+      "description": "Whether the linked recurring transactions are expected to have matching signs. When false, the linked recurring transactions are expected to have opposite signs."
     }
   },
   "unevaluatedProperties": false,
   "required": [
     "sourceRecurringTransactionId",
-    "destinationRecurringTransactionId"
+    "destinationRecurringTransactionId",
+    "isSameSign"
   ]
 }

src/schemas/transactionLink.json

@@ -21,8 +21,13 @@
       "title": "Destination Transaction ID",
       "format": "uuid",
       "description": "UUID of the destination transaction in the link."
+    },
+    "isSameSign": {
+      "type": "boolean",
+      "title": "Is Same Sign",
+      "description": "Whether the linked transactions are expected to have matching signs. When false, the linked transactions are expected to have opposite signs."
     }
   },
   "unevaluatedProperties": false,
-  "required": ["sourceTransactionId", "destinationTransactionId"]
+  "required": ["sourceTransactionId", "destinationTransactionId", "isSameSign"]
 }

src/tests/recurringTransactionLink.test.js

@@ -22,6 +22,27 @@ describe('recurringTransactionLink schema', () => {
     );
   });
 
+  test('missing isSameSign is invalid', () => {
+    const recurringTransactionLink = makeRecurringTransactionLink();
+    delete recurringTransactionLink.isSameSign;
+    expectInvalid(
+      validate,
+      'recurringTransactionLink',
+      recurringTransactionLink
+    );
+  });
+
+  test('non-boolean isSameSign is invalid', () => {
+    const recurringTransactionLink = makeRecurringTransactionLink({
+      isSameSign: 'false'
+    });
+    expectInvalid(
+      validate,
+      'recurringTransactionLink',
+      recurringTransactionLink
+    );
+  });
+
   test('unknown fields are invalid', () => {
     const recurringTransactionLink = makeRecurringTransactionLink({
       unexpectedField: 'x'

src/tests/test-fixtures.js

@@ -66,7 +66,8 @@ const recurringTransactionLinkTemplate = {
   id: ids.recurringTransactionLinkId,
   ...commonBase,
   sourceRecurringTransactionId: ids.recurringTransactionId,
-  destinationRecurringTransactionId: ids.linkedRecurringTransactionId
+  destinationRecurringTransactionId: ids.linkedRecurringTransactionId,
+  isSameSign: false
 };
 
 const transactionTemplate = {
@@ -101,7 +102,8 @@ const transactionLinkTemplate = {
   id: ids.transactionLinkId,
   ...commonBase,
   sourceTransactionId: ids.transactionId,
-  destinationTransactionId: ids.linkedTransactionId
+  destinationTransactionId: ids.linkedTransactionId,
+  isSameSign: false
 };
 
 const statementTemplate = {