@defra/forms-model 3.0.429 → 3.0.431

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
+}