@tellescope/validation 1.4.0 → 1.4.1

package/src/validation.ts

@@ -192,8 +192,22 @@ export type EscapeBuilder <R=any> = {
 }
 export type ComplexEscapeBuilder <C,R=any> = (customization: C) => EscapeBuilder<R>
 
+export type ValidatorDefinition <R=any> = {
+  validate: EscapeBuilder<R>,
+  getType: () => string | object,
+  getExample: () => string | object,
+}
+export type ValidatorBuilder <R=any, C={}> = (options: ValidatorOptions & C) => ValidatorDefinition<R>
+
+const EXAMPLE_OBJECT_ID = '60398b0231a295e64f084fd9'
+const getTypeString = () => "string"
+const getTypeNumber = () => "number"
+const getExampleString = () => 'example string'
+const getExampleObjectId = () => EXAMPLE_OBJECT_ID
+
 export type InputValues <T> = { [K in keyof T]: JSONType }
-export type InputValidation<T> = { [K in keyof T]: EscapeFunction }
+export type InputValidation<T> = { [K in keyof T]: ValidatorDefinition }
+export type InputValidationOld<T> = { [K in keyof T]: EscapeFunction }
 
 export const MAX_FILE_SIZE = 25000000 // 25 megabytes in bytes
 const DEFAULT_MAX_LENGTH = 5000
@@ -282,16 +296,17 @@ export const build_validator: BuildValidator_T = (escapeFunction, options={} as
   }
 }
 
-export const fieldsToValidation = <T>(fs: { [K in keyof T]: { validator: EscapeBuilder, required?: boolean } }): InputValidation<T> => {
-  const validation = {} as InputValidation<T>
+export const fieldsToValidationOld = <T>(fs: { [K in keyof T]: { validator: ValidatorDefinition, required?: boolean } }): InputValidationOld<T> => {
+  const validation = {} as InputValidationOld<T>
 
   for (const f in fs) {
-    validation[f] = fs[f].validator({ isOptional: !fs[f].required })
+    validation[f] =  fs[f].validator.validate({ isOptional: !fs[f].required }) 
   }
 
   return validation
 }
 
+
 /********************************* VALIDATORS *********************************/
 const optionsWithDefaults = (options={} as ValidatorOptions) => {
   return {
@@ -319,20 +334,24 @@ export const binaryOrValidator = <A, B>(f1: EscapeFunction<A>, f2: EscapeFunctio
   }, 
   { ...o, listOf: false }
 )
-export const orValidator = <T>(escapeFunctions: { [K in keyof T]: EscapeFunction<T[K]> }): EscapeBuilder<T[keyof T]> => (o={}) => build_validator(
-  value => {
-    for (const field in escapeFunctions) {
-      const escape = escapeFunctions[field]
-      try {
-        return escape(value)
-      } catch(err) { 
-        continue 
+export const orValidator = <T>(validators: { [K in keyof T]: ValidatorDefinition<T[K]> }): ValidatorDefinition<T[keyof T]> => ({
+  validate: (o={}) => build_validator(
+    value => {
+      for (const field in validators) {
+        const escape = validators[field]
+        try {
+          return escape.validate()(value)
+        } catch(err) { 
+          continue 
+        }
       }
-    }
-    throw `Value does not match any of the expected options`
-  },
-  { ...o, listOf: false }
-)
+      throw `Value does not match any of the expected options`
+    },
+    { ...o, listOf: false }
+  ),
+  getExample: () => (Object.values(validators)[0] as ValidatorDefinition).getExample(),
+  getType: () => [Object.values(validators).map(v => (v as ValidatorDefinition).getType())]
+})
 
 export const filterCommandsValidator: EscapeBuilder<FilterType> = (o={}) => build_validator(
   (value: any) => {
@@ -389,9 +408,11 @@ export const convertCommands = (operators: Indexable<any>) => {
 
 interface ObjectOptions {
   emptyOk?: boolean,
+  isOptional?: boolean,
   throwOnUnrecognizedField?: boolean,
 }
-export const objectValidator = <T extends object>(i: InputValidation<Required<T>>, objectOptions={ emptyOk: true } as ObjectOptions): EscapeBuilder<T>  => (o={}) => build_validator(
+
+export const objectValidatorOld = <T extends object>(i: InputValidationOld<Required<T>>, objectOptions={ emptyOk: true } as ObjectOptions): EscapeBuilder<T>  => (o={}) => build_validator(
   (object: any) => {
     const emptyOk = objectOptions.emptyOk ?? true
     const validated = {} as T
@@ -427,68 +448,140 @@ export const objectValidator = <T extends object>(i: InputValidation<Required<T>
     return validated
   }, { ...o, isObject: true, listOf: false }
 )
-export const listOfObjectsValidator = <T extends object>(i: InputValidation<Required<T>>, objectOptions={ emptyOk: true }): EscapeBuilder<T[]>  => (o={}) => build_validator(
-  (object: any) => {
-    const emptyOk = !!objectOptions.emptyOk || o.emptyListOk
-    const validated = {} as T
+export const listValidatorOld = <T>(b: EscapeFunction<T>): EscapeBuilder<T[]> => o => build_validator(
+  b, { ...o, listOf: true }
+)
 
-    if (!is_object(object)) {
-      throw new Error(`Expected a non-null object by got ${object}`)
-    }
-    if (!emptyOk && object_is_empty(object)) {
-      throw new Error(`Expected a non-empty object`)
-    }
+const exampleObject = (fields: InputValidation<any>) => {
+  const examples = {} as Indexable<string | object>
 
-    // don't throw on unrecognized fields, just ignore/don't validate them
-    // const unrecognizedFields = []
-    // for (const field in object) {
-    //   if (!(i as Indexable)[field]) {
-    //     unrecognizedFields.push(field)
-    //   } 
-    // }
-    // if (unrecognizedFields.length > 0) {
-    //   throw new Error(`Got unexpected field(s) [${unrecognizedFields.join(', ')}]`)
-    // }
+  for (const field in fields) {
+    examples[field] = fields[field].getExample()
+  }
 
-    for (const field in i) {
-      const value = (object as Indexable)[field] 
+  return examples
+}
+const typeObject = (fields: InputValidation<any>) => {
+  const types = {} as Indexable<string | object>
 
-      const escaped = i[field](value) // may be required
-      if (escaped === undefined) continue
+  for (const field in fields) {
+    types[field] = fields[field].getType()
+  }
 
-      validated[field] = escaped
-    }
+  return types
+}
 
-    return validated
-  }, { ...o, isObject: true, listOf: true, emptyListOk: !!objectOptions.emptyOk || o.emptyListOk }
-)
+export const objectValidator = <T extends object>(i: InputValidation<Required<T>>, objectOptions={ emptyOk: true } as ObjectOptions): ValidatorDefinition<T>  => ({
+  validate: (o={}) => build_validator(
+    (object: any) => {
+      const emptyOk = objectOptions.emptyOk ?? true
+      const validated = {} as T
 
-export const objectAnyFieldsValidator = <T>(valueValidator?: EscapeFunction<T>): EscapeBuilder<Indexable<T>> => (o={}) => build_validator(
-  (object: any) => {
-    if (!is_object(object)) { throw new Error("Expected a non-null object by got ${object}") }
+      if (!is_object(object)) {
+        throw new Error(`Expected a non-null object by got ${object}`)
+      }
+      if (!emptyOk && object_is_empty(object)) {
+        throw new Error(`Expected a non-empty object`)
+      }
 
-    const validated = {} as Indexable
+      // don't throw on unrecognized fields, just ignore/don't validate them
+      if (objectOptions.throwOnUnrecognizedField) {
+        const unrecognizedFields = []
+        for (const field in object) {
+          if (!(i as Indexable)[field]) {
+            unrecognizedFields.push(field)
+          } 
+        }
+        if (unrecognizedFields.length > 0) {
+          throw new Error(`Got unexpected field(s) [${unrecognizedFields.join(', ')}]`)
+        }
+      }
+
+      for (const field in i) {
+        const value = (object as Indexable)[field] 
+        const escaped = i[field].validate()(value) // may be required
+        if (escaped === undefined) continue
 
-    for (const field in object) {
-      if (valueValidator) {
-        validated[field] = valueValidator(object[field])
-      } else if (typeof object[field] === 'number') {
-        validated[field] = numberValidator(object[field])
-      } else if (typeof object[field] === 'string') {
-        validated[field] = stringValidator(object[field])
-      } else if (object[field] === null) {
-        validated[field] = null
-      } else {
+        validated[field] = escaped
+      }
+
+      return validated
+    }, { ...o, isObject: true, listOf: false, isOptional: !!objectOptions.isOptional || o.isOptional }
+  ),
+  getExample: () => exampleObject(i),
+  getType: () => typeObject(i),
+})
+
+export const listOfObjectsValidator = <T extends object>(i: InputValidation<Required<T>>, objectOptions={ emptyOk: true }): ValidatorDefinition<T[]> => ({
+  validate: (o={}) => build_validator(
+    (object: any) => {
+      const emptyOk = !!objectOptions.emptyOk || o.emptyListOk
+      const validated = {} as T
+
+      if (!is_object(object)) {
+        throw new Error(`Expected a non-null object by got ${object}`)
+      }
+      if (!emptyOk && object_is_empty(object)) {
+        throw new Error(`Expected a non-empty object`)
+      }
+
+      // don't throw on unrecognized fields, just ignore/don't validate them
+      // const unrecognizedFields = []
+      // for (const field in object) {
+      //   if (!(i as Indexable)[field]) {
+      //     unrecognizedFields.push(field)
+      //   } 
+      // }
+      // if (unrecognizedFields.length > 0) {
+      //   throw new Error(`Got unexpected field(s) [${unrecognizedFields.join(', ')}]`)
+      // }
+
+      for (const field in i) {
+        const value = (object as Indexable)[field] 
+
+        const escaped = i[field].validate()(value) // may be required
+        if (escaped === undefined) continue
+
+        validated[field] = escaped
+      }
+
+      return validated
+    }, { ...o, isObject: true, listOf: true, emptyListOk: !!objectOptions.emptyOk || o.emptyListOk }
+  ),
+  getExample: () => [exampleObject(i)], // don't forget list
+  getType: () => [typeObject(i)] // don't forget list
+})
+
+export const objectAnyFieldsValidator = <T>(valueValidator?: ValidatorDefinition<T>): ValidatorDefinition<Indexable<T>> => ({
+  validate: (o={}) => build_validator(
+    (object: any) => {
+      if (!is_object(object)) { throw new Error("Expected a non-null object by got ${object}") }
+
+      const validated = {} as Indexable
+
+      for (const field in object) {
         if (valueValidator) {
-          throw new Error(`Field ${field} is not a string or number`)
+          validated[field] = valueValidator.validate()(object[field])
+        } else if (typeof object[field] === 'number') {
+          validated[field] = numberValidator.validate()(object[field])
+        } else if (typeof object[field] === 'string') {
+          validated[field] = stringValidator.validate()(object[field])
+        } else if (object[field] === null) {
+          validated[field] = null
+        } else {
+          if (valueValidator) {
+            throw new Error(`Field ${field} is not a string or number`)
+          }
+          validated[field] = object[field]
         }
-        validated[field] = object[field]
       }
-    }
 
-    return validated
-  }, { ...o, isObject: true, listOf: false }
-)
+      return validated
+    }, { ...o, isObject: true, listOf: false }
+  ),
+  getExample: () => `{ "key": ${valueValidator?.getExample?.() ?? '"value"'} }`,
+  getType: () => `{ "key": ${valueValidator?.getType?.() ?? 'string'} }`,
+})
 
 export const objectAnyFieldsAnyValuesValidator = objectAnyFieldsValidator()
 
@@ -504,51 +597,125 @@ export const escapeString: EscapeWithOptions<string> = (o={}) => string => {
   }
   return string
 }
-export const stringValidator: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeString(o), { ...o, maxLength: o.maxLength ?? 1000, listOf: false  } 
-)
-export const stringValidator100: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeString(o), { ...o, maxLength: 100, listOf: false  } 
-)
-export const stringValidator250: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeString(o), { ...o, maxLength: 250, listOf: false  } 
-)
-export const stringValidator1000: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeString(o), { ...o, maxLength: 1000, listOf: false  } 
-)
-export const stringValidator5000: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeString(o), { ...o, maxLength: 5000, listOf: false  } 
-)
-export const stringValidator25000: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeString(o), { ...o, maxLength: 25000, listOf: false  } 
-)
-export const SMSMessageValidator: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeString(o), { ...o, maxLength: 630, listOf: false  } 
-)
 
-export const listValidator = <T>(b: EscapeFunction<T>): EscapeBuilder<T[]> => o => build_validator(
-  b, { ...o, listOf: true }
-)
-export const listValidatorEmptyOk = <T>(b: EscapeFunction<T>): EscapeBuilder<T[]> => o => build_validator(
-  b, { ...o, listOf: true, emptyListOk: true }
-)
+export const stringValidator: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: o.maxLength ?? 1000, listOf: false  } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidatorOptional: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: o.maxLength ?? 1000, listOf: false, isOptional: true } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidator100: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 100, listOf: false  } 
+  ),
+  getExample: () => 'example string',
+  getType: () => 'string'
+}
 
