@defra/forms-model 3.0.430 → 3.0.431

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

@@ -17,6 +17,8 @@ export enum QuestionTypeSubGroup {
 export const pageTypeSchema = Joi.string()
   .required()
   .valid('question', 'guidance')
+  .description('Type of page - either a question page or guidance page')
+
 export const questionTypeSchema = Joi.string()
   .required()
   .valid(
@@ -32,6 +34,7 @@ export const questionTypeSchema = Joi.string()
     ComponentType.RadiosField,
     ComponentType.AutocompleteField
   )
+  .description('The high-level type of question, including grouped types')
 
 export const questionTypeFullSchema = Joi.string()
   .required()
@@ -50,6 +53,7 @@ export const questionTypeFullSchema = Joi.string()
     ComponentType.RadiosField,
     ComponentType.AutocompleteField
   )
+  .description('The specific component type to use for this question')
 
 export const writtenAnswerSubSchema = Joi.string()
   .required()
@@ -58,6 +62,8 @@ export const writtenAnswerSubSchema = Joi.string()
     ComponentType.MultilineTextField,
     ComponentType.NumberField
   )
+  .description('Subtype for written answer questions')
+
 export const dateSubSchema = Joi.string()
   .required()
   .valid(ComponentType.DatePartsField, ComponentType.MonthYearField)
@@ -69,60 +75,221 @@ export const listSubSchema = Joi.string()
     ComponentType.RadiosField,
     ComponentType.AutocompleteField
   )
+  .description('Subtype for date-related questions')
+
+export const nameSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Unique identifier for the field')
+
+export const questionSchema = Joi.string()
+  .trim()
+  .required()
+  .description('The question text displayed to the user')
+
+export const hintTextSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Optional guidance text displayed below the question')
 
-export const nameSchema = Joi.string().trim().required()
-export const questionSchema = Joi.string().trim().required()
-export const hintTextSchema = Joi.string().trim().optional().allow('')
 export const questionOptionalSchema = Joi.string()
   .trim()
   .optional()
   .valid('', 'true')
-export const shortDescriptionSchema = Joi.string().trim().required()
-export const pageHeadingAndGuidanceSchema = Joi.string().trim().optional()
-export const pageHeadingSchema = Joi.string().trim().required()
-export const guidanceTextSchema = Joi.string().trim()
-export const needDeclarationSchema = Joi.string().trim().required()
-export const declarationTextSchema = Joi.string().trim().required()
-export const exactFilesSchema = Joi.number().empty('').integer().min(1).max(25)
-export const minFilesSchema = Joi.number().empty('').integer().min(0).max(25)
-export const maxFilesSchema = Joi.number().empty('').integer().min(1).max(25)
-export const minSchema = Joi.number().empty('').integer()
-export const maxSchema = Joi.number().empty('').integer()
-export const minLengthSchema = Joi.number().empty('').integer().min(1)
-export const maxLengthSchema = Joi.number().empty('').integer().min(1)
-export const maxFutureSchema = Joi.number().empty('').integer().min(0)
-export const maxPastSchema = Joi.number().empty('').integer().min(0)
-export const precisionSchema = Joi.number().empty('').integer().min(0).max(5)
-export const prefixSchema = Joi.string().trim().optional().allow('')
-export const regexSchema = Joi.string().optional().allow('')
-export const rowsSchema = Joi.number().empty('').integer().min(1)
-export const suffixSchema = Joi.string().trim().optional().allow('')
-export const classesSchema = Joi.string().trim().optional().allow('')
+  .description(
+    'Indicates whether a question is optional. Empty string or "true" values are accepted.'
+  )
+
+export const exactFilesSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .max(25)
+  .description(
+    'Specifies the exact number of files required for upload. Must be between 1 and 25.'
+  )
+
+export const minFilesSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(0)
+  .max(25)
+  .description(
+    'Minimum number of files required for upload. Must be between 0 and 25.'
+  )
+
+export const maxFilesSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .max(25)
+  .description(
+    'Maximum number of files allowed for upload. Must be between 1 and 25.'
+  )
+
 export const fileTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
