@defra/forms-model 3.0.430 → 3.0.431

package/README.md

@@ -1,9 +1,171 @@
 # Defra forms model
 
-# Test coverage threshold
+A model and validation library for Defra forms, providing the foundation for form definitions, components, validation, and data handling.
+
+## Features
+
+- **Form Definition** - Core structures for forms, pages, components, and conditions
+- **Component Library** - Pre-defined form components with validation
+- **JSON Schema** - Ready-to-use JSON schema files for cross-platform validation
+- **Conditions Engine** - Logic for determining form flow and visibility
+- **Type Definitions** - Complete TypeScript type safety
+- **Metadata Handling** - Support for form metadata, versioning, and state management
+
+## Installation
+
+```shell
+npm install @defra/forms-model
+```
+
+## Usage
+
+### Form Definition
+
+```javascript
+import { createForm } from '@defra/forms-model';
+
+const form = createForm({
+  name: 'my-form',
+  pages: [
+    {
+      path: '/start',
+      title: 'Start page',
+      components: [/* components */]
+    }
+  ],
+  sections: [/* sections */]
+});
+```
+
+### Component Usage
+
+```javascript
+import { ComponentType } from '@defra/forms-model';
+
+const textField = {
+  type: ComponentType.TextField,
+  name: 'fullName',
+  title: 'Full name',
+  schema: {
+    min: 2,
+    max: 100
+  }
+};
+```
+
+### Form Validation
+
+#### JSON Schema Files
+
+This package includes pre-generated JSON schema files for use with external JSON Schema validators/ IDEs linting etc:
+
+```javascript
+import formSchema from '@defra/forms-model/schemas/form-definition-schema.json';
+```
+
+Available schema files include:
+
+##### Form Definition Schemas
+
+- `form-definition-schema.json` - Full form definition validation
+- `form-definition-v2-payload-schema.json` - Form definition v2 payload validation
+
+##### Component Schemas
+
+- `component-schema.json` - Component validation
+- `component-schema-v2.json` - Component validation (v2)
+
+##### Page Schemas
+
+- `page-schema.json` - Page validation
+- `page-schema-v2.json` - Page validation (v2)
+- `page-schema-payload-v2.json` - Page payload validation (v2)
+
+##### List Schemas
+
+- `list-schema.json` - List validation
+- `list-schema-v2.json` - List validation (v2)
+
+##### Form Metadata Schemas
+
+- `form-metadata-schema.json` - Form metadata validation
+- `form-metadata-author-schema.json` - Form metadata author validation
+- `form-metadata-input-schema.json` - Form metadata input validation
+- `form-metadata-state-schema.json` - Form metadata state validation
+
+##### Form Metadata Field Schemas
+
+- `form-metadata-contact-schema.json` - Contact information validation
+- `form-metadata-email-schema.json` - Email validation
+- `form-metadata-online-schema.json` - Online form metadata validation
+
+##### Form Editor Schemas
+
+- `form-editor-input-page-schema.json` - Form editor input page validation
+- `form-editor-input-check-answers-setting-schema.json` - Check answers setting validation
+- `form-editor-input-question-schema.json` - Question input validation
+- `form-editor-input-page-settings-schema.json` - Page settings validation
+
+##### Form Editor Field Schemas
+
+- `page-type-schema.json` - Page type validation
+- `question-type-schema.json` - Question type validation
+- `question-type-full-schema.json` - Full question type validation
+- `written-answer-sub-schema.json` - Written answer sub-schema validation
+- `date-sub-schema.json` - Date sub-schema validation
+
+##### Form Submission Schemas
+
+- `form-submit-payload-schema.json` - Form submission payload validation
+- `form-submit-record-schema.json` - Form submission record validation
+- `form-submit-recordset-schema.json` - Form submission recordset validation
+
+##### Form Manager Schemas
+
+- `patch-page-schema.json` - Patch page validation
+
+##### Section Schemas
+
+- `question-schema.json` - Question validation
+
+##### Validation Schemas
+
+- `min-schema.json` - Minimum value validation
+- `max-schema.json` - Maximum value validation
+- `min-length-schema.json` - Minimum length validation
+- `max-length-schema.json` - Maximum length validation
+- `max-future-schema.json` - Maximum future date validation
+- `max-past-schema.json` - Maximum past date validation
+
+##### Common Schemas
+
+- `search-options-schema.json` - Search options validation
+- `query-options-schema.json` - Query options validation
+- `pagination-options-schema.json` - Pagination options validation
+- `sorting-options-schema.json` - Sorting options validation
+
+## Development
+
+### Test Coverage
 
 Unit test coverage threshold, code coverage below which build will fail is set by using jest config, at the moment line coverage threshold is set as 92%, see [jest.config.js](jest.config.js)
 