-export const listOfStringsValidator = listValidator(stringValidator()) 
-export const listOfStringsValidatorEmptyOk = listValidatorEmptyOk(stringValidator()) 
-export const listOfObjectAnyFieldsAnyValuesValidator = listValidator(objectAnyFieldsAnyValuesValidator())
+export const stringValidator250: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 250, listOf: false  } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidator1000: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 1000, listOf: false  } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidator5000: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 5000, listOf: false  } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidator5000EmptyOkay: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 5000, listOf: false, emptyStringOk: true } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidator5000Optional: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 5000, listOf: false, isOptional: true, emptyStringOk: true } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidator25000: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 25000, listOf: false  } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const stringValidator25000EmptyOkay: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 25000, listOf: false, emptyStringOk: true } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
+export const SMSMessageValidator: ValidatorDefinition<string> = {
+  validate: (o={}) => build_validator(
+    escapeString(o), { ...o, maxLength: 630, listOf: false  } 
+  ),
+  getExample: getExampleString,
+  getType: getTypeString,
+}
 
-export const booleanValidator: EscapeBuilder<boolean> = (options={}) => build_validator(
-  boolean => {
-    if (boolean === 'true') return true
-    if (boolean === 'false') return false
+export const listValidator = <T>(b: ValidatorDefinition<T>, o?: ValidatorOptions | ValidatorOptionsForList): ValidatorDefinition<T[]> => ({
+  validate: o => build_validator(b.validate(o as any), { ...o, listOf: true }),
+  getExample: () => [b.getExample()],
+  getType: () => [b.getExample()],
+})
+export const listValidatorEmptyOk = <T>(b: ValidatorDefinition<T>, o?: ValidatorOptions): ValidatorDefinition<T[]> => ({
+  validate: o => build_validator(b.validate(o as any), { ...o, listOf: true, emptyListOk: true }),
+  getExample: () => [b.getExample()],
+  getType: () => [b.getExample()],
+})
+export const listValidatorOptionalOrEmptyOk = <T>(b: ValidatorDefinition<T>, o?: ValidatorOptions): ValidatorDefinition<T[]> => ({
+  validate: o => build_validator(b.validate(o as any), { ...o, listOf: true, emptyListOk: true, isOptional: true }),
+  getExample: () => [b.getExample()],
+  getType: () => [b.getExample()],
+})
 
-    if (typeof boolean !== 'boolean') {
-      throw new Error(options.errorMessage || "Invalid boolean")
-    }
-    return boolean
-  }, 
-  { ...options, isBoolean: true, listOf: false }
-)
+export const listOfStringsValidator = listValidator(stringValidator) 
+export const listOfStringsValidatorOptionalOrEmptyOk = listValidatorOptionalOrEmptyOk(stringValidator) 
+export const listOfStringsValidatorEmptyOk = listValidatorEmptyOk(stringValidator) 
+export const listOfObjectAnyFieldsAnyValuesValidator = listValidator(objectAnyFieldsAnyValuesValidator)
+
+export const booleanValidatorBuilder: ValidatorBuilder<boolean> = (defaults) => ({
+  validate: (options={}) => build_validator(
+    boolean => {
+      if (boolean === 'true') return true
+      if (boolean === 'false') return false
+
+      if (typeof boolean !== 'boolean') {
+        throw new Error(options.errorMessage || "Invalid boolean")
+      }
+      return boolean
+    }, 
+    { ...defaults, ...options, isBoolean: true, listOf: false }
+  ),
+  getExample: () => "false",
+  getType: () => "boolean",
+})
+export const booleanValidator = booleanValidatorBuilder({ })
+export const booleanValidatorOptional = booleanValidatorBuilder({ isOptional: true })
 
 export const escapeMongoId: EscapeFunction<string> = (mongoId: any) => {
   if (typeof mongoId !== 'string') throw new Error('Expecting string id')
@@ -557,12 +724,20 @@ export const escapeMongoId: EscapeFunction<string> = (mongoId: any) => {
   }
   return mongoId
 }
-export const mongoIdValidator: EscapeBuilder<ObjectId> = (o={}) => build_validator(
-  s => to_object_id(escapeMongoId(s)), { ...optionsWithDefaults(o), maxLength: 100, listOf: false } 
-) 
-export const mongoIdStringValidator: EscapeBuilder<string> = (o={}) => build_validator(
-  escapeMongoId, { ...optionsWithDefaults(o), maxLength: 100, listOf: false } 
-) 
+export const mongoIdValidator: ValidatorDefinition<ObjectId> = {
+  validate: (o={}) => build_validator(
+    s => to_object_id(escapeMongoId(s)), { ...optionsWithDefaults(o), maxLength: 100, listOf: false } 
+  ),
+  getType: getTypeString,
+  getExample: getExampleObjectId,
+}
+export const buildMongoIdStringValidator: ValidatorBuilder<string> = (options) => ({
+  validate: (o={}) => build_validator(
+    escapeMongoId, { ...optionsWithDefaults({ ...options, ...o }), maxLength: 100, listOf: false } 
+  ),
+  getType: getTypeString,
+  getExample: getExampleObjectId,
+})
 
 export const nullValidator: EscapeBuilder<null> = (o={}) => build_validator(
   v => {
@@ -573,215 +748,296 @@ export const nullValidator: EscapeBuilder<null> = (o={}) => build_validator(
   { ...o, listOf: false }
 ) 
 
-export const mongoIdRequired = mongoIdValidator()
-export const mongoIdOptional = mongoIdValidator({ isOptional: true })
-export const mongoIdStringRequired = mongoIdStringValidator()
-export const mongoIdStringOptional = mongoIdStringValidator({ isOptional: true })
-export const listOfMongoIdValidator = listValidator(mongoIdValidator())
-export const listOfMongoIdStringValidator = listValidator(mongoIdStringValidator())
-export const listOfMongoIdStringValidatorEmptyOk = listValidatorEmptyOk(mongoIdStringValidator())
+export const mongoIdRequired = mongoIdValidator.validate()
+export const mongoIdOptional = mongoIdValidator.validate({ isOptional: true })
+export const listOfMongoIdValidator = listValidator(mongoIdValidator)
+
+export const mongoIdStringRequired = buildMongoIdStringValidator({ isOptional: false })
+export const mongoIdStringOptional = buildMongoIdStringValidator({ isOptional: true })
+export const listOfMongoIdStringValidator = listValidator(mongoIdStringRequired)
+export const listOfMongoIdStringValidatorEmptyOk = listValidatorEmptyOk(mongoIdStringRequired)
 
 export const first_letter_capitalized = (s='') => s.charAt(0).toUpperCase() + s.slice(1)
 export const escape_name = (namestring: string) => namestring.replace(/[^a-zA-Z0-9-_ /.]/, '').substring(0, 100)
 
 // enforces first-letter capitalization
-export const nameValidator: EscapeBuilder<string> = (options={}) => build_validator(
-  name => {
-    if (typeof name !== 'string') throw new Error('Expecting string value')
+export const nameValidator: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    name => {
+      if (typeof name !== 'string') throw new Error('Expecting string value')
 
-    name = escape_name(name)  
-    if (!name) throw new Error("Invalid name")
+      name = escape_name(name)  
+      if (!name) throw new Error("Invalid name")
 
-    return first_letter_capitalized(name) 
-  }, 
-  { ...options, maxLength: 100, trim: true, listOf: false }
-)
+      return first_letter_capitalized(name) 
+    }, 
+    { ...options, maxLength: 100, trim: true, listOf: false }
+  ),
+  getExample: () => 'John',
+  getType: getTypeString,
+}
 
+export const emailValidator: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    (email) => {
+      if (typeof email !== 'string') throw new Error('Expecting string value')
+      if (!isEmail(email)) { throw new Error(options.errorMessage || "Invalid email") }
 
-export const emailValidator: EscapeBuilder<string> = (options={}) => build_validator(
-  (email) => {
-    if (typeof email !== 'string') throw new Error('Expecting string value')
-    if (!isEmail(email)) { throw new Error(options.errorMessage || "Invalid email") }
+      return email.toLowerCase()
+    }, 
+    { ...options, maxLength: 250, listOf: false }
+  ),
+  getExample: () => "example@tellescope.com",
+  getType: getTypeString,
+}
+export const emailValidatorOptional: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    (email) => {
+      if (typeof email !== 'string') throw new Error('Expecting string value')
+      if (!isEmail(email)) { throw new Error(options.errorMessage || "Invalid email") }
 
-    return email.toLowerCase()
-  }, 
-  { ...options, maxLength: 250, listOf: false }
-)
+      return email.toLowerCase()
+    }, 
+    { ...options, maxLength: 250, listOf: false, isOptional: true, emptyStringOk: true }
+  ),
+  getExample: () => "example@tellescope.com",
+  getType: getTypeString,
+}
 
-export const emailValidatorEmptyOkay: EscapeBuilder<string> = (options={}) => build_validator(
-  (email) => {
-    if (typeof email !== 'string') throw new Error('Expecting string value')
-    if (!isEmail(email)) { throw new Error(options.errorMessage || "Invalid email") }
+export const emailValidatorEmptyOkay: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    (email) => {
+      if (typeof email !== 'string') throw new Error('Expecting string value')
+      if (!isEmail(email)) { throw new Error(options.errorMessage || "Invalid email") }
 
-    return email.toLowerCase()
-  }, 
-  { ...options, maxLength: 250, emptyStringOk: true, listOf: false }
-)
+      return email.toLowerCase()
+    }, 
+    { ...options, maxLength: 250, emptyStringOk: true, listOf: false }
+  ),
+  getExample: () => "example@tellescope.com",
+  getType: getTypeString,
+}
 
 
-export const numberValidatorBuilder: ComplexEscapeBuilder<{ lower: number, upper: number }, number> = r => (options={}) => {
-  options.isNumber = true
+export const numberValidatorBuilder: ValidatorBuilder<number, { lower: number, upper: number }> = ({ lower, upper, ...higherOptions }) => ({
+  validate: (options={}) => {
+    options.isNumber = true
 
-  return build_validator(
-   (number: any) => {
-      number = Number(number) // ok to throw error!
-      if (typeof number !== "number" || isNaN(number)) {
-        throw new Error(options.errorMessage || `Not a valid number`)
-      }
-      if (!r) return number
+    return build_validator(
+    (number: any) => {
+        number = Number(number) // ok to throw error!
+        if (typeof number !== "number" || isNaN(number)) {
+          throw new Error(options.errorMessage || `Not a valid number`)
+        }
+        if (!(lower || upper)) return number
 
-      if (!(number >= r.lower && number <= r.upper)) {
-        throw new Error(options.errorMessage || `Not a valid number for [${r.lower}-${r.upper}]`)
-      }
-      return number
-    }, 
-    { ...options, listOf: false }
-  )
-}
+        if (!(number >= lower && number <= upper)) {
+          throw new Error(options.errorMessage || `Not a valid number for [${lower}-${upper}]`)
+        }
+        return number
+      }, 
+      { ...optionsWithDefaults({ ...higherOptions, ...options }), listOf: false, }
+    )
+  },
+  getExample: () => `${lower}`, // `a number from ${lower} to ${upper}`,
+  getType: getTypeNumber,
+})
 
 export const nonNegNumberValidator = numberValidatorBuilder({ lower: 0, upper: 10000000000000 }) // max is 2286 in UTC MS
 export const numberValidator = numberValidatorBuilder({ lower: -100000000, upper: 10000000000000 }) // max is 2286 in UTC MS
