@luca-financial/luca-schema 2.3.4 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.0.0] - 2026-02-13
+
+### Changed
+
+- Enforce strict unknown-field validation across schemas via `unevaluatedProperties: false`.
+- Add date normalization helpers and expose date-specific validation metadata from validator APIs.
+- Expand validator exports for date utilities and schema date-field path discovery.
+- Remove `counterparty` from transaction schema/examples and align fixtures/docs.
+- Update example and test data to match strict schema behavior.
+
+### Breaking
+
+- Payloads containing undeclared properties now fail validation.
+- `counterparty` is no longer accepted on transactions.
+
+### Notes
+
+- During this transition, test fixtures derive `schemaVersion` from package version to keep LucaLedger and LucaSchema on a synchronized `3.x` baseline. Contract-specific schema versioning and enforcement will be addressed in a follow-up cross-repo migration pass.
+
 ## [2.3.4] - 2026-02-06
 
 ### Changed

package/README.md

@@ -84,9 +84,10 @@ const transaction = {
   authorizedAt: string | null;
   postedAt: string | null;
   currency: string | null;
-  amount: number;
+  amount: number; // integer minor units
   date: string;
   description: string;
+  memo: string | null;
   aggregationServiceId: string | null;
   transactionState:
     | 'PLANNED'
@@ -115,7 +116,7 @@ const recurringTransaction = {
   id: string;
   accountId: string;
   categoryId: string | null;
-  amount: number;
+  amount: number; // integer minor units
   description: string;
   frequency: 'DAY' | 'WEEK' | 'MONTH' | 'YEAR';
   interval: number;
@@ -176,10 +177,10 @@ const statement = {
   accountId: string;
   startDate: string;
   endDate: string;
-  startingBalance: number;
-  endingBalance: number;
-  totalCharges: number;
-  totalPayments: number;
+  startingBalance: number; // integer minor units
+  endingBalance: number; // integer minor units
+  totalCharges: number; // integer minor units
+  totalPayments: number; // integer minor units
   isLocked: boolean;
   createdAt: string;
   updatedAt: string | null;
@@ -196,9 +197,10 @@ Validates splits within a transaction.
 const transactionSplit = {
   id: string;
   transactionId: string;
-  amount: number;
+  amount: number; // integer minor units
   categoryId: string | null;
   description: string | null;
+  memo: string | null;
   createdAt: string;
   updatedAt: string | null;
   deletedAt?: string | null;
@@ -231,6 +233,10 @@ This module exports helper utilities to inspect schemas and validate data:
 import {
   validate,
   validateCollection,
+  normalizeDateString,
+  isDateStringFixable,
+  getDateFieldPaths,
+  getDateFieldPathsByCollection,
   getValidFields,
   getRequiredFields,
   stripInvalidFields,
@@ -240,8 +246,12 @@ import {
 } from '@luca-financial/luca-schema';
 ```
 
-- `validate(schemaKey, data)` → `{ valid: boolean, errors: AjvError[] }`
-- `validateCollection(schemaKey, array)` → `{ valid: boolean, errors: [{ index, entity, errors }] }`
+- `validate(schemaKey, data)` → `{ valid: boolean, errors: AjvError[], metadata: { dateFormatIssues, hasFixableDateFormatIssues } }`
+- `validateCollection(schemaKey, array)` → `{ valid: boolean, errors: [{ index, entity, errors, metadata }], metadata: { hasFixableDateFormatIssues } }`
+- `normalizeDateString(value)` → normalized `YYYY-MM-DD` for unambiguous date strings (`YYYY-MM-DD` or `YYYY/MM/DD`), else `null`
+- `isDateStringFixable(value)` → `true` only for unambiguous slash date strings that can be safely normalized
+- `getDateFieldPaths(schemaKey)` → `string[]` of `format: date` fields for a schema key
+- `getDateFieldPathsByCollection()` → `{ accounts, categories, statements, recurringTransactions, recurringTransactionEvents, transactions, 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
@@ -249,6 +259,8 @@ import {
 - `enums` → enum definitions (including `LucaSchemas` keys)
 - `LucaSchemas` → names for schema keys (e.g., `LucaSchemas.TRANSACTION`)
 
+All entity schemas and the top-level `lucaSchema` reject unknown properties.
+
 ## Development
 
 ```bash

package/dist/esm/index.d.ts

@@ -534,6 +534,7 @@ export type Transaction = Common5 & {
   currency?: Currency;
   amount: Amount1;
   description: Description2;
+  memo?: Memo;
   categoryId?: CategoryID1;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID1;
@@ -600,6 +601,10 @@ export type Amount1 = number;
  * Description of the transaction
  */
 export type Description2 = string;
+/**
+ * Optional memo for the transaction.
+ */
+export type Memo = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -620,6 +625,7 @@ export type TransactionSplit = Common6 & {
   amount: Amount2;
   categoryId: CategoryID2;
   description?: Description3;
+  memo?: Memo1;
 };
 /**
  * UUID for the item
@@ -657,6 +663,10 @@ export type CategoryID2 = string | null;
  * Optional description for the split.
  */
 export type Description3 = string | null;
+/**
+ * Optional memo for this split line.
+ */
+export type Memo1 = string | null;
 
 /**
  * Schema for the luca ledger
@@ -1001,6 +1011,7 @@ export type Transaction = Common & {
   currency?: Currency;
   amount: Amount;
   description: Description;
+  memo?: Memo;
   categoryId?: CategoryID;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID;
@@ -1067,6 +1078,10 @@ export type Amount = number;
  * Description of the transaction
  */
 export type Description = string;
+/**
+ * Optional memo for the transaction.
+ */
+export type Memo = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -1099,6 +1114,7 @@ export type TransactionSplit = Common & {
   amount: Amount;
   categoryId: CategoryID;
   description?: Description;
+  memo?: Memo;
 };
 /**
  * UUID for the item
@@ -1136,6 +1152,10 @@ export type CategoryID = string | null;
  * Optional description for the split.
  */
 export type Description = string | null;
+/**
+ * Optional memo for this split line.
+ */
+export type Memo = string | null;
 
 /**
  * Common properties for all schemas

package/dist/esm/index.js

@@ -1,14 +1,39 @@
-import * as schemaIndex from './schemas/index.js';
+import {
+  account,
+  category,
+  common,
+  enums as enumsSchema,
+  lucaSchema as lucaSchemaJson,
+  recurringTransaction,
+  recurringTransactionEvent,
+  statement,
+  transaction,
+  transactionSplit
+} from './schemas/index.js';
 import { enums, LucaSchemas } from './enums.js';
 import {
+  getDateFieldPaths,
+  getDateFieldPathsByCollection,
   getRequiredFields,
   getValidFields,
   stripInvalidFields,
   validate,
   validateCollection
 } from './lucaValidator.js';
+import { isDateStringFixable, normalizeDateString } from './dateUtils.js';
 
-const schemas = { ...schemaIndex, enums: schemaIndex.enums };
+const schemas = {
+  account,
+  category,
+  common,
+  lucaSchema: lucaSchemaJson,
+  statement,
+  recurringTransaction,
+  recurringTransactionEvent,
+  transaction,
+  transactionSplit,
+  enums: enumsSchema
+};
 
 export const accountSchema = schemas.account;
 export const categorySchema = schemas.category;
@@ -26,6 +51,10 @@ export {
   schemas,
   validate,
   validateCollection,
+  normalizeDateString,
+  isDateStringFixable,
+  getDateFieldPaths,
+  getDateFieldPathsByCollection,
   getValidFields,
   getRequiredFields,
   stripInvalidFields

package/dist/esm/lucaValidator.js

@@ -1,5 +1,6 @@
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
+import { isDateStringFixable, normalizeDateString } from './dateUtils.js';
 import accountSchemaJson from './schemas/account.json' with { type: 'json' };
 import categorySchemaJson from './schemas/category.json' with { type: 'json' };
 import commonSchemaJson from './schemas/common.json' with { type: 'json' };
@@ -27,6 +28,7 @@ const supportSchemas = [commonSchemaJson, enumsSchemaJson];
 let sharedAjv;
 const validFieldsCache = new Map();
 const requiredFieldsCache = new Map();
+const dateFieldPathsCache = new Map();
 
 function getValidator() {
   if (sharedAjv) return sharedAjv;
@@ -89,11 +91,111 @@ function isPlainObject(value) {
   return proto === Object.prototype || proto === null;
 }
 
+function decodePointerToken(token) {
+  return token.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+
+function getValueAtInstancePath(data, instancePath) {
+  if (!instancePath) return data;
+  if (typeof instancePath !== 'string' || !instancePath.startsWith('/')) {
+    return undefined;
+  }
+
+  const tokens = instancePath
+    .slice(1)
+    .split('/')
+    .filter(token => token.length > 0)
+    .map(decodePointerToken);
+
+  let current = data;
+  for (const token of tokens) {
+    if (current === null || current === undefined) return undefined;
+    if (Array.isArray(current)) {
+      const index = Number.parseInt(token, 10);
+      if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+        return undefined;
+      }
+      current = current[index];
+      continue;
+    }
+    if (typeof current !== 'object') return undefined;
+    current = current[token];
+  }
+
+  return current;
+}
+
+function createDateFormatIssue(error, data) {
+  const instancePath =
+    typeof error?.instancePath === 'string' ? error.instancePath : '';
+  const value = getValueAtInstancePath(data, instancePath);
+  const normalizedValue = normalizeDateString(value);
+  const fixable = isDateStringFixable(value);
+
+  return {
+    instancePath,
+    schemaPath: typeof error?.schemaPath === 'string' ? error.schemaPath : '',
+    keyword: 'format',
+    format: 'date',
+    value,
+    fixable,
+    normalizedValue: fixable ? normalizedValue : null
+  };
+}
+
+function buildValidationMetadata(errors, data) {
+  const dateFormatIssues = [];
+  for (const error of errors) {
+    if (error?.keyword !== 'format') continue;
+    if (error?.params?.format !== 'date') continue;
+    dateFormatIssues.push(createDateFormatIssue(error, data));
+  }
+
+  return {
+    dateFormatIssues,
+    hasFixableDateFormatIssues: dateFormatIssues.some(issue => issue.fixable)
+  };
+}
+
+function collectDatePathsFromSchemaFragment(schemaFragment, prefix = '') {
+  if (!schemaFragment || typeof schemaFragment !== 'object') return [];
+
+  const paths = [];
+  const properties = isPlainObject(schemaFragment.properties)
+    ? schemaFragment.properties
+    : {};
+
+  for (const [fieldName, fieldSchema] of Object.entries(properties)) {
+    const path = prefix ? `${prefix}.${fieldName}` : fieldName;
+    if (!fieldSchema || typeof fieldSchema !== 'object') continue;
+
+    if (fieldSchema.format === 'date') {
+      paths.push(path);
+    }
+
+    paths.push(...collectDatePathsFromSchemaFragment(fieldSchema, path));
+
+    if (fieldSchema.items && typeof fieldSchema.items === 'object') {
+      const itemPath = `${path}[]`;
+      paths.push(
+        ...collectDatePathsFromSchemaFragment(fieldSchema.items, itemPath)
+      );
+    }
+  }
+
+  return paths;
+}
+
 export function validate(schemaKey, data) {
   const ajv = getValidator();
   const schema = getSchema(schemaKey);
   const isValid = ajv.validate(schema, data);
-  return { valid: isValid, errors: ajv.errors ?? [] };
+  const errors = ajv.errors ?? [];
+  return {
+    valid: isValid,
+    errors,
+    metadata: buildValidationMetadata(errors, data)
+  };
 }
 
 /**
@@ -130,6 +232,50 @@ export function getRequiredFields(schemaKey) {
   return fields;
 }
 
+/**
+ * Returns cached date-format field paths for a schema key.
+ * Paths are dot-delimited and include [] for array item traversal.
+ * @param {string} schemaKey
+ * @returns {Array<string>}
+ */
+export function getDateFieldPaths(schemaKey) {
+  if (dateFieldPathsCache.has(schemaKey)) {
+    return dateFieldPathsCache.get(schemaKey);
+  }
+
+  const schema = getSchema(schemaKey);
+  const paths = collectDatePathsFromSchemaFragment({
+    properties: getSchemaProperties(schema)
+  });
+  const deduped = [...new Set(paths)];
+  dateFieldPathsCache.set(schemaKey, deduped);
+  return deduped;
+}
+
+/**
+ * Returns date-format field paths keyed by collection name.
+ * @returns {{
+ *   accounts: Array<string>,
+ *   categories: Array<string>,
+ *   statements: Array<string>,
+ *   recurringTransactions: Array<string>,
+ *   recurringTransactionEvents: Array<string>,
+ *   transactions: Array<string>,
+ *   transactionSplits: Array<string>
+ * }}
+ */
+export function getDateFieldPathsByCollection() {
+  return {
+    accounts: getDateFieldPaths('account'),
+    categories: getDateFieldPaths('category'),
+    statements: getDateFieldPaths('statement'),
+    recurringTransactions: getDateFieldPaths('recurringTransaction'),
+    recurringTransactionEvents: getDateFieldPaths('recurringTransactionEvent'),
+    transactions: getDateFieldPaths('transaction'),
+    transactionSplits: getDateFieldPaths('transactionSplit')
+  };
+}
+
 /**
  * Returns a new object containing only fields defined in the schema.
  * @param {string} schemaKey
@@ -167,15 +313,25 @@ export function validateCollection(schemaKey, arrayOfEntities) {
   arrayOfEntities.forEach((entity, index) => {
     const isValid = validateFn(entity);
     if (!isValid) {
+      const entityErrors = validateFn.errors ?? [];
       errors.push({
         index,
         entity,
-        errors: validateFn.errors ?? []
+        errors: entityErrors,
+        metadata: buildValidationMetadata(entityErrors, entity)
       });
     }
   });
 
-  return { valid: errors.length === 0, errors };
+  return {
+    valid: errors.length === 0,
+    errors,
+    metadata: {
+      hasFixableDateFormatIssues: errors.some(
+        entityError => entityError.metadata.hasFixableDateFormatIssues
+      )
+    }
+  };
 }
 
 export { schemas };

package/dist/esm/schemas/account.json

@@ -66,5 +66,6 @@
       "description": "Timestamp when the account was closed, if applicable (UTC)."
     }
   },
+  "unevaluatedProperties": false,
   "required": ["name", "type"]
 }

package/dist/esm/schemas/category.json

@@ -34,5 +34,6 @@
       "description": "The identifier of the parent category, if any. Null if the category is top-level. Parents must be top-level (no deeper than two levels; enforced outside JSON Schema)."
     }
   },
+  "unevaluatedProperties": false,
   "required": ["slug", "name", "parentId"]
 }

package/dist/esm/schemas/lucaSchema.json

@@ -75,5 +75,6 @@
         "$ref": "./transactionSplit.json"
       }
     }
-  }
+  },
+  "unevaluatedProperties": false
 }

package/dist/esm/schemas/recurringTransaction.json

@@ -74,6 +74,7 @@
       "description": "Current state of the recurring transaction series."
     }
   },
+  "unevaluatedProperties": false,
   "required": [
     "accountId",
     "categoryId",

package/dist/esm/schemas/recurringTransactionEvent.json

@@ -60,5 +60,6 @@
         "transactionId"
       ]
     }
-  ]
+  ],
+  "unevaluatedProperties": false
 }

package/dist/esm/schemas/statement.json

@@ -57,6 +57,7 @@
       "description": "Whether the statement is locked for editing"
     }
   },
+  "unevaluatedProperties": false,
   "required": [
     "accountId",
     "startDate",

package/dist/esm/schemas/transaction.json

@@ -52,6 +52,11 @@
       "minLength": 1,
       "description": "Description of the transaction"
     },
+    "memo": {
+      "type": ["string", "null"],
+      "title": "Memo",
+      "description": "Optional memo for the transaction."
+    },
     "categoryId": {
       "type": ["string", "null"],
       "title": "Category ID",
@@ -78,5 +83,6 @@
       "description": "The current state of the transaction."
     }
   },
+  "unevaluatedProperties": false,
   "required": ["accountId", "date", "amount", "description", "transactionState"]
 }

package/dist/esm/schemas/transactionSplit.json

@@ -33,7 +33,13 @@
       "type": ["string", "null"],
       "title": "Description",
       "description": "Optional description for the split."
+    },
+    "memo": {
+      "type": ["string", "null"],
+      "title": "Memo",
+      "description": "Optional memo for this split line."
     }
   },
+  "unevaluatedProperties": false,
   "required": ["transactionId", "amount", "categoryId"]
 }

package/dist/index.d.ts

@@ -534,6 +534,7 @@ export type Transaction = Common5 & {
   currency?: Currency;
   amount: Amount1;
   description: Description2;
+  memo?: Memo;
   categoryId?: CategoryID1;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID1;
@@ -600,6 +601,10 @@ export type Amount1 = number;
  * Description of the transaction
  */
 export type Description2 = string;
+/**
+ * Optional memo for the transaction.
+ */
+export type Memo = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -620,6 +625,7 @@ export type TransactionSplit = Common6 & {
   amount: Amount2;
   categoryId: CategoryID2;
   description?: Description3;
+  memo?: Memo1;
 };
 /**
  * UUID for the item
@@ -657,6 +663,10 @@ export type CategoryID2 = string | null;
  * Optional description for the split.
  */
 export type Description3 = string | null;
+/**
+ * Optional memo for this split line.
+ */
+export type Memo1 = string | null;
 
 /**
  * Schema for the luca ledger
@@ -1001,6 +1011,7 @@ export type Transaction = Common & {
   currency?: Currency;
   amount: Amount;
   description: Description;
+  memo?: Memo;
   categoryId?: CategoryID;
   statementId?: StatementID;
   aggregationServiceId?: AggregationServiceID;
@@ -1067,6 +1078,10 @@ export type Amount = number;
  * Description of the transaction
  */
 export type Description = string;
+/**
+ * Optional memo for the transaction.
+ */
+export type Memo = string | null;
 /**
  * Category UUID for this transaction
  */
@@ -1099,6 +1114,7 @@ export type TransactionSplit = Common & {
   amount: Amount;
   categoryId: CategoryID;
   description?: Description;
+  memo?: Memo;
 };
 /**
  * UUID for the item
@@ -1136,6 +1152,10 @@ export type CategoryID = string | null;
  * Optional description for the split.
  */
 export type Description = string | null;
+/**
+ * Optional memo for this split line.
+ */
+export type Memo = string | null;
 
 /**
  * Common properties for all schemas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luca-financial/luca-schema",
-  "version": "2.3.4",
+  "version": "3.0.0",
   "description": "Schemas for the Luca Ledger application",
   "author": "Johnathan Aspinwall",
   "main": "dist/esm/index.js",