@defra/forms-model 3.0.703 → 3.0.704

package/schemas/form-definition-v2-schema.json

@@ -143,42 +143,6 @@
       "additionalProperties": false,
       "title": "Output"
     },
-    "outputs": {
-      "type": "array",
-      "description": "One or more email targets/types for submission emails",
-      "items": {
-        "type": "object",
-        "properties": {
-          "emailAddress": {
-            "type": "string",
-            "description": "Email address where form submissions are sent",
-            "format": "email",
-            "title": "Email Address"
-          },
-          "audience": {
-            "type": "string",
-            "description": "Target audience for the output (human readable or machine processable)",
-            "enum": [
-              "human",
-              "machine"
-            ],
-            "title": "Audience"
-          },
-          "version": {
-            "type": "string",
-            "description": "Version identifier for the output format",
-            "title": "Version"
-          }
-        },
-        "required": [
-          "audience",
-          "version"
-        ],
-        "additionalProperties": false,
-        "title": "Outputs Item"
-      },
-      "title": "Outputs"
-    },
     "schema": {
       "description": "Form schema version to use (2)",
       "const": 2,
@@ -2441,9 +2405,72 @@
         "title": "Sections Item"
       },
       "title": "Sections"
+    },
+    "outputs": {
+      "type": "array",
+      "description": "Outputs schema for V2 forms",
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "description": "Configuration for a single submission email target",
+        "properties": {
+          "emailAddress": {
+            "type": "string",
+            "description": "Email address where form submissions are sent",
+            "format": "email",
+            "title": "Email Address"
+          },
+          "audience": {
+            "type": "string",
+            "description": "Target audience for the output (human readable or machine processable)",
+            "enum": [
+              "human",
+              "machine"
+            ],
+            "title": "Audience"
+          },
+          "version": {
+            "type": "string",
+            "description": "Version identifier for the output format",
+            "title": "Version"
+          },
+          "condition": {
+            "type": [
+              "array",
+              "boolean",
+              "number",
+              "object",
+              "string",
+              "null"
+            ],
+            "description": "Optional condition that determines if submissions are sent to this output",
+            "enum": [
+              "",
+              {
+                "ref": {
+                  "path": [
+                    "conditions"
+                  ],
+                  "ancestor": "root",
+                  "in": true
+                }
+              }
+            ],
+            "title": "Condition"
+          }
+        },
+        "required": [
+          "audience",
+          "version"
+        ],
+        "additionalProperties": false,
+        "title": "Outputs Item"
+      },
+      "title": "Outputs"
     }
   },
   "required": [
+    "schema",
     "pages",
     "sections"
   ],

package/src/form/form-audit/index.ts

@@ -54,6 +54,7 @@ import {
   type FormUploadedMessageData,
   type FormsBackupRequestedMessageData
 } from '~/src/form/form-audit/types.js'
+import { type Output } from '~/src/form/form-definition/types.js'
 import { emailAddressNoUnicodeSchema } from '~/src/form/form-editor/index.js'
 import {
   contactSchema,
@@ -102,6 +103,37 @@ export const formDefinitionS3Meta = Joi.object<FormDefinitionS3Meta>()
   })
   .description('Schema for form data S3 object in message')
 