+export const numberValidatorOptional = numberValidatorBuilder({ lower: -100000000, upper: 10000000000000, isOptional: true, emptyStringOk: true }) // max is 2286 in UTC MS
 export const fileSizeValidator = numberValidatorBuilder({ lower: 0, upper: MAX_FILE_SIZE })
 
-export const dateValidator: EscapeBuilder<Date> = (options={}) => build_validator(
-  (date: any) => {
-    if (isDate(date)) throw new Error(options.errorMessage || "Invalid date") 
+export const dateValidator: ValidatorDefinition<Date> = {
+  validate: (options={}) => build_validator(
+    (date: any) => {
+      if (isDate(date)) throw new Error(options.errorMessage || "Invalid date") 
 
-    return new Date(date)
-  }, 
-  { ...options, maxLength: 250, listOf: false }
-)
-
-export const exactMatchValidator = <T extends string>(matches: T[]): EscapeBuilder<T> => (o={}) => build_validator(
-  (match: JSONType) => {
-    if (matches.filter(m => m === match).length === 0) {
-      throw new Error(`Value must match one of ${matches}`)
-    }
-    return match
-  }, 
-  { ...o, listOf: false }
-)
-export const exactMatchListValidator = <T extends string>(matches: T[]): EscapeBuilder<T[]> => (o={}) => build_validator(
-  (match: JSONType) => {
-    if (matches.filter(m => m === match).length === 0) {
-      throw new Error(`Value must match one of ${matches}`)
-    }
-    return match
-  }, 
-  { ...o, listOf: true }
-)
+      return new Date(date)
+    }, 
+    { ...options, maxLength: 250, listOf: false }
+  ),
+  getExample: () => new Date().toISOString(),
+  getType: () => "Date",
+}
+export const dateValidatorOptional: ValidatorDefinition<Date> = {
+  validate: (options={}) => build_validator(
+    (date: any) => {
+      if (isDate(date)) throw new Error(options.errorMessage || "Invalid date") 
 
-export const journeysValidator: EscapeBuilder<Indexable> = (options={}) => build_validator(
-  (journeys) => {
-    if (typeof journeys !== 'object') {
-      throw new Error('Expecting an object')
-    }
+      return new Date(date)
+    }, 
+    { ...options, maxLength: 250, listOf: false, isOptional: true, emptyStringOk: true }
+  ),
+  getExample: () => new Date().toISOString(),
+  getType: () => "Date",
+}
 
-    const mIdValidator = mongoIdValidator()
-    const stateValidator   = stringValidator({ isOptional: true, maxLength: 75, errorMessage: "Journey state names may not exceed 75 characters" })
-    for (const j in journeys) {
-      mIdValidator(j);
-      (journeys as Indexable)[j] = stateValidator(journeys[j as keyof typeof journeys]);
-    }
-    return journeys
-  }, 
-  { ...options, isObject: true, listOf: false }
-)
+export const exactMatchValidator = <T extends string>(matches: T[]): ValidatorDefinition<T> => ({
+  validate: (o={}) => build_validator(
+    (match: JSONType) => {
+      if (matches.filter(m => m === match).length === 0) {
+        throw new Error(`Value must match one of ${matches}`)
+      }
+      return match
+    }, 
+    { ...o, listOf: false }
+  ),
+  getExample: () => matches[0],
+  getType: getTypeString,
+})
+export const exactMatchValidatorOptional = <T extends string>(matches: T[]): ValidatorDefinition<T> => ({
+  validate: (o={}) => build_validator(
+    (match: JSONType) => {
+      if (matches.filter(m => m === match).length === 0) {
+        throw new Error(`Value must match one of ${matches}`)
+      }
+      return match
+    }, 
+    { ...o, listOf: false, isOptional: true }
+  ),
+  getExample: () => matches[0],
+  getType: getTypeString,
+})
+export const exactMatchListValidator = <T extends string>(matches: T[]) => listValidator(exactMatchValidator(matches))
 
-export const escape_phone_number = (p='') => p.replace(/[^\d+]/g, '')
+export const journeysValidator: ValidatorDefinition<Indexable> = {
+  validate: (options={}) => build_validator(
+    (journeys) => {
+      if (typeof journeys !== 'object') {
+        throw new Error('Expecting an object')
+      }
 
-export const phoneValidator: EscapeBuilder<string> = (options={}) => build_validator(
-  phone => {
-    if (typeof phone !== "string") throw new Error(`Expecting phone to be string but got ${phone}`)
+      const mIdValidator = mongoIdValidator.validate()
+      const stateValidator   = stringValidator.validate({ isOptional: true, maxLength: 75, errorMessage: "Journey state names may not exceed 75 characters" })
+      for (const j in journeys) {
+        mIdValidator(j);
+        (journeys as Indexable)[j] = stateValidator(journeys[j as keyof typeof journeys]);
+      }
+      return journeys
+    }, 
+    { ...options, isObject: true, listOf: false }
+  ),
+  getExample: () => `{ ${EXAMPLE_OBJECT_ID}: "status" }`,
+  getType: () => `{ string: string }`,
+}
 
-    let escaped = escape_phone_number(phone) 
-    if (escaped.length < 10) throw new Error(`Phone number must be at least 10 digits`)
+export const escape_phone_number = (p='') => p.replace(/[^\d+]/g, '')
 
-    escaped = escaped.startsWith('+') ? escaped
-            : escaped.length === 10   ? '+1' + escaped // assume US country code for now
-                                      : "+"  + escaped // assume country code provided, but missing leading +
+export const phoneValidator: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    phone => {
+      if (typeof phone !== "string") throw new Error(`Expecting phone to be string but got ${phone}`)
 
-    if (!isMobilePhone(escaped, 'any', { strictMode: true })) {
-      throw `Invalid phone number`
-    }
+      let escaped = escape_phone_number(phone) 
+      if (escaped.length < 10) throw new Error(`Phone number must be at least 10 digits`)
 
-    return escaped
-  }, 
-  { ...options, maxLength: 25, listOf: false }
-)
+      escaped = escaped.startsWith('+') ? escaped
+              : escaped.length === 10   ? '+1' + escaped // assume US country code for now
+                                        : "+"  + escaped // assume country code provided, but missing leading +
 
-export const phoneValidatorEmptyOkay: EscapeBuilder<string> = (options={}) => build_validator(
-  phone => {
-    if (typeof phone !== "string") throw new Error(`Expecting phone to be string but got ${phone}`)
+      if (!isMobilePhone(escaped, 'any', { strictMode: true })) {
+        throw `Invalid phone number`
+      }
 
-    let escaped = escape_phone_number(phone) 
-    if (escaped.length < 10) throw new Error(`Phone number must be at least 10 digits`)
+      return escaped
+    }, 
+    { ...options, maxLength: 25, listOf: false }
+  ),
+  getExample: () => "+15555555555",
+  getType: getTypeString,
+}
+export const phoneValidatorOptional: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    phone => {
+      if (typeof phone !== "string") throw new Error(`Expecting phone to be string but got ${phone}`)
 
-    escaped = escaped.startsWith('+') ? escaped
-            : escaped.length === 10   ? '+1' + escaped // assume US country code for now
-                                      : "+"  + escaped // assume country code provided, but missing leading +
+      let escaped = escape_phone_number(phone) 
+      if (escaped.length < 10) throw new Error(`Phone number must be at least 10 digits`)
 
-    if (!isMobilePhone(escaped, 'any', { strictMode: true })) {
-      throw `Invalid phone number`
-    }
+      escaped = escaped.startsWith('+') ? escaped
+              : escaped.length === 10   ? '+1' + escaped // assume US country code for now
+                                        : "+"  + escaped // assume country code provided, but missing leading +
 
-    return escaped
-  }, 
-  { ...options, maxLength: 25, listOf: false, emptyStringOk: true }
-)
+      if (!isMobilePhone(escaped, 'any', { strictMode: true })) {
+        throw `Invalid phone number`
+      }
 
-export const fileTypeValidator: EscapeBuilder<string> = (options={}) => build_validator(
-  (s: any) => {
-    if (typeof s !== 'string') throw new Error("fileType must be a string")
-    if (!isMimeType(s)) throw new Error(`${s} is not a valid file type`)
+      return escaped
+    }, 
+    { ...options, maxLength: 25, listOf: false, isOptional: true, emptyStringOk: true }
+  ),
+  getExample: () => "+15555555555",
+  getType: getTypeString,
+}
 
-    return s
-  }, 
-  { ...options, listOf: false }
-)
+export const fileTypeValidator: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    (s: any) => {
+      if (typeof s !== 'string') throw new Error("fileType must be a string")
+      if (!isMimeType(s)) throw new Error(`${s} is not a valid file type`)
 
-export const urlValidator: EscapeBuilder<string> = (options={}) => build_validator(
-  (s: any) => {
-    if (typeof s !== 'string') throw new Error("URL must be a string")
-    if (!isURL(s)) throw new Error(`${s} is not a valid URL`)
+      return s
+    }, 
+    { ...options, listOf: false }
+  ),
+  getExample: () => 'text/plain',
+  getType: getTypeString,
+}
+export const urlValidator: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    (s: any) => {
+      if (typeof s !== 'string') throw new Error("URL must be a string")
+      if (!isURL(s)) throw new Error(`${s} is not a valid URL`)
 
-    return s
-  }, 
-  { ...options, listOf: false }
-)
+      return s
+    }, 
+    { ...options, listOf: false }
+  ),
+  getExample: () => '"https://www.tellescope.com"',
+  getType: getTypeString,
+}
 
-export const safeBase64Validator = (options={}) => build_validator(
-  (sb64: any) => {
-    if (typeof sb64 !== 'string') throw new Error("Expecting string")
+export const safeBase64Validator: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    (sb64: any) => {
+      if (typeof sb64 !== 'string') throw new Error("Expecting string")
 
-    // https://stackoverflow.com/questions/12930007/how-to-validate-base64-string-using-regex-in-javascript
-    // regex with = + and / replaced as get_random_base64_URL_safe 
-    if (!/^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-]{2}..|[A-Za-z0-9_-]{3}.)?$/.test(sb64)) {
-      throw `Invalid safe base64`
-    }
-    return sb64
-  },
-  { ...options, listOf: false }
-)
+      // https://stackoverflow.com/questions/12930007/how-to-validate-base64-string-using-regex-in-javascript
+      // regex with = + and / replaced as get_random_base64_URL_safe 
+      if (!/^(?:[A-Za-z0-9_-]{4})*(?:[A-Za-z0-9_-]{2}..|[A-Za-z0-9_-]{3}.)?$/.test(sb64)) {
+        throw `Invalid safe base64`
+      }
+      return sb64
+    },
+    { ...options, listOf: false }
+  ),
+  getExample: () => '129vjas0fkj1234jgfmnaef',
+  getType: getTypeString,
+}
 