+### JSON Schema Generation and Publishing
+
+This package generates JSON Schema files from Joi validation schemas during the build process. These schemas are included in the published npm package and are available at runtime.
+
+#### How It Works
+
+When you run `npm run build`, the script `scripts/generate-schemas.js` is executed which:
+
+1. Converts Joi validation schemas to JSON Schema format
+2. Enhances schemas with titles and descriptions
+3. Writes schema files to the `schemas/` directory
+
+#### Known Quirks
+
+1. **First Build Required**: After a fresh clone, you must run `npm run build` before the schema files will be available locally.
+
 ## License
 
 THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

package/dist/module/common/pagination/index.js

@@ -3,8 +3,8 @@ import Joi from 'joi';
  * Field definitions for pagination options.
  */
 export const paginationOptionFields = {
-  page: Joi.number().positive().integer().default(1).min(1).optional(),
-  perPage: Joi.number().positive().integer().default(24).min(1).max(200).optional()
+  page: Joi.number().positive().integer().default(1).min(1).optional().description('Current page number, starting from 1'),
+  perPage: Joi.number().positive().integer().default(24).min(1).max(200).optional().description('Number of items to display per page, between 1 and 200')
 };
 
 /**

package/dist/module/common/pagination/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Joi","paginationOptionFields","page","number","positive","integer","default","min","optional","perPage","max","paginationOptionsSchema","object"],"sources":["../../../../src/common/pagination/index.ts"],"sourcesContent":["import Joi from 'joi'\n\nimport { type PaginationOptions } from '~/src/common/pagination/types.js'\n\n/**\n * Field definitions for pagination options.\n */\nexport const paginationOptionFields = {\n  page: Joi.number().positive().integer().default(1).min(1).optional(),\n  perPage: Joi.number()\n    .positive()\n    .integer()\n    .default(24)\n    .min(1)\n    .max(200)\n    .optional()\n}\n\n/**\n * Joi schema for `PaginationOptions` interface\n * @see {@link PaginationOptions}\n */\nexport const paginationOptionsSchema: Joi.ObjectSchema<PaginationOptions> =\n  Joi.object(paginationOptionFields)\n"],"mappings":"AAAA,OAAOA,GAAG,MAAM,KAAK;AAIrB;AACA;AACA;AACA,OAAO,MAAMC,sBAAsB,GAAG;EACpCC,IAAI,EAAEF,GAAG,CAACG,MAAM,CAAC,CAAC,CAACC,QAAQ,CAAC,CAAC,CAACC,OAAO,CAAC,CAAC,CAACC,OAAO,CAAC,CAAC,CAAC,CAACC,GAAG,CAAC,CAAC,CAAC,CAACC,QAAQ,CAAC,CAAC;EACpEC,OAAO,EAAET,GAAG,CAACG,MAAM,CAAC,CAAC,CAClBC,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,CAAC,CACTC,OAAO,CAAC,EAAE,CAAC,CACXC,GAAG,CAAC,CAAC,CAAC,CACNG,GAAG,CAAC,GAAG,CAAC,CACRF,QAAQ,CAAC;AACd,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAMG,uBAA4D,GACvEX,GAAG,CAACY,MAAM,CAACX,sBAAsB,CAAC","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Joi","paginationOptionFields","page","number","positive","integer","default","min","optional","description","perPage","max","paginationOptionsSchema","object"],"sources":["../../../../src/common/pagination/index.ts"],"sourcesContent":["import Joi from 'joi'\n\nimport { type PaginationOptions } from '~/src/common/pagination/types.js'\n\n/**\n * Field definitions for pagination options.\n */\nexport const paginationOptionFields = {\n  page: Joi.number()\n    .positive()\n    .integer()\n    .default(1)\n    .min(1)\n    .optional()\n    .description('Current page number, starting from 1'),\n  perPage: Joi.number()\n    .positive()\n    .integer()\n    .default(24)\n    .min(1)\n    .max(200)\n    .optional()\n    .description('Number of items to display per page, between 1 and 200')\n}\n\n/**\n * Joi schema for `PaginationOptions` interface\n * @see {@link PaginationOptions}\n */\nexport const paginationOptionsSchema: Joi.ObjectSchema<PaginationOptions> =\n  Joi.object(paginationOptionFields)\n"],"mappings":"AAAA,OAAOA,GAAG,MAAM,KAAK;AAIrB;AACA;AACA;AACA,OAAO,MAAMC,sBAAsB,GAAG;EACpCC,IAAI,EAAEF,GAAG,CAACG,MAAM,CAAC,CAAC,CACfC,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,CAAC,CACTC,OAAO,CAAC,CAAC,CAAC,CACVC,GAAG,CAAC,CAAC,CAAC,CACNC,QAAQ,CAAC,CAAC,CACVC,WAAW,CAAC,sCAAsC,CAAC;EACtDC,OAAO,EAAEV,GAAG,CAACG,MAAM,CAAC,CAAC,CAClBC,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,CAAC,CACTC,OAAO,CAAC,EAAE,CAAC,CACXC,GAAG,CAAC,CAAC,CAAC,CACNI,GAAG,CAAC,GAAG,CAAC,CACRH,QAAQ,CAAC,CAAC,CACVC,WAAW,CAAC,wDAAwD;AACzE,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAMG,uBAA4D,GACvEZ,GAAG,CAACa,MAAM,CAACZ,sBAAsB,CAAC","ignoreList":[]}

