@pdtf/schemas 3.5.0 → 3.5.1-2

package/src/schemas/verifiedClaims/README.md

@@ -1,12 +1,21 @@
 ## README
 
 ### About verified claims
-`pdtf-verified-claims.json` describes the schema container in which we store property `claims` and their corresponding `verification`.  
+`pdtf-verified-claims.json` describes the schema container in which we store property `claims` and their corresponding `verification`.
 
-This schema structure is strongly influenced by OpenID Connect for Identity Assurance 1.0's way of storing "verified claims". 
+This schema structure is strongly influenced by OpenID Connect for Identity Assurance 1.0's way of storing "verified claims".
 
 More Details from the OIDC page which describes the details the nature of `verification` and `claims` objects: https://openid.net/specs/openid-connect-4-identity-assurance-1_0.html#name-representing-verified-claim
 
-Notes: 
+### Terms of Use
+The schema supports an optional `terms_of_use` object to control access to verified claims based on confidentiality levels:
+
+* **Public**: No access restrictions (`allowed_roles: []`)
+* **Restricted**: Requires some participant role but not specifically defined (`allowed_roles: []`)
+* **Confidential**: Specific roles defined for access control (e.g., `allowed_roles: ["Seller's Conveyancer", "Buyer's Conveyancer"]`)
+
+The `allowed_roles` array accepts any of the participant roles defined in [pdtf-transaction.json](../v3/pdtf-transaction.json).
+
+Notes:
 * For PDTF Schema, all data included in the `claims` object must adhere to [pdtf-transaction.json (v3)](../v3/pdtf-transaction.json)
 * For verification, there is more freedom in terms of the type of data that can currently be provided, see the documentation in the OIDC link above for details and examples.

package/src/schemas/verifiedClaims/pdtf-verified-claims.json

@@ -411,6 +411,22 @@
           },
           "minProperties": 1,
           "additionalProperties": false
+        },
+        "terms_of_use": {
+          "type": "object",
+          "properties": {
+            "confidentiality_level": {
+              "type": "string",
+              "enum": ["public", "restricted", "confidential"]
+            },
+            "allowed_roles": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "required": ["verification", "claims"],

package/src/tests/v3/transactionSchema.test.js

@@ -314,9 +314,11 @@ test("correctly gets a subschema validator for a TA6 overlay which validates wit
   );
   const data = jp.get(exampleTransaction, path);
   data.uprn = undefined;
-  const validator = getSubschemaValidator(path, exampleTransaction.$schema, [
-    "ta6ed4",
-  ]);
+  const validator = getSubschemaValidator(
+    path,
+    clonedExampleTransaction.$schema,
+    ["ta6ed4"]
+  );
   let isValid = validator(data);
   expect(isValid).toBe(true);
 });