-export const subdomainValidator = (options={}) => build_validator(
-  subdomain => {
-    if (typeof subdomain !== 'string') throw new Error("Expecting string value") 
+export const subdomainValidator: ValidatorDefinition<string> = {
+  validate: (options={}) => build_validator(
+    subdomain => {
+      if (typeof subdomain !== 'string') throw new Error("Expecting string value") 
 
-    subdomain = subdomain.toLowerCase()
-    if (subdomain.startsWith('-')) {
-      subdomain = subdomain.substring(1)
-    }
-    while (subdomain.endsWith('-')) {
-      subdomain = subdomain.substring(0, subdomain.length - 1)
-    }
+      subdomain = subdomain.toLowerCase()
+      if (subdomain.startsWith('-')) {
+        subdomain = subdomain.substring(1)
+      }
+      while (subdomain.endsWith('-')) {
+        subdomain = subdomain.substring(0, subdomain.length - 1)
+      }
 
-    subdomain = subdomain.replace(/[^a-zA-Z\d-]/g, '')
+      subdomain = subdomain.replace(/[^a-zA-Z\d-]/g, '')
 
-    return subdomain
-  }, 
-  { ...options, maxLength: 50, listOf: false }
-)
+      return subdomain
+    }, 
+    { ...options, maxLength: 50, listOf: false }
+  ),
+  getExample: () => 'example',
+  getType: getTypeString,
+}
 
 type FileResponse = { type: 'file', name: string, secureName: string }
 // export const fileResponseValidator: EscapeBuilder<FileResponse> = (options={}) => build_validator(
@@ -796,16 +1052,16 @@ type FileResponse = { type: 'file', name: string, secureName: string }
 //   { ...options, isObject: true, listOf: false }
 // )
 export const fileResponseValidator = objectValidator<FileResponse>({
-  type: exactMatchValidator(['file'])(),
-  name: stringValidator({ shouldTruncate: true, maxLength: 250 }),
-  secureName: stringValidator250(),
+  type: exactMatchValidator(['file']),
+  name: stringValidator1000,
+  secureName: stringValidator250,
 })
 
 type SignatureResponse = { type: 'signature', signed: string | null, fullName: string }
 export const signatureResponseValidator = objectValidator<SignatureResponse>({
-  type: exactMatchValidator(['signature'])(),
-  fullName: stringValidator({ maxLength: 100 }),
-  signed: booleanValidator(), 
+  type: exactMatchValidator(['signature']),
+  fullName: stringValidator100,
+  signed: booleanValidator, 
 })
 
 
@@ -845,22 +1101,25 @@ const _FORM_FIELD_TYPES: { [K in FormFieldType]: any } = {
 export const FORM_FIELD_TYPES = Object.keys(_FORM_FIELD_TYPES) as FormFieldType[]
 export const formFieldTypeValidator = exactMatchValidator<FormFieldType>(FORM_FIELD_TYPES)
 
-export const FORM_FIELD_VALIDATORS_BY_TYPE: { [K in FormFieldType]: (value?: FormResponseValueAnswer[keyof FormResponseValueAnswer], options?: any, isOptional?: boolean) => any } = {
-  'string': stringValidator({ maxLength: 5000, emptyStringOk: true, errorMessage: "Response must not exceed 5000 characters" }),
-  'number': numberValidator({ errorMessage: "Response must be a number" }),
-  'email': emailValidator(),
+export const FORM_FIELD_VALIDATORS_BY_TYPE: { [K in FormFieldType | 'userEmail' | 'phoneNumber']: (value?: FormResponseValueAnswer[keyof FormResponseValueAnswer], options?: any, isOptional?: boolean) => any } = {
+  'string': stringValidator.validate({ maxLength: 5000, emptyStringOk: true, errorMessage: "Response must not exceed 5000 characters" }),
+  'number': numberValidator.validate({ errorMessage: "Response must be a number" }),
+  'email': emailValidator.validate(),
+
+  'userEmail': emailValidator.validate(), 
+  'phone': phoneValidator.validate(),
+  'phoneNumber': phoneValidator.validate(), // backwards compatibility with old field name for phone
 
-  // @ts-ignore -- backwards compatibility with old field name for email
-  'userEmail': emailValidator(), 
-  'phone': phoneValidator(),
-  'phoneNumber': phoneValidator(), // backwards compatibility with old field name for phone
+  "date": dateValidator.validate(),
+  "ranking": listOfStringsValidator.validate(),
+  "rating": numberValidator.validate(),
 
   // fileInfo: FileResponse
   'file': (fileInfo: any, _, isOptional) => {
     if (isOptional && (!fileInfo || object_is_empty(fileInfo))) { 
       return { type: 'file', secureName: null }
     }
-    return fileResponseValidator()(fileInfo)
+    return fileResponseValidator.validate()(fileInfo)
   },
   // sigInfo: SignatureResponse
   
@@ -868,7 +1127,7 @@ export const FORM_FIELD_VALIDATORS_BY_TYPE: { [K in FormFieldType]: (value?: For
     if (isOptional && (!sigInfo || object_is_empty(sigInfo)))  {
       return { type: 'signature', signed: null }
     }
-    return signatureResponseValidator()(sigInfo)
+    return signatureResponseValidator.validate()(sigInfo)
   },
 
   // choiceInfo: { indexes: [], otherText?: string }  
@@ -898,82 +1157,87 @@ export const FORM_FIELD_VALIDATORS_BY_TYPE: { [K in FormFieldType]: (value?: For
     return parsed
    },
 }
-export const fieldsValidator: EscapeBuilder<Indexable<string | CustomField>> = (options={}) => build_validator(
-  (fields: any) => {
-    if (!is_object(fields)) throw new Error("Expecting an object")
-
-    for (const k in fields) {
-      if (DEFAULT_ENDUSER_FIELDS.includes(k)) throw new Error(`key ${k} conflicts with a built-in field.`)
-      if (k.startsWith('_')) throw new Error("Fields that start with '_' are not allowed")
-      if (is_whitespace(k)) {
-        delete fields[k]
-        continue
-      }
+export const fieldsValidator: ValidatorDefinition<Indexable<string | CustomField>> = {
+  validate: (options={}) => build_validator(
+    (fields: any) => {
+      if (!is_object(fields)) throw new Error("Expecting an object")
+
+      for (const k in fields) {
+        if (DEFAULT_ENDUSER_FIELDS.includes(k)) throw new Error(`key ${k} conflicts with a built-in field.`)
+        if (k.startsWith('_')) throw new Error("Fields that start with '_' are not allowed")
+        if (is_whitespace(k)) {
+          delete fields[k]
+          continue
+        }
 
-      if (k.length > 32) throw new Error(`key ${k} is greater than 32 characters`)
-
-      const val = fields[k]
-      if (typeof val === 'string') {
-        if (val.length > 512) fields[k] = val.substring(0, 512)
-        continue
-      } else if (typeof val === 'number' || val === null || typeof val === 'boolean') {
-        continue // nothing to restrict on number type yet
-      } else if (typeof val === 'object') {
-        if (JSON.stringify(val).length > 1024) throw new Error(`object value for key ${k} exceeds the maximum length of 1024 characters in string representation`)
-        // previous restricted structure for fields object
-        // try {
-        //   if (val.type && typeof val.type === 'string') { // form responses can be stored as custom fields (form responses is simple array)
-        //     FORM_FIELD_VALIDATORS_BY_TYPE[val.type as keyof typeof FORM_FIELD_VALIDATORS_BY_TYPE](val, undefined as never, undefined as never)
-        //     continue
-        //   }
-        //   if (val.length && typeof val.length === 'number') { // array of strings is ok too, (inclusive of multiple-choice responses)
-        //     if (val.find((s: any) => typeof s !== 'string') !== undefined) {
-        //       throw new Error('List must contain only strings')
-        //     }
-        //     continue 
-        //   }
-
-        //   if (val.value === undefined) throw new Error(`value field is undefined for key ${k}`)
-        //   if (JSON.stringify(val).length > 1024) throw new Error(`object value for key ${k} exceeds the maximum length of 1024 characters in string representation`)
-
-        //   const escaped = { value: val.value } as Indexable // create new object to omit unrecognized fields
-        //   escaped.title = val.title // optional
-        //   escaped.description = val.description // optional
-        //   fields[k] = escaped
-        // } catch(err) {
-        //   throw new Error(`object value is invalid JSON for key ${k}`)
-        // }
-      } else {
-        throw new Error(`Expecting value to be a string or object but got ${typeof val} for key {k}`)
+        if (k.length > 32) throw new Error(`key ${k} is greater than 32 characters`)
+
+        const val = fields[k]
+        if (typeof val === 'string') {
+          if (val.length > 512) fields[k] = val.substring(0, 512)
+          continue
+        } else if (typeof val === 'number' || val === null || typeof val === 'boolean') {
+          continue // nothing to restrict on number type yet
+        } else if (typeof val === 'object') {
+          if (JSON.stringify(val).length > 1024) throw new Error(`object value for key ${k} exceeds the maximum length of 1024 characters in string representation`)
+          // previous restricted structure for fields object
+          // try {
+          //   if (val.type && typeof val.type === 'string') { // form responses can be stored as custom fields (form responses is simple array)
+          //     FORM_FIELD_VALIDATORS_BY_TYPE[val.type as keyof typeof FORM_FIELD_VALIDATORS_BY_TYPE](val, undefined as never, undefined as never)
+          //     continue
+          //   }
+          //   if (val.length && typeof val.length === 'number') { // array of strings is ok too, (inclusive of multiple-choice responses)
+          //     if (val.find((s: any) => typeof s !== 'string') !== undefined) {
+          //       throw new Error('List must contain only strings')
+          //     }
+          //     continue 
+          //   }
+
+          //   if (val.value === undefined) throw new Error(`value field is undefined for key ${k}`)
+          //   if (JSON.stringify(val).length > 1024) throw new Error(`object value for key ${k} exceeds the maximum length of 1024 characters in string representation`)
+
+          //   const escaped = { value: val.value } as Indexable // create new object to omit unrecognized fields
+          //   escaped.title = val.title // optional
+          //   escaped.description = val.description // optional
+          //   fields[k] = escaped
+          // } catch(err) {
+          //   throw new Error(`object value is invalid JSON for key ${k}`)
+          // }
+        } else {
+          throw new Error(`Expecting value to be a string or object but got ${typeof val} for key {k}`)
+        }
       }
-    }
 
-    return fields
-  }, 
-  { ...options, isObject: true, listOf: false }
-)
+      return fields
+    }, 
+    { ...options, isObject: true, listOf: false }
+  ),
+  getExample: () => `{}`,
+  getType: () => `{}`,
+}
 
 export const preferenceValidator = exactMatchValidator<Preference>(['email', 'sms', 'call', 'chat'])
 
 export const updateOptionsValidator = objectValidator<CustomUpdateOptions>({
-  replaceObjectFields: booleanValidator({ isOptional: true }),
-})
+  replaceObjectFields: booleanValidatorOptional,
+}, { isOptional: true })
 
 export const journeyStatePriorityValidator = exactMatchValidator<JourneyStatePriority>(["Disengaged", "N/A", "Engaged"])
 
 export const journeyStateValidator = objectValidator<JourneyState>({
-  name: stringValidator100(),
-  priority: journeyStatePriorityValidator(),
-  description: stringValidator({ isOptional: true }),
-  requiresFollowup: booleanValidator({ isOptional: true }),
-})
-export const journeyStateUpdateValidator = objectValidator<JourneyState>({
-  name: stringValidator100({ isOptional: true }),
-  priority: journeyStatePriorityValidator({ isOptional: true }),
-  description: stringValidator({ isOptional: true }),
-  requiresFollowup: booleanValidator({ isOptional: true }),
+  name: stringValidator100,
+  priority: journeyStatePriorityValidator, // deprecated
+  description: stringValidatorOptional, // deprecated
+  requiresFollowup: booleanValidatorOptional, // deprecated
 })
-export const journeyStatesValidator = listValidator(journeyStateValidator())
+// deprecated
+// export const journeyStateUpdateValidator = objectValidator<JourneyState>({
+//   name: stringValidator100({ isOptional: true }),
+//   priority: journeyStatePriorityValidator({ isOptional: true }),
+//   description: stringValidator({ isOptional: true }),
+//   requiresFollowup: booleanValidator({ isOptional: true }),
+// })
+export const journeyStatesValidator = listValidator(journeyStateValidator)
 
 export const emailEncodingValidator = exactMatchValidator<EmailEncoding>(['', 'base64'])
 
@@ -991,28 +1255,32 @@ export const validateIndexable = <V>(keyValidator: EscapeFunction<string | numbe
   },
   { ...o, isObject: true, listOf: false }
 )
-export const indexableValidator = <V>(keyValidator: EscapeFunction<string>, valueValidator: EscapeFunction<V>): EscapeBuilder<{ [index: string]: V }> => (
-  validateIndexable(keyValidator, valueValidator)
-)
-export const indexableNumberValidator = <V>(keyValidator: EscapeFunction<number>, valueValidator: EscapeFunction<V>): EscapeBuilder<{ [index: number]: V }> => (
-  validateIndexable(keyValidator, valueValidator)
-)
+export const indexableValidator = <V>(keyValidator: ValidatorDefinition<string>, valueValidator: ValidatorDefinition<V>): ValidatorDefinition<{ [index: string]: V }> => ({
+  validate: validateIndexable(keyValidator.validate(), valueValidator.validate()),
+  getExample: () => `{ ${keyValidator.getExample()}: ${valueValidator.getExample()} }`,
+  getType: () => `{ ${keyValidator.getType()}: ${valueValidator.getType()} }`,
+})
+export const indexableNumberValidator = <V>(keyValidator: ValidatorDefinition<number>, valueValidator: ValidatorDefinition<V>): ValidatorDefinition<{ [index: number]: V }> => ({
+  validate: validateIndexable(keyValidator.validate(), valueValidator.validate()),
+  getExample: () => `{ ${keyValidator.getExample()}: ${valueValidator.getExample()} }`,
+  getType: () => `{ ${keyValidator.getType()}: ${valueValidator.getType()} }`,
+})
 
 export const rejectionWithMessage: EscapeBuilder<undefined> = o => build_validator(
   v => { throw new Error(o?.errorMessage || 'This field is not valid') }, 
   { ...o, isOptional: true, listOf: false, }
 )
 
-export const numberToDateValidator = indexableNumberValidator(numberValidator(), dateValidator())
-export const idStringToDateValidator = indexableValidator(mongoIdStringValidator(), dateValidator())
+export const numberToDateValidator = indexableNumberValidator(numberValidator, dateValidator)
+export const idStringToDateValidator = indexableValidator(mongoIdStringRequired, dateValidator)
 
 // todo: move preference to FIELD_TYPES with drop-down option in user-facing forms
 const FIELD_TYPES = ['string', 'number', 'email', 'phone', 'multiple_choice', 'file', 'signature']
 const VALIDATE_OPTIONS_FOR_FIELD_TYPES = {
   'multiple_choice': {
-    choices: listOfStringsValidator({ maxLength: 100, errorMessage: "Multiple choice options must be under 100 characters, and you must have at least one option." }),
-    radio: booleanValidator({ errorMessage: "radio must be a boolean" }),
-    other: booleanValidator({ isOptional: true, errorMessage: "other must be a boolean" }),
+    choices: listOfStringsValidator,
+    radio: booleanValidator,
+    other: booleanValidatorOptional,
     REQUIRED: ['choices', 'radio'],
   }
 }
@@ -1055,18 +1323,18 @@ const isFormField = (f: JSONType, fieldOptions={ forUpdate: false }) => {
 
 
   if (!forUpdate && !field.type) throw `field.type is required` // fieldName otherwise given as 'field' in validation for every subfield
-  if (field.type) exactMatchValidator(FIELD_TYPES)(field.type)
+  if (field.type) exactMatchValidator(FIELD_TYPES).validate(field.type)
 
   if (!forUpdate && !field.title) throw `field.title is required` // fieldName otherwise given as 'field' in validation for every subfield
   if (field.title) {
-    field.title = stringValidator({ 
+    field.title = stringValidator.validate({ 
       maxLength: 100, 
       errorMessage: "field title is required and must not exceed 100 characters" 
     })(field.title)
   }
 
   if (!forUpdate || field.description !== undefined){ // don't overwrite description on update with ''
-    field.description = stringValidator({ 
+    field.description = stringValidator.validate({ 
       isOptional: true,
       maxLength: 500, 
       errorMessage: "field description must be under 500 characters" 
@@ -1091,7 +1359,7 @@ const isFormField = (f: JSONType, fieldOptions={ forUpdate: false }) => {
       if (validators[k as keyof typeof validators] === undefined) {
         throw new Error(`Got unexpected option ${k} for field of type ${INTERNAL_NAME_TO_DISPLAY_FIELD[field.type as keyof typeof INTERNAL_NAME_TO_DISPLAY_FIELD] || 'Text'}`)
       }
-      field.options[k] = (validators[k as keyof typeof validators] as EscapeFunction)(field.options[k])
+      field.options[k] = (validators[k as keyof typeof validators] as ValidatorDefinition).validate(field.options[k])
     }
   }
 
@@ -1114,59 +1382,60 @@ const isFormField = (f: JSONType, fieldOptions={ forUpdate: false }) => {
 // validate optional vs not at endpoint-level
 export const formResponseAnswerValidator = orValidator<{ [K in FormFieldType]: FormResponseValueAnswer & { type: K } } >({
   email: objectValidator<FormResponseAnswerEmail>({
-    type: exactMatchValidator(['email'])(),
-    value: emailValidator({ isOptional: true, emptyStringOk: true }),
-  })(),
+    type: exactMatchValidator(['email']),
+    value: emailValidatorOptional,
+  }),
   number: objectValidator<FormResponseAnswerNumber>({
-    type: exactMatchValidator(['number'])(),
-    value: numberValidator({ isOptional: true, emptyStringOk: true }), 
-  })(),
+    type: exactMatchValidator(['number']),
+    value: numberValidatorOptional,
+  }),
   rating: objectValidator<FormResponseAnswerRating>({
-    type: exactMatchValidator(['rating'])(),
-    value: numberValidator({ isOptional: true, emptyStringOk: true }), 
-  })(),
+    type: exactMatchValidator(['rating']),
+    value: numberValidatorOptional, 
+  }),
   phone: objectValidator<FormResponseAnswerPhone>({
-    type: exactMatchValidator(['phone'])(),
-    value: phoneValidator({ isOptional: true, emptyStringOk: true }),
-  })(),
+    type: exactMatchValidator(['phone']),
+    value: phoneValidatorOptional,
+  }),
   string: objectValidator<FormResponseAnswerString>({
-    type: exactMatchValidator(['string'])(),
-    value: stringValidator5000({ isOptional: true, emptyStringOk: true }),
-  })(),
+    type: exactMatchValidator(['string']),
+    value: stringValidator5000Optional,
+  }),
   date: objectValidator<FormResponseAnswerDate>({
-    type: exactMatchValidator(['date'])(),
-    value: dateValidator({ isOptional: true, emptyStringOk: true }),
-  })(),
+    type: exactMatchValidator(['date']),
+    value: dateValidatorOptional,
+  }),
   file: objectValidator<FormResponseAnswerFile>({
-    type: exactMatchValidator(['file'])(),
+    type: exactMatchValidator(['file']),
     value: objectValidator<FormResponseAnswerFileValue>({
-      name: stringValidator5000(),
-      secureName: stringValidator250(),
-    }, { emptyOk: false })({ isOptional: true }), 
-  })(),
+      name: stringValidator5000,
+      secureName: stringValidator250,
+    }, { emptyOk: false, isOptional: true }),
+  }),
   multiple_choice: objectValidator<FormResponseAnswerMultipleChoice>({
-    type: exactMatchValidator(['multiple_choice'])(),
-    value: listOfStringsValidator({ isOptional: true, emptyListOk: true }),
-  })(),
+    type: exactMatchValidator(['multiple_choice']),
+    value: listOfStringsValidatorEmptyOk,
+  }),
   ranking: objectValidator<FormResponseAnswerRanking>({
-    type: exactMatchValidator(['ranking'])(),
-    value: listOfStringsValidator({ isOptional: true, emptyListOk: true }),
-  })(),
+    type: exactMatchValidator(['ranking']),
+    value:  listOfStringsValidatorOptionalOrEmptyOk,
+  }),
   signature: objectValidator<FormResponseAnswerSignature>({
-    type: exactMatchValidator(['signature'])(),
+    type: exactMatchValidator(['signature']),
     value: objectValidator<FormResponseAnswerSignatureValue>({
-      fullName: stringValidator250(),
-      signed: booleanValidator(),
-    }, { emptyOk: false })({ isOptional: true }), 
-  })(),
+      fullName: stringValidator250,
+      signed: booleanValidator,
+    }, { emptyOk: false, isOptional: true }),
+  }),
 })
 
 export const formResponseValidator = objectValidator<FormResponseValue>({
   fieldId: mongoIdStringRequired,
-  fieldTitle: stringValidator5000(),
-  answer: formResponseAnswerValidator(),
+  fieldTitle: stringValidator5000,
+  fieldDescription: stringValidator5000Optional,
+  answer: formResponseAnswerValidator,
 })