package/dist/module/common/search/index.js

@@ -5,10 +5,10 @@ import { organisations } from "../../form/form-metadata/index.js";
  * Field definitions for search options.
  */
 export const searchOptionFields = {
-  title: Joi.string().trim().allow('').max(255).optional().default(''),
-  author: Joi.string().trim().allow('').max(100).optional().default(''),
-  organisations: Joi.array().items(Joi.string().valid(...organisations)).single().optional().default([]),
-  status: Joi.array().items(Joi.string().valid('draft', 'live')).single().optional().default([])
+  title: Joi.string().trim().allow('').max(255).optional().default('').description('Search by form title, empty string matches all'),
+  author: Joi.string().trim().allow('').max(100).optional().default('').description('Search by form author, empty string matches all'),
+  organisations: Joi.array().items(Joi.string().valid(...organisations)).single().optional().default([]).description('Filter by organisation(s), empty array matches all'),
+  status: Joi.array().items(Joi.string().valid('draft', 'live')).single().optional().default([]).description('Filter by form status(es), empty array matches all')
 };
 
 /**

package/dist/module/common/search/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Joi","organisations","searchOptionFields","title","string","trim","allow","max","optional","default","author","array","items","valid","single","status","searchOptionsSchema","object"],"sources":["../../../../src/common/search/index.ts"],"sourcesContent":["import Joi from 'joi'\n\nimport { type SearchOptions } from '~/src/common/search/types.js'\nimport { organisations } from '~/src/form/form-metadata/index.js'\n\n/**\n * Field definitions for search options.\n */\nexport const searchOptionFields = {\n  title: Joi.string().trim().allow('').max(255).optional().default(''),\n  author: Joi.string().trim().allow('').max(100).optional().default(''),\n  organisations: Joi.array()\n    .items(Joi.string().valid(...organisations))\n    .single()\n    .optional()\n    .default([]),\n  status: Joi.array()\n    .items(Joi.string().valid('draft', 'live'))\n    .single()\n    .optional()\n    .default([])\n}\n\n/**\n * Joi schema for {@link SearchOptions} interface\n */\nexport const searchOptionsSchema: Joi.ObjectSchema<SearchOptions> =\n  Joi.object(searchOptionFields)\n"],"mappings":"AAAA,OAAOA,GAAG,MAAM,KAAK;AAGrB,SAASC,aAAa;;AAEtB;AACA;AACA;AACA,OAAO,MAAMC,kBAAkB,GAAG;EAChCC,KAAK,EAAEH,GAAG,CAACI,MAAM,CAAC,CAAC,CAACC,IAAI,CAAC,CAAC,CAACC,KAAK,CAAC,EAAE,CAAC,CAACC,GAAG,CAAC,GAAG,CAAC,CAACC,QAAQ,CAAC,CAAC,CAACC,OAAO,CAAC,EAAE,CAAC;EACpEC,MAAM,EAAEV,GAAG,CAACI,MAAM,CAAC,CAAC,CAACC,IAAI,CAAC,CAAC,CAACC,KAAK,CAAC,EAAE,CAAC,CAACC,GAAG,CAAC,GAAG,CAAC,CAACC,QAAQ,CAAC,CAAC,CAACC,OAAO,CAAC,EAAE,CAAC;EACrER,aAAa,EAAED,GAAG,CAACW,KAAK,CAAC,CAAC,CACvBC,KAAK,CAACZ,GAAG,CAACI,MAAM,CAAC,CAAC,CAACS,KAAK,CAAC,GAAGZ,aAAa,CAAC,CAAC,CAC3Ca,MAAM,CAAC,CAAC,CACRN,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,EAAE,CAAC;EACdM,MAAM,EAAEf,GAAG,CAACW,KAAK,CAAC,CAAC,CAChBC,KAAK,CAACZ,GAAG,CAACI,MAAM,CAAC,CAAC,CAACS,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAC1CC,MAAM,CAAC,CAAC,CACRN,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,EAAE;AACf,CAAC;;AAED;AACA;AACA;AACA,OAAO,MAAMO,mBAAoD,GAC/DhB,GAAG,CAACiB,MAAM,CAACf,kBAAkB,CAAC","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Joi","organisations","searchOptionFields","title","string","trim","allow","max","optional","default","description","author","array","items","valid","single","status","searchOptionsSchema","object"],"sources":["../../../../src/common/search/index.ts"],"sourcesContent":["import Joi from 'joi'\n\nimport { type SearchOptions } from '~/src/common/search/types.js'\nimport { organisations } from '~/src/form/form-metadata/index.js'\n\n/**\n * Field definitions for search options.\n */\nexport const searchOptionFields = {\n  title: Joi.string()\n    .trim()\n    .allow('')\n    .max(255)\n    .optional()\n    .default('')\n    .description('Search by form title, empty string matches all'),\n  author: Joi.string()\n    .trim()\n    .allow('')\n    .max(100)\n    .optional()\n    .default('')\n    .description('Search by form author, empty string matches all'),\n  organisations: Joi.array()\n    .items(Joi.string().valid(...organisations))\n    .single()\n    .optional()\n    .default([])\n    .description('Filter by organisation(s), empty array matches all'),\n  status: Joi.array()\n    .items(Joi.string().valid('draft', 'live'))\n    .single()\n    .optional()\n    .default([])\n    .description('Filter by form status(es), empty array matches all')\n}\n\n/**\n * Joi schema for {@link SearchOptions} interface\n */\nexport const searchOptionsSchema: Joi.ObjectSchema<SearchOptions> =\n  Joi.object(searchOptionFields)\n"],"mappings":"AAAA,OAAOA,GAAG,MAAM,KAAK;AAGrB,SAASC,aAAa;;AAEtB;AACA;AACA;AACA,OAAO,MAAMC,kBAAkB,GAAG;EAChCC,KAAK,EAAEH,GAAG,CAACI,MAAM,CAAC,CAAC,CAChBC,IAAI,CAAC,CAAC,CACNC,KAAK,CAAC,EAAE,CAAC,CACTC,GAAG,CAAC,GAAG,CAAC,CACRC,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,EAAE,CAAC,CACXC,WAAW,CAAC,gDAAgD,CAAC;EAChEC,MAAM,EAAEX,GAAG,CAACI,MAAM,CAAC,CAAC,CACjBC,IAAI,CAAC,CAAC,CACNC,KAAK,CAAC,EAAE,CAAC,CACTC,GAAG,CAAC,GAAG,CAAC,CACRC,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,EAAE,CAAC,CACXC,WAAW,CAAC,iDAAiD,CAAC;EACjET,aAAa,EAAED,GAAG,CAACY,KAAK,CAAC,CAAC,CACvBC,KAAK,CAACb,GAAG,CAACI,MAAM,CAAC,CAAC,CAACU,KAAK,CAAC,GAAGb,aAAa,CAAC,CAAC,CAC3Cc,MAAM,CAAC,CAAC,CACRP,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,EAAE,CAAC,CACXC,WAAW,CAAC,oDAAoD,CAAC;EACpEM,MAAM,EAAEhB,GAAG,CAACY,KAAK,CAAC,CAAC,CAChBC,KAAK,CAACb,GAAG,CAACI,MAAM,CAAC,CAAC,CAACU,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAC1CC,MAAM,CAAC,CAAC,CACRP,QAAQ,CAAC,CAAC,CACVC,OAAO,CAAC,EAAE,CAAC,CACXC,WAAW,CAAC,oDAAoD;AACrE,CAAC;;AAED;AACA;AACA;AACA,OAAO,MAAMO,mBAAoD,GAC/DjB,GAAG,CAACkB,MAAM,CAAChB,kBAAkB,CAAC","ignoreList":[]}