+  .description(
+    'Array of allowed file types. Can be provided as a single value or an array.'
+  )
+
 export const documentTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
+  .description(
+    'Array of allowed document types. Can be provided as a single value or an array.'
+  )
+
 export const imageTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
+  .description(
+    'Array of allowed image types. Can be provided as a single value or an array.'
+  )
+
 export const tabularDataTypesSchema = Joi.array()
   .items(Joi.string())
   .single()
   .empty(null)
   .default([])
-export const enhancedActionSchema = Joi.string().trim().optional().allow('')
-export const radioIdSchema = Joi.string().trim().optional().allow('')
-export const radioLabelSchema = Joi.string().trim().required()
-export const radioHintSchema = Joi.string().trim().optional().allow('')
-export const radioValueSchema = Joi.string().trim().optional().allow('')
+export const enhancedActionSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Action field that can include enhanced functionality')
+
+export const radioIdSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Unique identifier for radio options')
+
+export const radioLabelSchema = Joi.string()
+  .trim()
+  .required()
+  .description('The visible text shown next to radio options')
+
+export const radioHintSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description(
+    'Optional hint text displayed with radio buttons to provide additional guidance'
+  )
+
+export const radioValueSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description(
+    'Array of allowed tabular data types. Can be provided as a single value or an array.'
+  )
+
+export const shortDescriptionSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Brief description of the question for internal use')
+
+export const pageHeadingAndGuidanceSchema = Joi.string()
+  .trim()
+  .optional()
+  .description('Combined heading and guidance for the page')
+
+export const pageHeadingSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Main heading displayed at the top of the page')
+
+export const guidanceTextSchema = Joi.string()
+  .trim()
+  .description('Guidance text to assist users in completing the page')
+
+export const needDeclarationSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Whether a declaration is needed')
+
+export const declarationTextSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Text of the declaration that users must agree to')
+
+export const minSchema = Joi.number()
+  .empty('')
+  .integer()
+  .description('Minimum value for numeric inputs')
+
+export const maxSchema = Joi.number()
+  .empty('')
+  .integer()
+  .description('Maximum value for numeric inputs')
+
+export const minLengthSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Minimum character length for text inputs')
+
+export const maxLengthSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Maximum character length for text inputs')
+
+export const maxFutureSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Maximum days in the future allowed for date inputs')
+
+export const maxPastSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Maximum days in the past allowed for date inputs')
+
+export const precisionSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Decimal precision for numeric inputs')
+
+export const prefixSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Text to display before the input (e.g., £)')
+
+export const regexSchema = Joi.string()
+  .optional()
+  .allow('')
+  .description('Regular expression pattern for validation')
+
+export const rowsSchema = Joi.number()
+  .empty('')
+  .integer()
+  .min(1)
+  .description('Number of rows for multiline text fields')
+
+export const suffixSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Text to display after the input (e.g., kg)')
+
+export const classesSchema = Joi.string()
+  .trim()
+  .optional()
+  .allow('')
+  .description('Custom CSS classes to apply to the component')
 
 export const questionDetailsFullSchema = {
   classesSchema,
@@ -169,6 +336,7 @@ export const formEditorInputPageKeys = {
 export const formEditorInputPageSchema = Joi.object<FormEditorInputPage>()
   .keys(formEditorInputPageKeys)
   .required()
+  .description('Input schema for creating a new page in the form editor')
 
 export const formEditorInputheckAnswersSettingsKeys = {
   declarationText: shortDescriptionSchema
@@ -182,6 +350,7 @@ export const formEditorInputCheckAnswersSettingSchema =
   Joi.object<FormEditorInputCheckAnswersSettings>()
     .keys(formEditorInputheckAnswersSettingsKeys)
     .required()
+    .description('Configuration for the check-answers page')
 
 export const formEditorInputQuestionKeys = {
   question: questionSchema,
@@ -198,6 +367,9 @@ export const formEditorInputQuestionSchema =
   Joi.object<FormEditorInputQuestion>()
     .keys(formEditorInputQuestionKeys)
     .required()
+    .description(
+      'Input schema for creating or updating a question in the form editor'
+    )
 
 export const formEditorInputPageSettingsKeys = {
   pageHeadingAndGuidance: pageHeadingAndGuidanceSchema,
@@ -213,3 +385,4 @@ export const formEditorInputPageSettingsSchema =
   Joi.object<FormEditorInputPageSettings>()
     .keys(formEditorInputPageSettingsKeys)
     .required()
+    .description('Settings for page content and display in the form editor')

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

@@ -5,8 +5,17 @@ import { pageSchema } from '~/src/index.js'
 
 export const patchPageSchema = Joi.object<PatchPageFields>()
   .keys({
-    title: pageSchema.extract('title').optional(),
-    path: pageSchema.extract('path').optional()
+    title: pageSchema
+      .extract('title')
+      .optional()
+      .description('New title to set for the page'),
+    path: pageSchema
+      .extract('path')
+      .optional()
+      .description('New URL path to set for the page')
   })
   .required()
   .min(1)
+  .description(
+    'Schema for partially updating a page, requiring at least one field to be provided'
+  )

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

@@ -22,30 +22,63 @@ export const organisations = [
   'Veterinary Medicines Directorate – VMD'
 ]
 
-export const idSchema = Joi.string().hex().length(24).required()
-export const titleSchema = Joi.string().max(250).trim().required()
+export const idSchema = Joi.string()
+  .hex()
+  .length(24)
+  .required()
+  .description(
+    'Unique identifier for the form, 24-character hexadecimal string'
+  )
+
+export const titleSchema = Joi.string()
+  .max(250)
+  .trim()
+  .required()
+  .description('Title of the form, displayed to users')
+
 export const slugSchema = Joi.string()
   .pattern(/^[a-z0-9-]+$/, { name: 'letters, numbers and hyphens only' })
   .required()
+  .description('URL-friendly identifier used in form paths')
 
 export const organisationSchema = Joi.string()
   .valid(...organisations)
   .required()
+  .description('Defra organisation responsible for the form')
+
+export const teamNameSchema = Joi.string()
+  .max(100)
+  .trim()
+  .required()
+  .description('Name of the team responsible for the form')
 
-export const teamNameSchema = Joi.string().max(100).trim().required()
 export const teamEmailSchema = Joi.string()
   .email({ tlds: { allow: ['uk'] } })
   .trim()
   .required()
+  .description('Contact email for the team responsible for the form')
+
+export const phoneSchema = Joi.string()
+  .trim()
+  .description('Phone number for form-related inquiries')
+
+export const emailAddressSchema = Joi.string()
+  .email()
+  .trim()
+  .required()
+  .description('Email address for form-related inquiries')
 
-export const phoneSchema = Joi.string().trim()
+export const emailResponseTimeSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Expected response time for email inquiries')
 
-export const emailAddressSchema = Joi.string().email().trim().required()
-export const emailResponseTimeSchema = Joi.string().trim().required()
-export const emailSchema = Joi.object<FormMetadataContactEmail>().keys({
-  address: emailAddressSchema,
-  responseTime: emailResponseTimeSchema
-})
+export const emailSchema = Joi.object<FormMetadataContactEmail>()
+  .keys({
+    address: emailAddressSchema,
+    responseTime: emailResponseTimeSchema
+  })
+  .description('Email contact details including response expectations')
 
 export const onlineUrlSchema = Joi.string()
   .uri({
@@ -53,34 +86,61 @@ export const onlineUrlSchema = Joi.string()
   })
   .trim()
   .required()
-export const onlineTextSchema = Joi.string().trim().required()
-export const onlineSchema = Joi.object<FormMetadataContactOnline>().keys({
-  url: onlineUrlSchema,
-  text: onlineTextSchema
-})
+  .description('URL for online contact method')
+
+export const onlineTextSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Descriptive text for the online contact link')
 
-export const contactSchema = Joi.object<FormMetadataContact>().keys({
-  phone: phoneSchema,
-  email: emailSchema,
-  online: onlineSchema
-})
+export const onlineSchema = Joi.object<FormMetadataContactOnline>()
+  .keys({
+    url: onlineUrlSchema,
+    text: onlineTextSchema
+  })
+  .description('Online contact details with URL and descriptive text')
 
-export const submissionGuidanceSchema = Joi.string().trim()
+export const contactSchema = Joi.object<FormMetadataContact>()
+  .keys({
+    phone: phoneSchema,
+    email: emailSchema,
+    online: onlineSchema
+  })
+  .description('Complete contact information for form-related inquiries')
+
+export const submissionGuidanceSchema = Joi.string()
+  .trim()
+  .description('Guidance text shown to users when submitting the form')
 
 export const privacyNoticeUrlSchema = Joi.string()
   .uri({
     scheme: ['http', 'https']
   })
   .trim()
+  .description('URL to the privacy notice for this form')
 
 export const notificationEmailAddressSchema = Joi.string()
   .email({ tlds: { allow: ['uk'] } })
   .trim()
   .pattern(/\.gov\.uk$|\.org\.uk$/)
+  .description(
+    'Email address to receive form submission notifications, must be a .gov.uk or .org.uk address'
+  )
+
+export const authoredAtSchema = Joi.date()
+  .iso()
+  .required()
+  .description('ISO format timestamp of when an action occurred')
 
-export const authoredAtSchema = Joi.date().iso().required()
-export const authorIdSchema = Joi.string().trim().required()
-export const authorDisplayNameSchema = Joi.string().trim().required()
+export const authorIdSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Unique identifier for the author')
+
+export const authorDisplayNameSchema = Joi.string()
+  .trim()
+  .required()
+  .description('Human-readable name of the author')
 
 export const formMetadataInputKeys = {
   title: titleSchema,
@@ -100,6 +160,7 @@ export const formMetadataInputKeys = {
 export const formMetadataInputSchema = Joi.object<FormMetadataInput>()
   .keys(formMetadataInputKeys)
   .required()
+  .description('Input data for creating or updating form metadata')
 
 /**
  * Joi schema for `FormMetadataAuthor` interface
@@ -111,29 +172,46 @@ export const formMetadataAuthorSchema = Joi.object<FormMetadataAuthor>()
     displayName: authorDisplayNameSchema
   })
   .required()
+  .description('Information about the author of a form or form change')
 
 /**
  * Joi schema for `FormMetadataState` interface
  * @see {@link FormMetadataState}
  */
-export const formMetadataStateSchema = Joi.object<FormMetadataState>().keys({
-  createdAt: authoredAtSchema,
-  createdBy: formMetadataAuthorSchema,
-  updatedAt: authoredAtSchema,
-  updatedBy: formMetadataAuthorSchema
-})
+export const formMetadataStateSchema = Joi.object<FormMetadataState>()
+  .keys({
+    createdAt: authoredAtSchema.description(
+      'When this version was first created'
+    ),
+    createdBy: formMetadataAuthorSchema.description('Who created this version'),
+    updatedAt: authoredAtSchema.description(
+      'When this version was last updated'
+    ),
+    updatedBy: formMetadataAuthorSchema.description(
+      'Who last updated this version'
+    )
+  })
+  .description('Metadata about a specific version state (draft or live)')
 
 /**
  * Joi schema for `FormMetadata` interface
  * @see {@link FormMetadata}
  */
-export const formMetadataSchema = formMetadataInputSchema.append<FormMetadata>({
-  id: idSchema,
-  slug: slugSchema,
-  draft: formMetadataStateSchema,
-  live: formMetadataStateSchema,
-  createdAt: authoredAtSchema,
-  createdBy: formMetadataAuthorSchema,
-  updatedAt: authoredAtSchema,
-  updatedBy: formMetadataAuthorSchema
-})
+export const formMetadataSchema = formMetadataInputSchema
+  .append<FormMetadata>({
+    id: idSchema,
+    slug: slugSchema,
+    draft: formMetadataStateSchema.description(
+      'Metadata for the draft version'
+    ),
+    live: formMetadataStateSchema.description(
+      'Metadata for the published version'
+    ),
+    createdAt: authoredAtSchema.description('When the form was first created'),
+    createdBy: formMetadataAuthorSchema.description('Who created the form'),
+    updatedAt: authoredAtSchema.description('When the form was last updated'),
+    updatedBy: formMetadataAuthorSchema.description('Who last updated the form')
+  })
+  .description(
+    'Complete metadata for a form, including version information and authoring details'
+  )

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

@@ -11,22 +11,36 @@ import {
  * @see {@link SubmitRecord}
  */
 export const formSubmitRecordSchema = Joi.object<SubmitRecord>({
-  name: Joi.string().required(),
-  title: Joi.string().required(),
-  value: Joi.string().required().allow('')
-})
+  name: Joi.string()
+    .required()
+    .description('Field identifier matching the component name'),
+  title: Joi.string()
+    .required()
+    .description('Human-readable label for the field'),
+  value: Joi.string()
+    .required()
+    .allow('')
+    .description('User-submitted value for the field, may be empty')
+}).description('Individual field value in a form submission')
 
 /**
  * Joi schema for `SubmitRecordset` interface
  * @see {@link SubmitRecordset}
  */
 export const formSubmitRecordsetSchema = Joi.object<SubmitRecordset>({
-  name: Joi.string().required(),
-  title: Joi.string().required(),
+  name: Joi.string()
+    .required()
+    .description('Identifier for the repeatable section'),
+  title: Joi.string()
+    .required()
+    .description('Human-readable title for the repeatable section'),
   value: Joi.array<SubmitRecord[]>()
     .items(Joi.array<SubmitRecord>().items(formSubmitRecordSchema).required())
     .required()
-})
+    .description(
+      'Array of record arrays, each representing a repeated instance'
+    )
+}).description('Collection of repeated field values from a repeatable section')
 
 /**
  * Joi schema for `SubmitPayload` interface
@@ -34,11 +48,20 @@ export const formSubmitRecordsetSchema = Joi.object<SubmitRecordset>({
  */
 export const formSubmitPayloadSchema = Joi.object<SubmitPayload>()
   .keys({
-    retrievalKey: Joi.string().required(),
-    sessionId: Joi.string().required(),
-    main: Joi.array<SubmitRecord>().items(formSubmitRecordSchema).required(),
+    retrievalKey: Joi.string()
+      .required()
+      .description('Unique key to retrieve this submission later'),
+    sessionId: Joi.string()
+      .required()
+      .description('User session identifier for tracking and security'),
+    main: Joi.array<SubmitRecord>()
+      .items(formSubmitRecordSchema)
+      .required()
+      .description('Main (non-repeating) field values from the form'),
     repeaters: Joi.array<SubmitRecordset>()
       .items(formSubmitRecordsetSchema)
       .required()
+      .description('Repeatable section values from the form')
   })
   .required()
+  .description('Complete form submission payload structure with all form data')

package/src/types/joi-to-json.d.ts

@@ -0,0 +1,15 @@
+declare module 'joi-to-json' {
+  import { type Schema } from 'joi'
+
+  /**
+   * Converts a Joi schema to a JSON Schema
+   */
+  function parse(
+    joiSchema: Schema,
+    type?: string,
+    definitions?: object,
+    parserOptions?: object
+  ): object
+
+  export = parse
+}