-export const formResponsesValidator = listValidator(formResponseValidator())
+export const formResponsesValidator = listValidator(formResponseValidator)
 
 export const intakePhoneValidator = exactMatchValidator<'optional' | 'required'>(['optional', 'required'])
 
@@ -1228,10 +1497,10 @@ export const CUD = Object.keys(_CUD) as CUDType[]
 export const CUDStringValidator = exactMatchValidator<CUDType>(CUD)
 
 export const CUDValidator = objectValidator<CUDSubscription>({
-  create: booleanValidator({ isOptional: true }),
-  update: booleanValidator({ isOptional: true }),
-  delete: booleanValidator({ isOptional: true }),
-})
+  create: booleanValidatorOptional,
+  update: booleanValidatorOptional,
+  delete: booleanValidatorOptional,
+}, { isOptional: true })
 
 const _UNIT_OF_TIME: { [K in UnitOfTime]: any } = {
   Days: '',
@@ -1243,9 +1512,9 @@ export const UNITS_OF_TIME = Object.keys(_UNIT_OF_TIME) as UnitOfTime[]
 
 export const UnitOfTimeValidator = exactMatchValidator<UnitOfTime>(UNITS_OF_TIME)
 
-const WebhookSubscriptionValidatorObject = {} as { [K in WebhookSupportedModel]: EscapeFunction<CUDSubscription> } 
+const WebhookSubscriptionValidatorObject = {} as { [K in WebhookSupportedModel]: ValidatorDefinition<CUDSubscription> } 
 for (const model in WEBHOOK_MODELS) {
-  WebhookSubscriptionValidatorObject[model as WebhookSupportedModel] = CUDValidator({ listOf: false, isOptional: true })
+  WebhookSubscriptionValidatorObject[model as WebhookSupportedModel] = CUDValidator
 }
 export const WebhookSubscriptionValidator = objectValidator<{ [K in WebhookSupportedModel]: CUDSubscription}>(
   WebhookSubscriptionValidatorObject,
@@ -1255,15 +1524,15 @@ export const WebhookSubscriptionValidator = objectValidator<{ [K in WebhookSuppo
 export const sessionTypeValidator = exactMatchValidator<SessionType>(['user', 'enduser'])
 
 export const listOfDisplayNameInfo = listValidator(objectValidator<{ fname: string, lname: string, id: string }>({ 
-  fname: nameValidator(), 
-  lname: nameValidator(),
-  id: listOfMongoIdStringValidator(),
-})())
+  fname: nameValidator, 
+  lname: nameValidator,
+  id: listOfMongoIdStringValidator,
+}))
 
 export const attendeeInfoValidator = objectValidator<AttendeeInfo>({
-  AttendeeId: stringValidator(),
-  ExternalUserId: mongoIdStringValidator(),
-  JoinToken: stringValidator(),
+  AttendeeId: stringValidator,
+  ExternalUserId: mongoIdStringRequired,
+  JoinToken: stringValidator,
 })
 
 export const attendeeValidator = objectValidator<{
@@ -1271,55 +1540,55 @@ export const attendeeValidator = objectValidator<{
   id: string,
   info: AttendeeInfo,
 }>({ 
-  type: sessionTypeValidator(),
-  id: mongoIdStringValidator(),
-  info: attendeeInfoValidator(),
+  type: sessionTypeValidator,
+  id: mongoIdStringRequired,
+  info: attendeeInfoValidator,
 }) 
-export const listOfAttendeesValidator = listValidator(attendeeValidator())
+export const listOfAttendeesValidator = listValidator(attendeeValidator)
 export const meetingInfoValidator = objectValidator<{ Meeting: MeetingInfo }>({ 
-  Meeting: objectAnyFieldsAnyValuesValidator(),
+  Meeting: objectAnyFieldsAnyValuesValidator,
 }) 
 
 export const userIdentityValidator = objectValidator<{
   type: SessionType,
   id: string,
 }>({ 
-  type: sessionTypeValidator(),
-  id: mongoIdStringValidator(),
+  type: sessionTypeValidator,
+  id: mongoIdStringRequired,
 }) 
-export const listOfUserIndentitiesValidator = listValidator(userIdentityValidator())
+export const listOfUserIndentitiesValidator = listValidator(userIdentityValidator)
 
 export const chatAttachmentValidator = objectValidator<ChatAttachment>({ 
-  type: exactMatchValidator<ChatAttachmentType>(['image', 'video', 'file'])(),
-  secureName: stringValidator250(),
+  type: exactMatchValidator<ChatAttachmentType>(['image', 'video', 'file']),
+  secureName: stringValidator250,
 }) 
-export const listOfChatAttachmentsValidator = listValidatorEmptyOk(chatAttachmentValidator())
+export const listOfChatAttachmentsValidator = listValidatorEmptyOk(chatAttachmentValidator)
 
 export const meetingsListValidator = listValidator(objectValidator<{
   id: string,
   updatedAt: string,
   status: MeetingStatus,
 }>({
-  id: mongoIdStringValidator(),
-  updatedAt: stringValidator(),
-  status: meetingStatusValidator(),
-})())
+  id: mongoIdStringRequired,
+  updatedAt: stringValidator,
+  status: meetingStatusValidator,
+}))
 
 export const userDisplayInfoValidator = objectValidator<UserDisplayInfo>({
-  id: mongoIdRequired,
-  createdAt: dateValidator(),
-  avatar: stringValidator(),
-  fname: nameValidator(), 
-  lname: nameValidator(),
-  lastActive: dateValidator(),
-  lastLogout: dateValidator(),
-  email: emailValidator(),
+  id: mongoIdStringRequired,
+  createdAt: dateValidator,
+  avatar: stringValidator,
+  fname: nameValidator, 
+  lname: nameValidator,
+  lastActive: dateValidator,
+  lastLogout: dateValidator,
+  email: emailValidator,
 })