+/**
+ * Stands apart from the definition's own output schema, which resolves a
+ * condition against the sibling `conditions` array - a lookup that has no
+ * meaning on an audit message carrying the output on its own.
+ */
+export const formOutputMessageData = Joi.object<Output>()
+  .keys({
+    emailAddress: emailAddressNoUnicodeSchema
+      .required()
+      .description('Email address the submission is sent to'),
+    audience: Joi.string()
+      .trim()
+      .valid('human', 'machine')
+      .required()
+      .description(
+        'Whether the submission is sent human readable or machine processable'
+      ),
+    version: Joi.string()
+      .trim()
+      .required()
+      .description('Version identifier of the output format'),
+    condition: Joi.string()
+      .trim()
+      .allow('')
+      .optional()
+      .description(
+        'Id of the condition determining whether the submission is sent to this address'
+      )
+  })
+  .description('A submission email target as recorded on an audit event')
+
 export const formUpdatedMessageData = formMessageDataBase
   .append<FormUpdatedMessageData>({
     requestType: Joi.string()

package/src/form/form-definition/helpers.ts

@@ -1,7 +1,10 @@
 import { ComponentType } from '~/src/components/enums.js'
 import { type ComponentDef } from '~/src/components/types.js'
 import { type ConditionListItemRefValueDataV2 } from '~/src/conditions/types.js'
-import { type FormDefinition } from '~/src/form/form-definition/types.js'
+import {
+  type FormDefinition,
+  type Output
+} from '~/src/form/form-definition/types.js'
 import { type ControllerType } from '~/src/pages/enums.js'
 import { hasComponents } from '~/src/pages/helpers.js'
 
@@ -81,6 +84,34 @@ export function getHiddenFields(definition: FormDefinition) {
   return totalHiddenFields
 }
 
+/**
+ * Builds the key identifying a submission email target. Two outputs sharing a
+ * key would send the same format of the same submission to the same inbox in
+ * the same circumstances, so one of them is redundant. Addresses are compared
+ * case-insensitively and a missing condition is treated as an empty one.
+ * @param output - submission email target
+ */
+export function getOutputKey(output: Partial<Output>): string {
+  return [
+    output.emailAddress?.trim().toLowerCase() ?? '',
+    output.condition?.trim() ?? '',
+    output.audience ?? '',
+    output.version?.trim() ?? ''
+  ].join('|')
+}
+
+/**
+ * Whether two submission email targets are duplicates of one another
+ * @param output - submission email target
+ * @param otherOutput - submission email target to compare against
+ */
+export function isDuplicateOutput(
+  output: Partial<Output>,
+  otherOutput: Partial<Output>
+): boolean {
+  return getOutputKey(output) === getOutputKey(otherOutput)
+}
+
 /**
  * @param definition - form definition
  * @returns {boolean}

package/src/form/form-definition/index.ts

@@ -40,6 +40,7 @@ import {
 } from '~/src/form/form-definition/constants.js'
 import {
   isConditionListItemRefValueData,
+  isDuplicateOutput,
   isFormDefinition
 } from '~/src/form/form-definition/helpers.js'
 import {
@@ -53,6 +54,7 @@ import {
   type Item,
   type Link,
   type List,
+  type Output,
   type Page,
   type PhaseBanner,
   type Repeat,
@@ -1197,6 +1199,66 @@ const outputSchema = Joi.object<FormDefinition['output']>()
       .description('Version identifier for the output format')
   })
 
+const outputsItemSchema = Joi.object<Output>()
+  .description('Configuration for a single submission email target')
+  .keys({
+    emailAddress: emailAddressNoUnicodeSchema.description(
+      'Email address where form submissions are sent'
+    ),
+    audience: Joi.string()
+      .trim()
+      .valid('human', 'machine')
+      .required()
+      .description(
+        'Target audience for the output (human readable or machine processable)'
+      ),
+    version: Joi.string()
+      .trim()
+      .required()
+      .description('Version identifier for the output format')
+  })
+
+const outputsItemSchemaV2 = outputsItemSchema.keys({
+  condition: Joi.string()
+    .trim()
+    .allow('')
+    .optional()
+    .when('/conditions', {
+      is: Joi.exist(),
+      then: Joi.valid('', conditionIdRef)
+    })
+    .description(
+      'Optional condition that determines if submissions are sent to this output'
+    )
+    .error(checkErrors(FormDefinitionError.RefOutputCondition))
+})
+
+const outputsSchema = Joi.array<Output>()
+  .items(outputsItemSchema)
+  .unique(isDuplicateOutput)
+  // Without this the raw Joi message names the array index, eg `"outputs[4]"
+  // contains a duplicate value`, which means nothing to a form author
+  .messages({
+    'array.unique':
+      'Email address {{#value.emailAddress}} is already receiving the same submissions'
+  })
+  .optional()
+  .description('One or more email targets/types for submission emails')
+  .error(checkErrors(FormDefinitionError.UniqueOutput))
+
+const outputsSchemaV2 = Joi.array<Output>()
+  .items(outputsItemSchemaV2)
+  .unique(isDuplicateOutput)
+  // Without this the raw Joi message names the array index, eg `"outputs[4]"
+  // contains a duplicate value`, which means nothing to a form author
+  .messages({
+    'array.unique':
+      'Email address {{#value.emailAddress}} is already receiving the same submissions'
+  })
+  .optional()
+  .description('Outputs schema for V2 forms')
+  .error(checkErrors(FormDefinitionError.UniqueOutput))
+
 /**
  * Joi schema for `FormDefinition` interface
  * @see {@link FormDefinition}
@@ -1271,31 +1333,12 @@ export const formDefinitionSchema = Joi.object<FormDefinition>()
       .description('Phase banner configuration'),
     options: optionsSchema.optional().description('Options for the form'),
     outputEmail: emailAddressNoUnicodeSchema
-      .email({ tlds: { allow: ['uk'] } })
       .optional()
       .description('Email address where form submissions are sent'),
     output: outputSchema
       .optional()
       .description('Configuration for submission output format'),
-    outputs: Joi.array()
-      .items({
-        emailAddress: emailAddressNoUnicodeSchema
-          .email({ tlds: { allow: ['uk'] } })
-          .description('Email address where form submissions are sent'),
-        audience: Joi.string()
-          .trim()
-          .valid('human', 'machine')
-          .required()
-          .description(
-            'Target audience for the output (human readable or machine processable)'
-          ),
-        version: Joi.string()
-          .trim()
-          .required()
-          .description('Version identifier for the output format')
-      })
-      .optional()
-      .description('One or more email targets/types for submission emails')
+    outputs: outputsSchema
   })
 
 export const formDefinitionV2Schema = formDefinitionSchema
@@ -1303,6 +1346,7 @@ export const formDefinitionV2Schema = formDefinitionSchema
     schema: Joi.number()
       .integer()
       .valid(SchemaVersion.V2)
+      .required()
       .description('Form schema version to use (2)'),
     pages: Joi.array<Page>()
       .items(pageSchemaV2)
@@ -1353,7 +1397,8 @@ export const formDefinitionV2Schema = formDefinitionSchema
           FormDefinitionError.UniqueSectionName,
           FormDefinitionError.UniqueSectionTitle
         ])
-      )
+      ),
+    outputs: outputsSchemaV2
   })
   .description('Form definition schema for V2')
 

package/src/form/form-definition/types.ts

@@ -188,6 +188,11 @@ export interface Output {
   audience: OutputAudience
   version: string
   emailAddress: string
+  /**
+   * Id of the condition determining whether submissions are sent to this
+   * output. V2 only - rejected by the V1 schema.
+   */
+  condition?: string
 }
 
 export interface FormOptions {

package/src/form/form-manager/errors.ts

@@ -30,10 +30,12 @@ export const checkErrors = (
         const keyMatch =
           typeof err.local.key === 'number' ? err.local.path : err.local.key
 
+        // An empty key matches any unique constraint for schemas whose
+        // uniqueness is a composite of several keys rather than a single one
         if (
           errorDetails.type === FormDefinitionErrorType.Unique &&
           err.code === 'array.unique' &&
-          keyMatch === errorDetails.key
+          (errorDetails.key === '' || keyMatch === errorDetails.key)
         ) {
           err.local.errorCode = formError
           err.local.errorType = FormDefinitionErrorType.Unique
@@ -172,6 +174,8 @@ export const formErrorsToMessages: Record<FormDefinitionError, string> = {
     'Each item in a list must have unique text. Change the item text to one that is not already used.',
   [FormDefinitionError.UniqueListItemValue]:
     'Each item in a list must have a unique value. Change the item value to one that is not already used.',
+  [FormDefinitionError.UniqueOutput]:
+    'This email address is already receiving the same submissions. Change the address, condition or format, or remove the duplicate.',
   [FormDefinitionError.RefPageCondition]:
     'This page is referenced by a condition. Remove the condition before making changes to this page.',
   [FormDefinitionError.RefConditionComponentId]:
@@ -184,6 +188,8 @@ export const formErrorsToMessages: Record<FormDefinitionError, string> = {
     'A condition is using another condition. Remove the reference before making changes.',
   [FormDefinitionError.RefPageComponentList]:
     'A question on this page is using a list. Remove the reference before making changes to the list.',
+  [FormDefinitionError.RefOutputCondition]:
+    'A submission email is using a condition that does not exist in this form. Select an existing condition or remove it.',
   [FormDefinitionError.IncompatibleConditionComponentType]:
     'You cannot change to this question type because this question is used in a condition. Remove the condition or select a different question type.',
   [FormDefinitionError.IncompatibleQuestionRegex]:

package/src/form/form-manager/types.ts

@@ -45,12 +45,14 @@ export enum FormDefinitionError {
   UniqueListItemId = 'unique_list_item_id',
   UniqueListItemText = 'unique_list_item_text',
   UniqueListItemValue = 'unique_list_item_value',
+  UniqueOutput = 'unique_output',
   RefPageCondition = 'ref_page_condition',
   RefConditionComponentId = 'ref_condition_component_id',
   RefConditionListId = 'ref_condition_list_id',
   RefConditionItemId = 'ref_condition_item_id',
   RefConditionConditionId = 'ref_condition_condition_id',
   RefPageComponentList = 'ref_page_component_list',
+  RefOutputCondition = 'ref_output_condition',
   IncompatibleConditionComponentType = 'incompatible_condition_component_type',
   IncompatibleQuestionRegex = 'incompatible_question_regex',
   Other = 'other'
@@ -125,6 +127,13 @@ export const formDefinitionErrors: FormDefinitionErrors = {
     key: 'value',
     type: FormDefinitionErrorType.Unique
   },
+  [FormDefinitionError.UniqueOutput]: {
+    // Outputs are compared on a composite of their address, condition,
+    // audience and version, so there is no single key to match on. An empty
+    // key matches any unique constraint on the schema it is attached to.
+    key: '',
+    type: FormDefinitionErrorType.Unique
+  },
   [FormDefinitionError.RefPageCondition]: {
     key: 'condition',
     type: FormDefinitionErrorType.Ref
@@ -149,6 +158,10 @@ export const formDefinitionErrors: FormDefinitionErrors = {
     key: 'list',
     type: FormDefinitionErrorType.Ref
   },
+  [FormDefinitionError.RefOutputCondition]: {
+    key: 'condition',
+    type: FormDefinitionErrorType.Ref
+  },
   [FormDefinitionError.IncompatibleConditionComponentType]: {
     key: 'componentId',
     type: FormDefinitionErrorType.Incompatible

package/src/form/form-submission/enums.ts

@@ -19,3 +19,29 @@ export enum SubmissionEventMessageSource {
 export enum SubmissionEventMessageType {
   RUNNER_SAVE_AND_EXIT = 'RUNNER_SAVE_AND_EXIT'
 }
+
+/**
+ * The outcome of evaluating a single form condition.
+ *
+ * `Error` is deliberately distinct from `False`. The runner defaults a failed
+ * evaluation to `false` when routing, but for an audit record the two are not
+ * the same thing and a consumer must be able to tell them apart.
+ */
+export enum ConditionEvaluationOutcome {
+  /**
+   * The condition evaluated to `true`
+   */
+  True = 'true',
+
+  /**
+   * The condition evaluated to `false`
+   */
+  False = 'false',
+
+  /**
+   * Evaluation threw - most commonly because the condition references a
+   * component that is absent from the evaluation context, such as a component
+   * on a repeater page. The runner treats this as `false`.
+   */
+  Error = 'error'
+}

package/src/form/form-submission/index.ts

@@ -2,6 +2,7 @@ import Joi from 'joi'
 
 import { FormStatus } from '~/src/common/enums.js'
 import {
+  ConditionEvaluationOutcome,
   SecurityQuestionsEnum,
   SubmissionEventMessageCategory,
   SubmissionEventMessageSchemaVersion,
@@ -11,6 +12,8 @@ import {
 import {
   type SaveAndExitMessage,
   type SaveAndExitMessageData,
+  type SubmitConditionEvaluation,
+  type SubmitConditionReference,
   type SubmitPayload,
   type SubmitRecord,
   type SubmitRecordset
@@ -61,6 +64,52 @@ export const formSubmitRecordsetSchema = Joi.object<SubmitRecordset>({
   .label('FormSubmitRecordset')
   .description('Collection of repeated field values from a repeatable section')
 
+/**
+ * Joi schema for `SubmitConditionReference` interface
+ * @see {@link SubmitConditionReference}
+ */
+export const formSubmitConditionReferenceSchema =
+  Joi.object<SubmitConditionReference>({
+    componentId: Joi.string()
+      .required()
+      .description('Identifier of the component the condition depends on'),
+    componentName: Joi.string()
+      .required()
+      .description(
+        'Name of the component the condition depends on, matching the submitted record name'
+      ),
+    answered: Joi.boolean()
+      .required()
+      .description(
+        'Whether the component held an answer when the condition was evaluated'
+      )
+  })
+    .label('FormSubmitConditionReference')
+    .description('A component a condition depends on, and its answered state')
+
+/**
+ * Joi schema for `SubmitConditionEvaluation` interface
+ * @see {@link SubmitConditionEvaluation}
+ */
+export const formSubmitConditionEvaluationSchema =
+  Joi.object<SubmitConditionEvaluation>({
+    conditionId: Joi.string()
+      .required()
+      .description('Identifier of the condition in the V2 form definition'),
+    outcome: Joi.string()
+      .valid(...Object.values(ConditionEvaluationOutcome))
+      .required()
+      .description('Result of evaluating the condition'),
+    references: Joi.array<SubmitConditionReference>()
+      .items(formSubmitConditionReferenceSchema)
+      .required()
+      .description(
+        'Components the condition depends on, including those reached through nested condition references'
+      )
+  })
+    .label('FormSubmitConditionEvaluation')
+    .description('Recorded outcome of a single condition at submission')
+
 /**
  * Joi schema for `SubmitPayload` interface
  * @see {@link SubmitPayload}

package/src/form/form-submission/types.ts

@@ -1,5 +1,6 @@
 import { type FormStatus } from '~/src/common/enums.js'
 import {
+  type ConditionEvaluationOutcome,
   type SecurityQuestionsEnum,
   type SubmissionEventMessageCategory,
   type SubmissionEventMessageSchemaVersion,
@@ -7,6 +8,8 @@ import {
   type SubmissionEventMessageType
 } from '~/src/form/form-submission/enums.js'
 import {
+  formSubmitConditionEvaluationSchema,
+  formSubmitConditionReferenceSchema,
   formSubmitPayloadSchema,
   formSubmitRecordSchema,
   formSubmitRecordsetSchema
@@ -54,6 +57,57 @@ export interface SubmitRecordset {
   value: SubmitRecord[][]
 }
 
+/**
+ * A component referenced by a condition, and whether the user had answered it
+ * when the condition was evaluated.
+ *
+ * An unanswered question is not absent from the runner's evaluation context -
+ * it is present as `null` - so conditions still return a boolean for questions
+ * that were skipped or never reached. Negative operators ("is not", "is shorter
+ * than") return `true` in that case. Without knowing which referenced questions
+ * were answered, a consumer cannot tell a real match from a vacuous one.
+ * @see {@link formSubmitConditionReferenceSchema}
+ */
+export interface SubmitConditionReference {
+  /**
+   * The id of the referenced component
+   */
+  componentId: string
+
+  /**
+   * The name of the referenced component, as used in the submitted records
+   */
+  componentName: string
+
+  /**
+   * Whether the referenced component held an answer at the point of evaluation
+   */
+  answered: boolean
+}
+
+/**
+ * The recorded outcome of a single condition at the point of submission.
+ * V2 forms only - V1 conditions are not captured.
+ * @see {@link formSubmitConditionEvaluationSchema}
+ */
+export interface SubmitConditionEvaluation {
+  /**
+   * The id of the condition, as authored in the V2 form definition
+   */
+  conditionId: string
+
+  /**
+   * The result of evaluating the condition
+   */
+  outcome: ConditionEvaluationOutcome
+
+  /**
+   * Every component the condition depends on, including those reached through
+   * nested condition references, and whether each was answered
+   */
+  references: SubmitConditionReference[]
+}
+
 /**
  * Interface for the submission-api `/submit` payload
  * @see {@link formSubmitPayloadSchema}