From 97ffee2cb22ca4696d0a6f752e60a743835e78d3 Mon Sep 17 00:00:00 2001 From: Alex Luckett Date: Thu, 19 Nov 2026 14:54:31 +0000 Subject: [PATCH 1/3] Correct the v4 to v5 migration guide Add Node 26 to the supported Node.js range and say that v5 drops Node 22. Name conditionEvaluations as a field that a strict v4 schema rejects, because the plugin always sends it. Limit the map proxy note to upgrades from a version before v4.22.0, which is where the path parameter came in. Put the table rows in the same order as the sections. --- docs/migration-v4-to-v5.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/migration-v4-to-v5.md b/docs/migration-v4-to-v5.md index b7c32d747..38330f45e 100644 --- a/docs/migration-v4-to-v5.md +++ b/docs/migration-v4-to-v5.md @@ -8,12 +8,12 @@ v5 keeps the v4 plugin options, service interfaces and page controller methods. | Change | Applies to | Effort | | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | -| [Node.js `^24.19.0` and npm `^11.17.0 \|\| >=12.0.2`](#nodejs-and-npm) | All applications | Small | +| [Node.js `^24.19.0 \|\| ^26.0.0` and npm `^11.17.0 \|\| >=12.0.2`](#nodejs-and-npm) | All applications | Small | | [forms-model v4 and Joi 18](#forms-model-v4-and-joi-18) | All applications | Small | | [Client build for maps](#client-build-for-maps) | Applications that bundle the plugin's client JavaScript | Small | | [Submission data for location fields](#submission-data-for-location-fields) | Services that read easting/northing or latitude/longitude answers | Small | -| [Submission message schema](#submission-message-schema) | Services that validate submission messages with the plugin's schemas | Trivial | | [Blank repeater answers are `null`](#blank-repeater-answers) | Services that read `data.repeaters` from submission messages | Trivial | +| [Submission message schema](#submission-message-schema) | Services that validate submission messages with the plugin's schemas | Trivial | | [`SchemaValidationError` for invalid definitions](#invalid-form-definition-errors) | Code that catches errors when it builds a `FormModel` | Trivial | | [`FormAdapterSubmissionSchemaVersion` is a constant object](#submission-schema-version) | TypeScript code that uses it as a type | Trivial | | [Templates use a `t` global](#templates-use-a-t-global) | Applications that render plugin templates in their own Nunjucks setup | Small | @@ -25,7 +25,7 @@ Read [Deploying v5](#deploying-v5) before you release. ## Node.js and npm -v5 supports Node.js `^24.19.0` and npm `^11.17.0 || >=12.0.2`. npm warns about other versions, and refuses to install with `engine-strict`. Update your `.nvmrc`, `Dockerfile`, CI and `engines` field to match. +v5 supports Node.js `^24.19.0 || ^26.0.0` and npm `^11.17.0 || >=12.0.2`. v4 supported Node.js 22, which v5 does not. npm warns about other versions, and refuses to install with `engine-strict`. Update your `.nvmrc`, `Dockerfile`, CI and `engines` field to match. ## forms-model v4 and Joi 18 @@ -102,9 +102,9 @@ Update services that check whether a key exists, for example with `'field' in it The schemas for submission messages, such as `formAdapterSubmissionMessageMetaSchema`, changed: - `meta.schemaVersion` is required, and must be the number `1`. The string `'V1'` is no longer valid. -- `meta.language`, `meta.auth`, `payment.descriptionInEng` and `conditionEvaluations` are new optional fields. The plugin always sends `meta.language`. +- `meta.language`, `meta.auth`, `payment.descriptionInEng` and `conditionEvaluations` are new optional fields. The plugin always sends `meta.language` and `conditionEvaluations`. For a V1 form definition, `conditionEvaluations` is an empty array. -A service that validates v5 messages with the v4 schema rejects `meta.language`, unless it validates with `stripUnknown: true`. Upgrade such services before you release v5. See [Deploying v5](#deploying-v5). +A service that validates v5 messages with the v4 schema rejects `meta.language` and `conditionEvaluations`, unless it validates with `allowUnknown: true` or `stripUnknown: true`. Upgrade such services before you release v5. See [Deploying v5](#deploying-v5). ## Invalid form definition errors @@ -210,4 +210,4 @@ These changes affect code that imports from `@defra/forms-engine-plugin/engine/* - **Submission services first:** upgrade services that validate submission messages with the v4 schema before you release v5. See [Submission message schema](#submission-message-schema). - **Postcode lookup in progress:** a user who is in the postcode lookup pages when v5 goes live can see an error page, and must go back to the address question to start the lookup again. -- **Map pages open during the release:** a browser that has the v4 map JavaScript gets errors from the map proxy until the user reloads the page. The proxy takes a `path` parameter in place of `url`. The `id` of each feature in `/api/maps/countries.geojson` is now a number. +- **Map pages open during the release:** the `id` of each feature in `/api/maps/countries.geojson` is now a number. If you upgrade from a version before v4.22.0, a browser that has the old map JavaScript also gets errors from the map proxy until the user reloads the page, because the proxy takes a `path` parameter in place of `url`. From 07eec6ce1a7ba0d6c8b050b55480fefa6db3cc1d Mon Sep 17 00:00:00 2001 From: Alex Luckett Date: Thu, 19 Nov 2026 15:00:34 +0000 Subject: [PATCH 2/3] Move the v4 schema warning into the release steps A service that uses the v5 schemas accepts the new fields, so the risk exists only while services still run the v4 schemas during the release. --- docs/migration-v4-to-v5.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/migration-v4-to-v5.md b/docs/migration-v4-to-v5.md index 38330f45e..bbb4975d5 100644 --- a/docs/migration-v4-to-v5.md +++ b/docs/migration-v4-to-v5.md @@ -104,8 +104,6 @@ The schemas for submission messages, such as `formAdapterSubmissionMessageMetaSc - `meta.schemaVersion` is required, and must be the number `1`. The string `'V1'` is no longer valid. - `meta.language`, `meta.auth`, `payment.descriptionInEng` and `conditionEvaluations` are new optional fields. The plugin always sends `meta.language` and `conditionEvaluations`. For a V1 form definition, `conditionEvaluations` is an empty array. -A service that validates v5 messages with the v4 schema rejects `meta.language` and `conditionEvaluations`, unless it validates with `allowUnknown: true` or `stripUnknown: true`. Upgrade such services before you release v5. See [Deploying v5](#deploying-v5). - ## Invalid form definition errors `new FormModel(...)` throws a `SchemaValidationError` when the definition fails schema validation. The original Joi `ValidationError` is on `error.cause`. @@ -208,6 +206,6 @@ These changes affect code that imports from `@defra/forms-engine-plugin/engine/* ## Deploying v5 -- **Submission services first:** upgrade services that validate submission messages with the v4 schema before you release v5. See [Submission message schema](#submission-message-schema). +- **Submission services first:** upgrade services that validate submission messages with the plugin's schemas before you release v5. The v4 schemas reject `meta.language` and `conditionEvaluations`, which v5 always sends. See [Submission message schema](#submission-message-schema). - **Postcode lookup in progress:** a user who is in the postcode lookup pages when v5 goes live can see an error page, and must go back to the address question to start the lookup again. - **Map pages open during the release:** the `id` of each feature in `/api/maps/countries.geojson` is now a number. If you upgrade from a version before v4.22.0, a browser that has the old map JavaScript also gets errors from the map proxy until the user reloads the page, because the proxy takes a `path` parameter in place of `url`. From c8a7cda5922eea51d0efbf372462243cb645f2f3 Mon Sep 17 00:00:00 2001 From: Alex Luckett Date: Thu, 19 Nov 2026 15:01:32 +0000 Subject: [PATCH 3/3] Remove the submission service release step How a service that reads submissions validates them, and when it upgrades, belongs to that service. The schema section still lists the changes to the schemas that the plugin exports. --- docs/migration-v4-to-v5.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/migration-v4-to-v5.md b/docs/migration-v4-to-v5.md index bbb4975d5..1e1589d12 100644 --- a/docs/migration-v4-to-v5.md +++ b/docs/migration-v4-to-v5.md @@ -206,6 +206,5 @@ These changes affect code that imports from `@defra/forms-engine-plugin/engine/* ## Deploying v5 -- **Submission services first:** upgrade services that validate submission messages with the plugin's schemas before you release v5. The v4 schemas reject `meta.language` and `conditionEvaluations`, which v5 always sends. See [Submission message schema](#submission-message-schema). - **Postcode lookup in progress:** a user who is in the postcode lookup pages when v5 goes live can see an error page, and must go back to the address question to start the lookup again. - **Map pages open during the release:** the `id` of each feature in `/api/maps/countries.geojson` is now a number. If you upgrade from a version before v4.22.0, a browser that has the old map JavaScript also gets errors from the map proxy until the user reloads the page, because the proxy takes a `path` parameter in place of `url`.