-export const meetingDisplayInfoValidator = indexableValidator(mongoIdStringRequired, userDisplayInfoValidator())
+export const meetingDisplayInfoValidator = indexableValidator(mongoIdStringRequired, userDisplayInfoValidator)
 
 export const chatRoomUserInfoValidator = objectAnyFieldsValidator(objectValidator<ChatRoomUserInfo>({
-  unreadCount: nonNegNumberValidator(),
-})())
+  unreadCount: nonNegNumberValidator,
+}))
 
 const _AUTOMATION_ENDUSER_STATUS: { [K in AutomatedActionStatus]: any } = {
   active: '',
@@ -1360,94 +1629,100 @@ export const MESSAGE_TEMPLATE_MODES = Object.keys(_MESSAGE_TEMPLATE_MODES) as Me
 export const messageTemplateModeValidator = exactMatchValidator<MessageTemplateMode>(MESSAGE_TEMPLATE_MODES)
 
 const sharedReminderValidators = {
-  msBeforeStartTime: nonNegNumberValidator(),
-  didRemind: booleanValidator({ isOptional: true }),
+  msBeforeStartTime: nonNegNumberValidator,
+  didRemind: booleanValidatorOptional,
 }
 
 export const calendarEventReminderValidator = orValidator<{ [K in CalendarEventReminderType]: CalendarEventReminderInfoForType[K] } >({
   webhook: objectValidator<CalendarEventReminderInfoForType['webhook']>({
-    info: objectValidator<{}>({}, { emptyOk: true })({ isOptional: true }),
-    type: exactMatchValidator<'webhook'>(['webhook'])(), 
+    info: objectValidator<{}>({}, { emptyOk: true, isOptional: true }),
+    type: exactMatchValidator<'webhook'>(['webhook']), 
     ...sharedReminderValidators, 
-  })(),
+  }),
   'add-to-journey': objectValidator<CalendarEventReminderInfoForType['add-to-journey']>({
     info: objectValidator<CalendarEventReminderInfoForType['add-to-journey']['info']>({
-      journeyId: mongoIdRequired,
-    })(),
-    type: exactMatchValidator<'add-to-journey'>(['add-to-journey'])(), 
+      journeyId: mongoIdStringRequired,
+    }),
+    type: exactMatchValidator<'add-to-journey'>(['add-to-journey']), 
     ...sharedReminderValidators, 
-  })(),
+  }),
   "enduser-notification": objectValidator<CalendarEventReminderInfoForType['enduser-notification']>({
     info: objectValidator<CalendarEventReminderNotificationInfo>({
-      templateId: mongoIdOptional,
-    }, { emptyOk: true })(),
-    type: exactMatchValidator<'enduser-notification'>(['enduser-notification'])(), 
+      templateId: mongoIdStringOptional,
+    }, { emptyOk: true }),
+    type: exactMatchValidator<'enduser-notification'>(['enduser-notification']), 
     ...sharedReminderValidators, 
-  })(),
+  }),
   "user-notification": objectValidator<CalendarEventReminderInfoForType['user-notification']>({
     info: objectValidator<CalendarEventReminderNotificationInfo>({
-      templateId: mongoIdOptional,
-    }, { emptyOk: true })(),
-    type: exactMatchValidator<'user-notification'>(['user-notification'])(), 
+      templateId: mongoIdStringOptional,
+    }, { emptyOk: true }),
+    type: exactMatchValidator<'user-notification'>(['user-notification']), 
     ...sharedReminderValidators, 
-  })(),
+  }),
 })
-export const listOfCalendarEventRemindersValidator = listValidatorEmptyOk(calendarEventReminderValidator())
+export const listOfCalendarEventRemindersValidator = listValidatorEmptyOk(calendarEventReminderValidator)
 
 export const cancelConditionsValidator = listOfObjectsValidator<CancelCondition>({
-  type: exactMatchValidator(['formResponse'])(),
+  type: exactMatchValidator(['formResponse']),
   info: objectValidator<FormSubmitCancellationConditionInfo>({
     automationStepId: mongoIdStringRequired,
-  }, { emptyOk: false })(),
+  }, { emptyOk: false }),
 })
+export const cancelConditionsValidatorOptional = listValidatorOptionalOrEmptyOk(objectValidator<CancelCondition>({
+  type: exactMatchValidator(['formResponse']),
+  info: objectValidator<FormSubmitCancellationConditionInfo>({
+    automationStepId: mongoIdStringRequired,
+  }, { emptyOk: false }),
+}))
 
 const delayValidation = { 
   automationStepId: mongoIdStringRequired, 
-  delayInMS: nonNegNumberValidator(), // use 0 when no delay
-  delay: nonNegNumberValidator(), // for UI only
-  unit: UnitOfTimeValidator(), // for UI only
-  cancelConditions: cancelConditionsValidator({ isOptional: true, emptyListOk: true, })
+  delayInMS: nonNegNumberValidator, // use 0 when no delay
+  delay: nonNegNumberValidator, // for UI only
+  unit: UnitOfTimeValidator, // for UI only
+  cancelConditions: cancelConditionsValidatorOptional,
 }
 
 export const automationEventValidator = orValidator<{ [K in AutomationEventType]: AutomationEvent & { type: K } } >({
   formResponse: objectValidator<FormResponseAutomationEvent>({
-    type: exactMatchValidator(['formResponse'])(),
+    type: exactMatchValidator(['formResponse']),
     info: objectValidator<WithAutomationStepId>({ 
-      automationStepId: mongoIdStringValidator(),
-    }, { emptyOk: false })(),
-  })(),
+      automationStepId: mongoIdStringRequired,
+    }, { emptyOk: false }),
+  }),
   afterAction: objectValidator<AfterActionAutomationEvent>({
-    type: exactMatchValidator(['afterAction'])(),
-    info: objectValidator<AfterActionEventInfo>(delayValidation, { emptyOk: false })(),
-  })(),
+    type: exactMatchValidator(['afterAction']),
+    info: objectValidator<AfterActionEventInfo>(delayValidation, { emptyOk: false }),
+  }),
   formUnsubmitted: objectValidator<FormUnsubmittedEvent>({
-    type: exactMatchValidator(['formUnsubmitted'])(),
+    type: exactMatchValidator(['formUnsubmitted']),
     info: objectValidator<FormUnsubmittedEventInfo>({ 
       ...delayValidation,
       automationStepId: mongoIdStringRequired, 
-    }, { emptyOk: false })(),
-  })(),
+    }, { emptyOk: false }),
+  }),
   onJourneyStart: objectValidator<OnJourneyStartAutomationEvent>({
-    type: exactMatchValidator(['onJourneyStart'])(),
-    info: objectValidator<{}>({ }, { emptyOk: true })(),
-  })(),
+    type: exactMatchValidator(['onJourneyStart']),
+    info: objectValidator<{}>({ }, { emptyOk: true }),
+  }),
   ticketCompleted: objectValidator<TicketCompletedAutomationEvent>({
-    type: exactMatchValidator(['ticketCompleted'])(),
+    type: exactMatchValidator(['ticketCompleted']),
     info: objectValidator<TicketCompletedEventInfo>({ 
       automationStepId: mongoIdStringRequired, 
-      closedForReason: stringValidator({ isOptional: true }),
-    }, { emptyOk: false })(),
-  })(),
+      closedForReason: stringValidatorOptional,
+    }, { emptyOk: false }),
+  }),
 })
-export const automationEventsValidator = listValidatorEmptyOk(automationEventValidator())
+export const automationEventsValidator = listValidatorEmptyOk(automationEventValidator)
 
 export const automationConditionValidator = orValidator<{ [K in AutomationConditionType]: AutomationCondition & { type: K } } >({
   atJourneyState: objectValidator<AtJourneyStateAutomationCondition>({
-    type: exactMatchValidator(['atJourneyState'])(),
-    info: objectValidator<AutomationForJourneyAndState>({ state: stringValidator100(), journeyId: mongoIdStringRequired }, { emptyOk: false })(),
-  })(),
+    type: exactMatchValidator(['atJourneyState']),
+    info: objectValidator<AutomationForJourneyAndState>({ state: stringValidator100, journeyId: mongoIdStringRequired }, { emptyOk: false }),
+  }),
 })