@@ -458,7 +460,7 @@ test("ntsl2025 requires parking and listingAndConservation fields", () => {
   const clonedExampleTransaction = JSON.parse(
     JSON.stringify(exampleTransaction)
   );
-  
+
   // Set up lettings-specific fields
   clonedExampleTransaction.propertyPack.lettingInformation = {
     rent: 3500,
@@ -467,32 +469,47 @@ test("ntsl2025 requires parking and listingAndConservation fields", () => {
   };
   delete clonedExampleTransaction.propertyPack.priceInformation;
   delete clonedExampleTransaction.propertyPack.ownership;
-  
+
   // Remove ALL parking fields - this should make validation fail
   delete clonedExampleTransaction.propertyPack.parking.parkingArrangements;
   delete clonedExampleTransaction.propertyPack.parking.disabledParking;
   delete clonedExampleTransaction.propertyPack.parking.controlledParking;
-  delete clonedExampleTransaction.propertyPack.parking.electricVehicleChargingPoint;
-  
+  delete clonedExampleTransaction.propertyPack.parking
+    .electricVehicleChargingPoint;
+
   // Remove ALL listingAndConservation fields - this should make validation fail
   delete clonedExampleTransaction.propertyPack.listingAndConservation.isListed;
-  delete clonedExampleTransaction.propertyPack.listingAndConservation.isConservationArea;
-  delete clonedExampleTransaction.propertyPack.listingAndConservation.hasTreePreservationOrder;
-  
+  delete clonedExampleTransaction.propertyPack.listingAndConservation
+    .isConservationArea;
+  delete clonedExampleTransaction.propertyPack.listingAndConservation
+    .hasTreePreservationOrder;
+
   const isValid = validator(clonedExampleTransaction);
-  
+
   // The data should be INVALID because required fields are missing
   expect(isValid).toBe(false);
-  
+
   // Specifically check that parking and listingAndConservation fields are reported as missing
-  const errorMessages = validator.errors.map(e => e.message);
-  expect(errorMessages).toContain("must have required property 'parkingArrangements'");
-  expect(errorMessages).toContain("must have required property 'disabledParking'");
-  expect(errorMessages).toContain("must have required property 'controlledParking'");
-  expect(errorMessages).toContain("must have required property 'electricVehicleChargingPoint'");
+  const errorMessages = validator.errors.map((e) => e.message);
+  expect(errorMessages).toContain(
+    "must have required property 'parkingArrangements'"
+  );
+  expect(errorMessages).toContain(
+    "must have required property 'disabledParking'"
+  );
+  expect(errorMessages).toContain(
+    "must have required property 'controlledParking'"
+  );
+  expect(errorMessages).toContain(
+    "must have required property 'electricVehicleChargingPoint'"
+  );
   expect(errorMessages).toContain("must have required property 'isListed'");
-  expect(errorMessages).toContain("must have required property 'isConservationArea'");
-  expect(errorMessages).toContain("must have required property 'hasTreePreservationOrder'");
+  expect(errorMessages).toContain(
+    "must have required property 'isConservationArea'"
+  );
+  expect(errorMessages).toContain(
+    "must have required property 'hasTreePreservationOrder'"
+  );
 });
 
 test("waterAndDrainage state is invalid under nts2023 overlay when mainsFoulDrainage yesNo is Not known", () => {
@@ -500,36 +517,37 @@ test("waterAndDrainage state is invalid under nts2023 overlay when mainsFoulDrai
   const clonedExampleTransaction = JSON.parse(
     JSON.stringify(exampleTransaction)
   );
-  
+
   // Set the waterAndDrainage to an actually invalid state for nts2023
-  // The nts overlay restricts mainsFoulDrainage.yesNo to only "Yes" or "No" 
+  // The nts overlay restricts mainsFoulDrainage.yesNo to only "Yes" or "No"
   // (not "Not known" like the base schema allows)
   clonedExampleTransaction.propertyPack.waterAndDrainage = {
-    "water": {
-      "mainsWater": {
-        "yesNo": "Yes",
-        "waterMeter": {
-          "isSupplyMetered": "No"
-        }
-      }
+    water: {
+      mainsWater: {
+        yesNo: "Yes",
+        waterMeter: {
+          isSupplyMetered: "No",
+        },
+      },
     },
-    "drainage": {
-      "mainsSurfaceWaterDrainage": {
-        "yesNo": "Yes"
+    drainage: {
+      mainsSurfaceWaterDrainage: {
+        yesNo: "Yes",
       },
-      "mainsFoulDrainage": {
-        "yesNo": "Not known"  // This is invalid under nts2023 overlay
-      }
-    }
+      mainsFoulDrainage: {
+        yesNo: "Not known", // This is invalid under nts2023 overlay
+      },
+    },
   };
-  
+
   const isValid = validator(clonedExampleTransaction);
   expect(isValid).toBe(false);
-  
+
   // Check that the validation error is about the invalid enum value
-  const relevantError = validator.errors.find(error => 
-    error.instancePath.includes('mainsFoulDrainage') && 
-    error.message.includes('must be equal to one of the allowed values')
+  const relevantError = validator.errors.find(
+    (error) =>
+      error.instancePath.includes("mainsFoulDrainage") &&
+      error.message.includes("must be equal to one of the allowed values")
   );
   expect(relevantError).toBeDefined();
 });
@@ -539,36 +557,37 @@ test("waterAndDrainage state with mainsFoulDrainage No missing offMainsDrainageS
   const clonedExampleTransaction = JSON.parse(
     JSON.stringify(exampleTransaction)
   );
-  
+
   // Set the waterAndDrainage to the state from the user request
   // This SHOULD be invalid because offMainsDrainageSystem is required when mainsFoulDrainage.yesNo is "No"
   clonedExampleTransaction.propertyPack.waterAndDrainage = {
-    "water": {
-      "mainsWater": {
-        "yesNo": "Yes",
-        "waterMeter": {
-          "isSupplyMetered": "No"
-        }
-      }
+    water: {
+      mainsWater: {
+        yesNo: "Yes",
+        waterMeter: {
+          isSupplyMetered: "No",
+        },
+      },
     },
-    "drainage": {
-      "mainsSurfaceWaterDrainage": {
-        "yesNo": "Yes"
+    drainage: {
+      mainsSurfaceWaterDrainage: {
+        yesNo: "Yes",
       },
-      "mainsFoulDrainage": {
-        "yesNo": "No"
+      mainsFoulDrainage: {
+        yesNo: "No",
         // Missing offMainsDrainageSystem - this should make validation fail
-      }
-    }
+      },
+    },
   };
-  
+
   const isValid = validator(clonedExampleTransaction);
   expect(isValid).toBe(false);
-  
+
   // Check that the validation error is about missing offMainsDrainageSystem
-  const relevantError = validator.errors.find(error => 
-    error.instancePath.includes('mainsFoulDrainage') && 
-    error.message.includes('offMainsDrainageSystem')
+  const relevantError = validator.errors.find(
+    (error) =>
+      error.instancePath.includes("mainsFoulDrainage") &&
+      error.message.includes("offMainsDrainageSystem")
   );
   expect(relevantError).toBeDefined();
 });

package/src/tests/v3/verifiedClaimsValidator.test.js

@@ -126,3 +126,70 @@ test("returns an empty array of errors for verified claim with multiple valid pa
   };
   expect(validateVerifiedClaims([clonedVouch], v3SchemaId, null)).toEqual([]);
 });
+
+test("returns an empty array for valid terms_of_use object with confidential level", () => {
+  const clonedVouch = JSON.parse(JSON.stringify(exampleVouch));
+  clonedVouch.terms_of_use = {
+    confidentiality_level: "confidential",
+    allowed_roles: ["Seller's Conveyancer", "Buyer's Conveyancer"]
+  };
+  expect(validateVerifiedClaims([clonedVouch])).toEqual([]);
+});
+
+test("returns an empty array for valid terms_of_use with public confidentiality", () => {
+  const clonedVouch = JSON.parse(JSON.stringify(exampleVouch));
+  clonedVouch.terms_of_use = {
+    confidentiality_level: "public",
+    allowed_roles: []
+  };
+  expect(validateVerifiedClaims([clonedVouch])).toEqual([]);
+});
+
+test("returns an empty array for valid terms_of_use with restricted level", () => {
+  const clonedVouch = JSON.parse(JSON.stringify(exampleVouch));
+  clonedVouch.terms_of_use = {
+    confidentiality_level: "restricted",
+    allowed_roles: []
+  };
+  expect(validateVerifiedClaims([clonedVouch])).toEqual([]);
+});
+
+test("returns errors for invalid confidentiality_level in terms_of_use", () => {
+  const clonedVouch = JSON.parse(JSON.stringify(exampleVouch));
+  clonedVouch.terms_of_use = {
+    confidentiality_level: "invalid_level",
+    allowed_roles: ["Seller's Conveyancer"]
+  };
+  const errors = validateVerifiedClaims([clonedVouch]);
+  expect(errors).toHaveLength(1);
+  expect(errors[0]).toHaveLength(1);
+  expect(errors[0][0].instancePath).toBe("/verified_claims/0/terms_of_use/confidentiality_level");
+  expect(errors[0][0].keyword).toBe("enum");
+});
+
+test("returns errors for invalid allowed_roles type in terms_of_use", () => {
+  const clonedVouch = JSON.parse(JSON.stringify(exampleVouch));
+  clonedVouch.terms_of_use = {
+    confidentiality_level: "confidential",
+    allowed_roles: "not_an_array"
+  };
+  const errors = validateVerifiedClaims([clonedVouch]);
+  expect(errors).toHaveLength(1);
+  expect(errors[0]).toHaveLength(1);
+  expect(errors[0][0].instancePath).toBe("/verified_claims/0/terms_of_use/allowed_roles");
+  expect(errors[0][0].keyword).toBe("type");
+});
+
+test("returns errors for additional properties in terms_of_use", () => {
+  const clonedVouch = JSON.parse(JSON.stringify(exampleVouch));
+  clonedVouch.terms_of_use = {
+    confidentiality_level: "confidential",
+    allowed_roles: ["Estate Agent"],
+    extra_property: "should_not_be_allowed"
+  };
+  const errors = validateVerifiedClaims([clonedVouch]);
+  expect(errors).toHaveLength(1);
+  expect(errors[0]).toHaveLength(1);
+  expect(errors[0][0].instancePath).toBe("/verified_claims/0/terms_of_use");
+  expect(errors[0][0].keyword).toBe("additionalProperties");
+});