package/dist/module/common/sorting/index.js

@@ -3,8 +3,8 @@ import Joi from 'joi';
  * Field definitions for sorting options.
  */
 export const sortingOptionFields = {
-  sortBy: Joi.string().valid('updatedAt', 'title').optional(),
-  order: Joi.string().valid('asc', 'desc').optional()
+  sortBy: Joi.string().valid('updatedAt', 'title').optional().description('Field to sort results by'),
+  order: Joi.string().valid('asc', 'desc').optional().description('Sort order (ascending or descending)')
 };
 
 /**

package/dist/module/common/sorting/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["Joi","sortingOptionFields","sortBy","string","valid","optional","order","sortingOptionsSchema","object"],"sources":["../../../../src/common/sorting/index.ts"],"sourcesContent":["import Joi from 'joi'\n\nimport { type SortingOptions } from '~/src/common/sorting/types.js'\n\n/**\n * Field definitions for sorting options.\n */\nexport const sortingOptionFields = {\n  sortBy: Joi.string().valid('updatedAt', 'title').optional(),\n  order: Joi.string().valid('asc', 'desc').optional()\n}\n\n/**\n * Joi schema for `SortingOptions` interface\n * @see {@link SortingOptions}\n */\nexport const sortingOptionsSchema: Joi.ObjectSchema<SortingOptions> =\n  Joi.object(sortingOptionFields)\n"],"mappings":"AAAA,OAAOA,GAAG,MAAM,KAAK;AAIrB;AACA;AACA;AACA,OAAO,MAAMC,mBAAmB,GAAG;EACjCC,MAAM,EAAEF,GAAG,CAACG,MAAM,CAAC,CAAC,CAACC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAACC,QAAQ,CAAC,CAAC;EAC3DC,KAAK,EAAEN,GAAG,CAACG,MAAM,CAAC,CAAC,CAACC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAACC,QAAQ,CAAC;AACpD,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAME,oBAAsD,GACjEP,GAAG,CAACQ,MAAM,CAACP,mBAAmB,CAAC","ignoreList":[]}
+{"version":3,"file":"index.js","names":["Joi","sortingOptionFields","sortBy","string","valid","optional","description","order","sortingOptionsSchema","object"],"sources":["../../../../src/common/sorting/index.ts"],"sourcesContent":["import Joi from 'joi'\n\nimport { type SortingOptions } from '~/src/common/sorting/types.js'\n\n/**\n * Field definitions for sorting options.\n */\nexport const sortingOptionFields = {\n  sortBy: Joi.string()\n    .valid('updatedAt', 'title')\n    .optional()\n    .description('Field to sort results by'),\n  order: Joi.string()\n    .valid('asc', 'desc')\n    .optional()\n    .description('Sort order (ascending or descending)')\n}\n\n/**\n * Joi schema for `SortingOptions` interface\n * @see {@link SortingOptions}\n */\nexport const sortingOptionsSchema: Joi.ObjectSchema<SortingOptions> =\n  Joi.object(sortingOptionFields)\n"],"mappings":"AAAA,OAAOA,GAAG,MAAM,KAAK;AAIrB;AACA;AACA;AACA,OAAO,MAAMC,mBAAmB,GAAG;EACjCC,MAAM,EAAEF,GAAG,CAACG,MAAM,CAAC,CAAC,CACjBC,KAAK,CAAC,WAAW,EAAE,OAAO,CAAC,CAC3BC,QAAQ,CAAC,CAAC,CACVC,WAAW,CAAC,0BAA0B,CAAC;EAC1CC,KAAK,EAAEP,GAAG,CAACG,MAAM,CAAC,CAAC,CAChBC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CACpBC,QAAQ,CAAC,CAAC,CACVC,WAAW,CAAC,sCAAsC;AACvD,CAAC;;AAED;AACA;AACA;AACA;AACA,OAAO,MAAME,oBAAsD,GACjER,GAAG,CAACS,MAAM,CAACR,mBAAmB,CAAC","ignoreList":[]}