-export const listOfAutomationConditionsValidator = listValidatorEmptyOk(automationConditionValidator())
+export const listOfAutomationConditionsValidator = listValidatorEmptyOk(automationConditionValidator)
 
 const _SEND_FORM_CHANNELS: { [K in SendFormChannel]: any } = {
   Email: '',
@@ -1455,63 +1730,64 @@ const _SEND_FORM_CHANNELS: { [K in SendFormChannel]: any } = {
 }
 export const SEND_FORM_CHANNELS = Object.keys(_SEND_FORM_CHANNELS) as SendFormChannel[]
 export const sendFormChannelValidator = exactMatchValidator<SendFormChannel>(SEND_FORM_CHANNELS)
+export const sendFormChannelValidatorOptional = exactMatchValidatorOptional<SendFormChannel>(SEND_FORM_CHANNELS)
 
 export const automationActionValidator = orValidator<{ [K in AutomationActionType]: AutomationAction & { type: K } } >({
   setEnduserStatus: objectValidator<SetEnduserStatusAutomationAction>({
-    type: exactMatchValidator(['setEnduserStatus'])(),
-    info: objectValidator<SetEnduserStatusInfo>({ status: stringValidator250() }, { emptyOk: false })(),
-  })(),
+    type: exactMatchValidator(['setEnduserStatus']),
+    info: objectValidator<SetEnduserStatusInfo>({ status: stringValidator250 }, { emptyOk: false }),
+  }),
   sendEmail: objectValidator<SendEmailAutomationAction>({
-    type: exactMatchValidator(['sendEmail'])(),
-    info: objectValidator<AutomationForMessage>({ senderId: mongoIdStringValidator(), templateId: mongoIdStringValidator() }, { emptyOk: false })(),
-  })(),
+    type: exactMatchValidator(['sendEmail']),
+    info: objectValidator<AutomationForMessage>({ senderId: mongoIdStringRequired, templateId: mongoIdStringRequired }, { emptyOk: false }),
+  }),
   sendSMS: objectValidator<SendSMSAutomationAction>({
-    type: exactMatchValidator(['sendSMS'])(),
-    info: objectValidator<AutomationForMessage>({ senderId: mongoIdStringValidator(), templateId: mongoIdStringValidator() }, { emptyOk: false })(),
-  })(),
+    type: exactMatchValidator(['sendSMS']),
+    info: objectValidator<AutomationForMessage>({ senderId: mongoIdStringRequired, templateId: mongoIdStringRequired }, { emptyOk: false }),
+  }),
   sendForm: objectValidator<SendFormAutomationAction>({
-    type: exactMatchValidator(['sendForm'])(),
+    type: exactMatchValidator(['sendForm']),
     info: objectValidator<AutomationForFormRequest>({ 
-      senderId: mongoIdStringValidator(), 
-      formId: mongoIdStringValidator(),
-      channel: sendFormChannelValidator({ isOptional: true }),
-    }, { emptyOk: false })(),
-  })(),
+      senderId: mongoIdStringRequired, 
+      formId: mongoIdStringRequired,
+      channel: sendFormChannelValidatorOptional,
+    }, { emptyOk: false }),
+  }),
   createTicket: objectValidator<CreateTicketAutomationAction>({
-    type: exactMatchValidator(['createTicket'])(),
+    type: exactMatchValidator(['createTicket']),
     info: objectValidator<CreateTicketActionInfo>({ 
-      title: stringValidator({ isOptional: false }),
+      title: stringValidatorOptional,
       assignmentStrategy: orValidator<{ [K in CreateTicketAssignmentStrategyType ]: CreateTicketAssignmentStrategy & { type: K } }>({
         'care-team-random': objectValidator<CreateTicketAssignmentStrategy>({ 
-          type: exactMatchValidator<CreateTicketAssignmentStrategyType>(['care-team-random'])(),
-          info: objectValidator<object>({}, { emptyOk: true })(),
-        })()
-      })(), 
-      closeReasons: listOfStringsValidator({ isOptional: true, emptyListOk: true }),
+          type: exactMatchValidator<CreateTicketAssignmentStrategyType>(['care-team-random']),
+          info: objectValidator<object>({}, { emptyOk: true }),
+        })
+      }), 
+      closeReasons: listOfStringsValidatorOptionalOrEmptyOk,
       defaultAssignee: mongoIdStringRequired,
-    }, { emptyOk: false })(),
-  })(),
+    }, { emptyOk: false }),
+  }),
   sendWebhook: objectValidator<SendWebhookAutomationAction>({
-    type: exactMatchValidator(['sendWebhook'])(),
-    info: objectValidator<AutomationForWebhook>({ message: stringValidator5000() }, { emptyOk: false })(),
-  })(),
+    type: exactMatchValidator(['sendWebhook']),
+    info: objectValidator<AutomationForWebhook>({ message: stringValidator5000 }, { emptyOk: false }),
+  }),
 })
 
 export const relatedRecordValidator = objectValidator<RelatedRecord>({
-  type: stringValidator100(),
-  id: mongoIdStringValidator(),
+  type: stringValidator100,
+  id: mongoIdStringRequired,
   creator: mongoIdStringOptional,
 })
-export const listOfRelatedRecordsValidator = listValidatorEmptyOk(relatedRecordValidator())
+export const listOfRelatedRecordsValidator = listValidatorEmptyOk(relatedRecordValidator)
 
 export const searchOptionsValidator = objectValidator<SearchOptions>({
-  query: stringValidator100(),
+  query: stringValidator100,
 })
 
 export const notificationPreferenceValidator = objectValidator<NotificationPreference>({
-  email: booleanValidator({ isOptional: true }),
+  email: booleanValidatorOptional,
 })
-export const notificationPreferencesValidator = objectAnyFieldsValidator(notificationPreferenceValidator())
+export const notificationPreferencesValidator = objectAnyFieldsValidator(notificationPreferenceValidator)
 
 export const FHIRObservationCategoryValidator = exactMatchValidator<ObservationCategory>(['vital-signs'])
 
@@ -1529,42 +1805,42 @@ export const FHIR_OBSERVATION_STATUS_CODES = Object.keys(_FHIR_OBSERVATION_STATU
 export const FHIRObservationStatusCodeValidator = exactMatchValidator<ObservationStatusCode>(FHIR_OBSERVATION_STATUS_CODES)
 
 export const FHIRObservationValueValidator = objectValidator<ObservationValue>({
-  unit: stringValidator(),
-  value: numberValidator(),
+  unit: stringValidator,
+  value: numberValidator,
 })
 
 export const previousFormFieldValidator = orValidator<{ [K in PreviousFormFieldType]: PreviousFormField & { type: K } } >({
   root: objectValidator<PreviousFormFieldRoot>({
-    type: exactMatchValidator(['root'])(),
-    info: objectValidator<{}>({}, { emptyOk: true })(),
-  })(),
+    type: exactMatchValidator(['root']),
+    info: objectValidator<{}>({}, { emptyOk: true }),
+  }),
   "after": objectValidator<PreviousFormFieldAfter>({
-    type: exactMatchValidator(['after'])(),
-    info: objectValidator<PreviousFormFieldAfterInfo>({ fieldId: mongoIdStringRequired }, { emptyOk: false })(),
-  })(),
+    type: exactMatchValidator(['after']),
+    info: objectValidator<PreviousFormFieldAfterInfo>({ fieldId: mongoIdStringRequired }, { emptyOk: false }),
+  }),
   "previousEquals": objectValidator<PreviousFormFieldEquals>({
-    type: exactMatchValidator(['previousEquals'])(),
+    type: exactMatchValidator(['previousEquals']),
     info: objectValidator<PreviousFormFieldEqualsInfo>({ 
       fieldId: mongoIdStringRequired,
-      equals: stringValidator250(),
-    }, { emptyOk: false })(),
-  })(),
+      equals: stringValidator250,
+    }, { emptyOk: false }),
+  }),
 })
