From ea106da50c2404722136f579112915fc97046888 Mon Sep 17 00:00:00 2001 From: Jon Eubank Date: Tue, 18 Aug 2026 11:29:59 -0400 Subject: [PATCH 1/3] Add and export types with the Validation error string literal values --- .../src/validateDictionary/DictionaryValidationError.ts | 2 ++ packages/validation/src/validateField/FieldValidationError.ts | 2 ++ packages/validation/src/validateRecord/RecordValidationError.ts | 2 ++ packages/validation/src/validateSchema/SchemaValidationError.ts | 2 ++ 4 files changed, 8 insertions(+) diff --git a/packages/validation/src/validateDictionary/DictionaryValidationError.ts b/packages/validation/src/validateDictionary/DictionaryValidationError.ts index d321b63d..f7b279d8 100644 --- a/packages/validation/src/validateDictionary/DictionaryValidationError.ts +++ b/packages/validation/src/validateDictionary/DictionaryValidationError.ts @@ -48,3 +48,5 @@ export type DictionaryValidationErrorInvalidRecords = DictionaryValidationErrorB export type DictionaryValidationError = | DictionaryValidationErrorUnrecognizedSchema | DictionaryValidationErrorInvalidRecords; + +export type DictionaryValidationErrorReason = DictionaryValidationError['reason']; diff --git a/packages/validation/src/validateField/FieldValidationError.ts b/packages/validation/src/validateField/FieldValidationError.ts index bc886530..d4a4b51d 100644 --- a/packages/validation/src/validateField/FieldValidationError.ts +++ b/packages/validation/src/validateField/FieldValidationError.ts @@ -41,3 +41,5 @@ export type FieldValidationErrorValueType = { }; export type FieldValidationError = FieldValidationErrorRestrictions | FieldValidationErrorValueType; + +export type FieldValidationErrorReason = FieldValidationError['reason']; diff --git a/packages/validation/src/validateRecord/RecordValidationError.ts b/packages/validation/src/validateRecord/RecordValidationError.ts index c3e49234..4a7d588c 100644 --- a/packages/validation/src/validateRecord/RecordValidationError.ts +++ b/packages/validation/src/validateRecord/RecordValidationError.ts @@ -38,3 +38,5 @@ export type RecordValidationError = | RecordValidationErrorInvalidValue | RecordValidationErrorRestrictions | RecordValidationErrorUnrecognizedField; + +export type RecordValidationErrorReason = RecordValidationError['reason']; diff --git a/packages/validation/src/validateSchema/SchemaValidationError.ts b/packages/validation/src/validateSchema/SchemaValidationError.ts index 7cdb9b01..67f7d44d 100644 --- a/packages/validation/src/validateSchema/SchemaValidationError.ts +++ b/packages/validation/src/validateSchema/SchemaValidationError.ts @@ -42,3 +42,5 @@ export type SchemaRecordError = { }; export type SchemaValidationError = SchemaRecordError; + +export type SchemaValidationErrorReason = SchemaValidationRecordErrorDetails['reason']; From fb2e1c4f9af6eed38493762273c06019fdd4f85f Mon Sep 17 00:00:00 2001 From: Jon Eubank Date: Tue, 1 Sep 2026 13:53:42 -0400 Subject: [PATCH 2/3] Add TSDocs for all exported valdiation error types --- .../DictionaryValidationError.ts | 25 +++++++++++++++++++ .../src/validateField/FieldValidationError.ts | 18 +++++++++++-- .../validateRecord/RecordValidationError.ts | 22 ++++++++++++++++ .../validateSchema/SchemaValidationError.ts | 21 ++++++++++++++++ 4 files changed, 84 insertions(+), 2 deletions(-) diff --git a/packages/validation/src/validateDictionary/DictionaryValidationError.ts b/packages/validation/src/validateDictionary/DictionaryValidationError.ts index f7b279d8..6c3bbcd3 100644 --- a/packages/validation/src/validateDictionary/DictionaryValidationError.ts +++ b/packages/validation/src/validateDictionary/DictionaryValidationError.ts @@ -20,14 +20,25 @@ import type { FieldDetails } from '../validateRecord'; import type { SchemaRecordError, SchemaValidationRecordErrorDetails } from '../validateSchema'; +/** + * Shared properties for all dictionary validation errors. Carries the name of the schema + * being validated. + */ export type DictionaryValidationErrorBase = { schemaName: string; }; +/** + * Error for a record submitted for a schema name that does not exist in the dictionary. + */ export type DictionaryValidationErrorUnrecognizedSchema = DictionaryValidationErrorBase & { reason: 'UNRECOGNIZED_SCHEMA'; }; +/** + * Error for a field value that fails a foreign key constraint; `foreignSchema` identifies the + * referenced schema and field that the value must exist in. + */ export type DictionaryValidationErrorRecordForeignKey = FieldDetails & { reason: 'INVALID_BY_FOREIGNKEY'; foreignSchema: { @@ -36,17 +47,31 @@ export type DictionaryValidationErrorRecordForeignKey = FieldDetails & { }; }; +/** + * All error detail types that can appear on a record when validating against a dictionary, + * including foreign key errors. + */ export type DictionaryValidationRecordErrorDetails = | SchemaValidationRecordErrorDetails | DictionaryValidationErrorRecordForeignKey; +/** + * Error for a schema submission that contains one or more invalid records; `invalidRecords` contains a list of + * record validation errors grouped by record. + */ export type DictionaryValidationErrorInvalidRecords = DictionaryValidationErrorBase & { reason: 'INVALID_RECORDS'; invalidRecords: SchemaRecordError[]; }; +/** + * A dictionary-level validation error. Narrow on `reason` to access the specific error properties. + */ export type DictionaryValidationError = | DictionaryValidationErrorUnrecognizedSchema | DictionaryValidationErrorInvalidRecords; +/** + * All `reason` values for a `DictionaryValidationError`. + */ export type DictionaryValidationErrorReason = DictionaryValidationError['reason']; diff --git a/packages/validation/src/validateField/FieldValidationError.ts b/packages/validation/src/validateField/FieldValidationError.ts index d4a4b51d..8ea1f7e0 100644 --- a/packages/validation/src/validateField/FieldValidationError.ts +++ b/packages/validation/src/validateField/FieldValidationError.ts @@ -21,18 +21,26 @@ import type { SchemaFieldValueType } from '@overture-stack/lectern-dictionary'; import type { FieldRestrictionRule } from '../validateField/FieldRestrictionRule'; import type { RestrictionTestInvalidInfo } from '../validateField/FieldRestrictionTest'; +/** + * Information for an error validating a field against a restriction. Includes a restriction rule + * paired with the details of why it failed. + */ export type FieldValidationErrorRestrictionInfo = RestrictionTestInvalidInfo & { restriction: FieldRestrictionRule; }; +/** + * Error for a field value that fails one or more restriction rules (codeList, regex, range, etc.). + * `errors` lists each individual restriction that was violated. + */ export type FieldValidationErrorRestrictions = { reason: 'INVALID_BY_RESTRICTION'; errors: Array; }; /** - * This is the result when the value does not match the value type defined in the field. The properties - * `valueType` and `isArray` are the expected type values as defined in the field definition. + * Validation error for a field value that does not match the field's declared `valueType` or + * `isArray`. */ export type FieldValidationErrorValueType = { reason: 'INVALID_VALUE_TYPE'; @@ -40,6 +48,12 @@ export type FieldValidationErrorValueType = { isArray: boolean; }; +/** + * A field-level validation error. Narrow on `reason` to access the specific error properties. + */ export type FieldValidationError = FieldValidationErrorRestrictions | FieldValidationErrorValueType; +/** + * All `reason` values for a `FieldValidationError`. + */ export type FieldValidationErrorReason = FieldValidationError['reason']; diff --git a/packages/validation/src/validateRecord/RecordValidationError.ts b/packages/validation/src/validateRecord/RecordValidationError.ts index 4a7d588c..f5293cbe 100644 --- a/packages/validation/src/validateRecord/RecordValidationError.ts +++ b/packages/validation/src/validateRecord/RecordValidationError.ts @@ -23,20 +23,42 @@ import type { FieldValidationErrorValueType, } from '../validateField/FieldValidationError'; +/** + * The name and submitted value of a field involved in a validation error. + */ export type FieldDetails = { fieldName: string; fieldValue: DataRecordValue; }; +/** + * Record-level validation error for a field value that does not match the field's declared + * `valueType` or `isArray`. Includes the field name and submitted value alongside the type mismatch details. + */ export type RecordValidationErrorInvalidValue = FieldDetails & FieldValidationErrorValueType; + +/** + * Record-level validation error for a field value that violates one or more restriction rules. + * Includes the field name and submitted value alongside the restriction failure details. + */ export type RecordValidationErrorRestrictions = FieldDetails & FieldValidationErrorRestrictions; + +/** + * Error for a field name present in the record that is not defined in the schema. + */ export type RecordValidationErrorUnrecognizedField = FieldDetails & { reason: 'UNRECOGNIZED_FIELD'; }; +/** + * A record-level validation error. Narrow on `reason` to access the specific error properties. + */ export type RecordValidationError = | RecordValidationErrorInvalidValue | RecordValidationErrorRestrictions | RecordValidationErrorUnrecognizedField; +/** + * All `reason` values for a `RecordValidationError`. + */ export type RecordValidationErrorReason = RecordValidationError['reason']; diff --git a/packages/validation/src/validateSchema/SchemaValidationError.ts b/packages/validation/src/validateSchema/SchemaValidationError.ts index 67f7d44d..4f6c4346 100644 --- a/packages/validation/src/validateSchema/SchemaValidationError.ts +++ b/packages/validation/src/validateSchema/SchemaValidationError.ts @@ -20,27 +20,48 @@ import type { DataRecord } from '@overture-stack/lectern-dictionary'; import type { RecordValidationError, FieldDetails } from '../validateRecord'; +/** + * Error for a record that violates a `uniqueKey` constraint. `uniqueKey` holds the conflicting + * composite key values; `matchingRecords` lists indices of records sharing that key. + */ export type SchemaValidationRecordErrorUniqueKey = { reason: 'INVALID_BY_UNIQUE_KEY'; uniqueKey: DataRecord; matchingRecords: number[]; }; +/** + * Error for a Record where a field value that violates a `unique` constraint. + * `matchingRecords` lists the indices of records with the same value in the specified field. + */ export type SchemaValidationRecordErrorUnique = FieldDetails & { reason: 'INVALID_BY_UNIQUE'; matchingRecords: number[]; }; +/** + * All error detail types that can appear on a record when validating against a schema. + */ export type SchemaValidationRecordErrorDetails = | RecordValidationError | SchemaValidationRecordErrorUnique | SchemaValidationRecordErrorUniqueKey; +/** + * Pairing of a record's position in the submitted data alongside the validation errors it produced. + */ export type SchemaRecordError = { recordIndex: number; recordErrors: ErrorDetails[]; }; +/** + * Error produced when validating a set of records against a schema. Groups per-record errors by + * their index in the submitted data. + */ export type SchemaValidationError = SchemaRecordError; +/** + * All `reason` values across schema-level record errors. + */ export type SchemaValidationErrorReason = SchemaValidationRecordErrorDetails['reason']; From aab166771c1605af3bb6b30f8077f9d0c7df6ca2 Mon Sep 17 00:00:00 2001 From: Jon Eubank Date: Tue, 1 Sep 2026 14:35:22 -0400 Subject: [PATCH 3/3] Export new error types from lectern-client --- packages/client/src/index.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts index b8fdbbd6..643023bf 100644 --- a/packages/client/src/index.ts +++ b/packages/client/src/index.ts @@ -40,10 +40,14 @@ export type { TestResultInvalid, SchemaValidationRecordErrorDetails, SchemaRecordError, + SchemaValidationErrorReason, DictionaryValidationRecordErrorDetails, DictionaryValidationError, + DictionaryValidationErrorReason, FieldValidationErrorRestrictionInfo, FieldValidationError, + FieldValidationErrorReason, + RecordValidationErrorReason, ParseDictionaryData, ParseDictionaryFailure, ParseDictionaryResult,