-export const previousFormFieldsValidator = listValidatorEmptyOk(previousFormFieldValidator())
+export const previousFormFieldsValidator = listValidatorEmptyOk(previousFormFieldValidator)
 
 export const portalSettingsValidator = objectValidator<PortalSettings>({
 
 })
 
 export const organizationThemeValidator = objectValidator<OrganizationTheme>({
-  logoURL: stringValidator250({ isOptional: true }), // these don't really need to be optional
-  themeColor: stringValidator250({ isOptional: true }), // these don't really need to be optional
-  name: stringValidator250(),
-  subdomain: stringValidator250(),
-  businessId: mongoIdRequired,
-  faviconURL: stringValidator250(),
-  customPortalURL: stringValidator250(),
-  portalSettings: portalSettingsValidator(),
+  logoURL: stringValidatorOptional, // these don't really need to be optional
+  themeColor: stringValidatorOptional, // these don't really need to be optional
+  name: stringValidator250,
+  subdomain: stringValidator250,
+  businessId: mongoIdStringRequired,
+  faviconURL: stringValidator250,
+  customPortalURL: stringValidator250,
+  portalSettings: portalSettingsValidator,
 })
 
 const _MANAGED_CONTENT_RECORD_TYPES: { [K in ManagedContentRecordType]: any } = {
@@ -1575,104 +1851,110 @@ const _MANAGED_CONTENT_RECORD_TYPES: { [K in ManagedContentRecordType]: any } =
 export const MANAGED_CONTENT_RECORD_TYPES = Object.keys(_MANAGED_CONTENT_RECORD_TYPES) as ManagedContentRecordType[]
 export const managedContentRecordTypeValidator = exactMatchValidator<ManagedContentRecordType>(MANAGED_CONTENT_RECORD_TYPES)
 
-export const passwordValidator: EscapeBuilder<string> = (o) =>  build_validator((password) => {
-  if (typeof password !== 'string') {
-    throw new Error("Password must be a string")
-  }
-  if (password.length < 8) {
-    throw new Error("Password must be at least 8 characters long")
-  }
+export const passwordValidator: ValidatorDefinition<string> = {
+  getExample: getExampleString,
+  getType: getTypeString,
+  validate: (
+    (o) => build_validator((password) => {
+      if (typeof password !== 'string') {
+        throw new Error("Password must be a string")
+      }
+      if (password.length < 8) {
+        throw new Error("Password must be at least 8 characters long")
+      }
 
-  if (
-      (password.match(/[a-z]/g)?.length ?? 0) < 1 // 1 lowercase
-  || (
-    (password.match(/[A-Z]/g)?.length ?? 0) < 1 // 1 uppercase
-    && (password.match(/[0-9]/g)?.length ?? 0) < 1 // 1 number
-    && (password.match(/[^a-zA-Z0-9]/g)?.length ?? 0) < 1 // 1 special character
-  )
-  ) {
-  console.error('bad password regex')
-    throw new Error('Password must included 1 uppercase letter, 1 number, or 1 symbol') 
-  }
+      if (
+          (password.match(/[a-z]/g)?.length ?? 0) < 1 // 1 lowercase
+      || (
+        (password.match(/[A-Z]/g)?.length ?? 0) < 1 // 1 uppercase
+        && (password.match(/[0-9]/g)?.length ?? 0) < 1 // 1 number
+        && (password.match(/[^a-zA-Z0-9]/g)?.length ?? 0) < 1 // 1 special character
+      )
+      ) {
+      console.error('bad password regex')
+        throw new Error('Password must included 1 uppercase letter, 1 number, or 1 symbol') 
+      }
 
-  return password 
-}, { ...o, listOf: false, emptyStringOk: false, })
+      return password 
+    }, { ...o, listOf: false, emptyStringOk: false, })
+  ),
+}
 
 export const flowchartUIValidator = objectValidator<FlowchartUI>({
-  x: numberValidator(),
-  y: numberValidator(),
+  x: numberValidator,
+  y: numberValidator,
 }, { emptyOk: true })
 
 
 
 export const integrationAuthenticationsValidator = objectValidator<IntegrationAuthentication>({
-  type: exactMatchValidator(['oauth2'])(),
+  type: exactMatchValidator(['oauth2']),
   info: objectValidator<OAuth2AuthenticationFields>({
-    access_token: stringValidator250(),
-    refresh_token: stringValidator250(),
-    scope: stringValidator5000(),
-    expiry_date: nonNegNumberValidator(),
-    token_type: exactMatchValidator<'Bearer'>(['Bearer'])(),
-    state: stringValidator250({ isOptional: true }),
-    email: emailValidator({ isOptional: true }),
-  })(),
+    access_token: stringValidator250,
+    refresh_token: stringValidator250,
+    scope: stringValidator5000,
+    expiry_date: nonNegNumberValidator,
+    token_type: exactMatchValidator<'Bearer'>(['Bearer']),
+    state: stringValidatorOptional,
+    email: emailValidatorOptional,
+  }),
 })
 
 
 export const formFieldOptionsValidator = objectValidator<FormFieldOptions>({
-  choices: listOfStringsValidator({ isOptional: true }),
-  from: numberValidator({ isOptional: true }),
-  to: numberValidator({ isOptional: true }),
-  other: stringValidator250({ isOptional: true }),
-  radio: booleanValidator({ isOptional: true }),
+  choices: listOfStringsValidatorOptionalOrEmptyOk,
+  from: numberValidatorOptional,
+  to: numberValidatorOptional,
+  other: stringValidatorOptional,
+  radio: booleanValidatorOptional,
 })
 
 export const blockValidator = orValidator<{ [K in BlockType]: Block & { type: K } } >({
   h1: objectValidator<BlockContentH1>({
-    type: exactMatchValidator(['h1'])(),
+    type: exactMatchValidator(['h1']),
     info: objectValidator<BlockContentH1['info']>({
-      text: stringValidator5000({ emptyStringOk: true }),
-    })(),
-  })(),
+      text: stringValidator5000EmptyOkay,
+    }),
+  }),
   h2: objectValidator<BlockContentH2>({
-    type: exactMatchValidator(['h2'])(),
+    type: exactMatchValidator(['h2']),
     info: objectValidator<BlockContentH1['info']>({
-      text: stringValidator5000({ emptyStringOk: true }),
-    })(),
-  })(),
+      text: stringValidator5000EmptyOkay,
+    }),
+  }),
   html: objectValidator<BlockContentHTML>({
-    type: exactMatchValidator(['html'])(),
+    type: exactMatchValidator(['html']),
     info: objectValidator<BlockContentHTML['info']>({
-      html: stringValidator25000({ emptyStringOk: true }),
-    })(),
-  })(),
+      html: stringValidator25000EmptyOkay,
+    }),
+  }),
   image: objectValidator<BlockContentImage>({
-    type: exactMatchValidator(['image'])(),
+    type: exactMatchValidator(['image']),
     info: objectValidator<BlockContentImage['info']>({
-      link: stringValidator5000({ emptyStringOk: true }),
-      name: stringValidator250({ isOptional: true, emptyStringOk: true }),
-      height: nonNegNumberValidator({ isOptional: true }),
-      width: nonNegNumberValidator({ isOptional: true }),
-    })(),
-  })(),
+      link: stringValidator5000EmptyOkay,
+      name: stringValidatorOptional,
+      height: numberValidatorOptional,
+      width: numberValidatorOptional,
+    }),
+  }),
   pdf: objectValidator<BlockContentPDF>({
-    type: exactMatchValidator(['pdf'])(),
+    type: exactMatchValidator(['pdf']),
     info: objectValidator<BlockContentPDF['info']>({
-      link: stringValidator5000({ emptyStringOk: true }),
-      name: stringValidator250({ isOptional: true, emptyStringOk: true }),
-      height: nonNegNumberValidator({ isOptional: true }),
-      width: nonNegNumberValidator({ isOptional: true }),
-    })(),
-  })(),
+      link: stringValidator5000EmptyOkay,
+      name: stringValidatorOptional,
+      height: numberValidatorOptional,
+      width: numberValidatorOptional,
+    }),
+  }),
   youtube: objectValidator<BlockContentYoutube>({
-    type: exactMatchValidator(['youtube'])(),
+    type: exactMatchValidator(['youtube']),
     info: objectValidator<BlockContentYoutube['info']>({
-      link: stringValidator5000({ emptyStringOk: true }),
-      name: stringValidator250({ isOptional: true, emptyStringOk: true }),
-      height: nonNegNumberValidator({ isOptional: true }),
-      width: nonNegNumberValidator({ isOptional: true }),
-    })(),
-  })(),
+      link: stringValidator5000EmptyOkay,
+      name: stringValidatorOptional,
+      height: numberValidatorOptional,
+      width: numberValidatorOptional,
+    }),
+  }),
 })
 
 const _BLOCK_TYPES: { [K in BlockType]: any } = {
@@ -1687,7 +1969,7 @@ export const BLOCK_TYPES = Object.keys(_BLOCK_TYPES) as BlockType[]
 export const blockTypeValidator = exactMatchValidator<BlockType>(BLOCK_TYPES)
 export const is_block_type = (type: any): type is BlockType => BLOCK_TYPES.includes(type)
 
-export const blocksValidator = listValidatorEmptyOk(blockValidator())
+export const blocksValidator = listValidatorEmptyOk(blockValidator)
 
 
 const _DATABASE_RECORD_FIELD_TYPES: { [K in DatabaseRecordFieldType]: any } = {
@@ -1717,33 +1999,33 @@ export const is_database_record_field_type = (type: any): type is DatabaseRecord
 
 // structure as above instead if need unique label or additional config based on type
 export const databaseFieldValidator = objectValidator<DatabaseRecordField>({
-  type: databaseRecordFieldTypeValidator(),
-  label: stringValidator250(),
+  type: databaseRecordFieldTypeValidator,
+  label: stringValidator250,
 })
-export const databaseFieldsValidator = listValidator(databaseFieldValidator())
+export const databaseFieldsValidator = listValidator(databaseFieldValidator)
 
 
 export const databaseRecordValueValidator = orValidator<{ [K in DatabaseRecordFieldType]: DatabaseRecordValues[K] } >({
   string: objectValidator<DatabaseRecordValues['string']>({
-    type: exactMatchValidator(['string'])(),
-    value: stringValidator1000(),
-  })(), 
+    type: exactMatchValidator(['string']),
+    value: stringValidator1000,
+  }), 
   'string-long': objectValidator<DatabaseRecordValues['string-long']>({
-    type: exactMatchValidator(['string-long'])(),
-    value: stringValidator5000(),
-  })(), 
+    type: exactMatchValidator(['string-long']),
+    value: stringValidator5000,
+  }), 
   'number': objectValidator<DatabaseRecordValues['number']>({
-    type: exactMatchValidator(['number'])(),
-    value: numberValidator(),
-  })(), 
+    type: exactMatchValidator(['number']),
+    value: numberValidator,
+  }), 
 })
-export const databaseRecordValuesValidator = listValidator(databaseRecordValueValidator())
+export const databaseRecordValuesValidator = listValidator(databaseRecordValueValidator)
 
 export const organizationAccessValidator = objectValidator<OrganizationAccess>({
-  create: booleanValidator({ isOptional: true }),
-  update: booleanValidator({ isOptional: true }),
-  read: booleanValidator({ isOptional: true }),
-  delete: booleanValidator({ isOptional: true }),
+  create: booleanValidatorOptional,
+  update: booleanValidatorOptional,
+  read: booleanValidatorOptional,
+  delete: booleanValidatorOptional,
 })
 
 const _PORTAL_PAGES: { [K in PortalPage]: any } = {
@@ -1760,33 +2042,33 @@ export const portalPageValidator = exactMatchValidator<PortalPage>(PORTAL_PAGES)
 
 export const portalBlockValidator = orValidator<{ [K in PortalBlockType]: PortalBlockForType[K] } >({
   carePlan: objectValidator<PortalBlockForType['carePlan']>({
-    type: exactMatchValidator(['carePlan'])(),
-    info: objectValidator<PortalBlockForType['carePlan']['info']>({}, { emptyOk: true })()
-  })(), 
+    type: exactMatchValidator(['carePlan']),
+    info: objectValidator<PortalBlockForType['carePlan']['info']>({}, { emptyOk: true })
+  }), 
   education: objectValidator<PortalBlockForType['education']>({
-    type: exactMatchValidator(['education'])(),
-    info: objectValidator<PortalBlockForType['education']['info']>({}, { emptyOk: true })()
-  })(), 
+    type: exactMatchValidator(['education']),
+    info: objectValidator<PortalBlockForType['education']['info']>({}, { emptyOk: true })
+  }), 
   careTeam: objectValidator<PortalBlockForType['careTeam']>({
-    type: exactMatchValidator(['careTeam'])(),
+    type: exactMatchValidator(['careTeam']),
     info: objectValidator<PortalBlockForType['careTeam']['info']>({
-      title: stringValidator(),
+      title: stringValidator,
       // members: listValidatorEmptyOk(
       //   objectValidator<CareTeamMemberPortalCustomizationInfo>({
       //     title: stringValidator(),
       //     role: stringValidator({ isOptional: true }),
       //   })()
       // )()
-    })()
-  })(), 
+    })
+  }), 
   text: objectValidator<PortalBlockForType['text']>({
-    type: exactMatchValidator(['text'])(),
+    type: exactMatchValidator(['text']),
     info: objectValidator<PortalBlockForType['text']['info']>({
-      text: stringValidator5000(),
-    })()
-  })(), 
+      text: stringValidator5000,
+    })
+  }), 
 })
-export const portalBlocksValidator = listValidatorEmptyOk(portalBlockValidator())
+export const portalBlocksValidator = listValidatorEmptyOk(portalBlockValidator)
 
 const _PORTAL_BLOCK_TYPES: { [K in PortalBlockType]: any } = {
   carePlan: '',
@@ -1802,14 +2084,14 @@ export const enduserTaskForEventValidator = objectValidator<EnduserTaskForEvent>
   id: mongoIdStringRequired,
   enduserId: mongoIdStringRequired,
 })
-export const enduserTasksForEventValidator = listValidatorEmptyOk(enduserTaskForEventValidator())
+export const enduserTasksForEventValidator = listValidatorEmptyOk(enduserTaskForEventValidator)
 
 export const enduserFormResponseForEventValidator = objectValidator<EnduserFormResponseForEvent>({
   enduserId: mongoIdStringRequired,
   formId: mongoIdStringRequired,
-  accessCode: stringValidator1000(),
+  accessCode: stringValidator1000,
 })
-export const enduserFormResponsesForEventValidator = listValidatorEmptyOk(enduserFormResponseForEventValidator())
+export const enduserFormResponsesForEventValidator = listValidatorEmptyOk(enduserFormResponseForEventValidator)
 
 export const VALID_STATES: string[] = [
   "AK", 
@@ -1873,23 +2155,23 @@ export const VALID_STATES: string[] = [
 export const stateValidator = exactMatchValidator(VALID_STATES)
 
 export const stateCredentialValidator = objectValidator<StateCredentialInfo>({
-  expiresAt: dateValidator({ isOptional: true }),
-  state: stateValidator(),
+  expiresAt: dateValidatorOptional,
+  state: stateValidator,
 })
-export const stateCredentialsValidator = listValidatorEmptyOk(stateCredentialValidator())
+export const stateCredentialsValidator = listValidatorEmptyOk(stateCredentialValidator)
 
 export const availabilityBlockValidator = objectValidator<AvailabilityBlock>({
-  durationInMinutes: nonNegNumberValidator(),
-  startTimeInMS: nonNegNumberValidator(),
+  durationInMinutes: nonNegNumberValidator,
+  startTimeInMS: nonNegNumberValidator,
   userId: mongoIdStringRequired,
 })
-export const availabilityBlocksValidator = listValidatorEmptyOk(availabilityBlockValidator())
+export const availabilityBlocksValidator = listValidatorEmptyOk(availabilityBlockValidator)
 
 export const weeklyAvailabilityValidator = objectValidator<WeeklyAvailability>({
-  dayOfWeekStartingSundayIndexedByZero: nonNegNumberValidator(),
-  endTimeInMinutes: nonNegNumberValidator(),
-  startTimeInMinutes: nonNegNumberValidator(),
+  dayOfWeekStartingSundayIndexedByZero: nonNegNumberValidator,
+  endTimeInMinutes: nonNegNumberValidator,
+  startTimeInMinutes: nonNegNumberValidator,
 })
-export const weeklyAvailabilitiesValidator = listValidatorEmptyOk(weeklyAvailabilityValidator())
+export const weeklyAvailabilitiesValidator = listValidatorEmptyOk(weeklyAvailabilityValidator)
 
 export const timezoneValidator = exactMatchValidator<Timezone>(Object.keys(TIMEZONES) as Timezone[])