@pdtf/schemas 3.5.1-3 → 3.5.1-4

package/README.md

@@ -277,6 +277,9 @@ const verifiedClaims = [
         },
       ],
     },
+    terms_of_use: {
+      confidentiality_level: "public",
+    },
     claims: {
       "/propertyPack/priceInformation/price": 350000,
       "/propertyPack/energyEfficiency/epcRating": "C",
@@ -297,6 +300,61 @@ if (errors.length === 0) {
 - **Provenance Tracking** - Each claim includes verification evidence and source attribution
 - **Trust Framework Integration** - Claims operate within the UK PDTF trust framework
 - **Attachment Support** - Supporting documents can be cryptographically linked to claims
+- **Confidentiality Controls** - Terms of use define access levels and permitted recipients
+
+#### Confidentiality Levels
+
+Verified claims support three confidentiality levels through a pdtf-specific extension: a `terms_of_use` field, enabling fine-grained access control:
+
+**Public Data** - Freely accessible data from official sources or public listing information:
+
+```javascript
+{
+  terms_of_use: {
+    confidentiality_level: "public";
+  }
+}
+```
+
+Examples: Land Registry data, Energy Performance Certificates, planning records, council tax information
+
+**Restricted Data** - Limited to transaction participants:
+
+```javascript
+{
+  terms_of_use: {
+    confidentiality_level: "restricted";
+  }
+}
+```
+
+Examples: Commercial property reports, contents of legal forms
+
+**Confidential Data** - Role-based access with explicit authorization:
+
+```javascript
+{
+  terms_of_use: {
+    confidentiality_level: "confidential",
+    allowed_roles: [
+      "Estate Agent",
+      "Seller's Conveyancer",
+      "Buyer's Conveyancer",
+      "Mortgage Broker",
+      "Lender"
+    ]
+  }
+}
+```
+
+Examples: Identity verification reports, anti-money laundering checks, sensitive personal information
+
+**Guidelines:**
+
+- Use **public** for government/official data sources
+- Use **restricted** for commercial data providers and processed information
+- Use **confidential** for sensitive personal data requiring explicit role authorization
+- Always consider data source and sensitivity when assigning levels
 
 **Roadmap - W3C Verifiable Credentials:**
 The next version of the PDTF framework will migrate to [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/) to provide:

package/index.js

@@ -208,9 +208,30 @@ const getCachedSchemaData = (path, schemaId, overlays) => {
     if (pathArray.length >= 1) {
       subSchema = pathArray.reduce((schema, pathElement) => {
         if (!schema) return undefined;
-        const { type, items, properties, oneOf } = schema;
+        const { type, items, properties, patternProperties, oneOf } = schema;
+
+        // Check array type
         if (type === "array") return items;
+
+        // Check explicit properties first
         if (properties?.[pathElement]) return properties[pathElement];
+
+        // Check patternProperties
+        if (patternProperties) {
+          for (const pattern in patternProperties) {
+            try {
+              const regex = new RegExp(pattern);
+              if (regex.test(pathElement)) {
+                return patternProperties[pattern];
+              }
+            } catch (e) {
+              // Invalid regex pattern in schema - skip it
+              console.warn(`Invalid regex pattern in patternProperties: ${pattern}`, e);
+            }
+          }
+        }
+
+        // Check oneOf discriminators
         if (oneOf) {
           let matchingProperty;
           oneOf.forEach((aOneOf) => {
@@ -222,6 +243,7 @@ const getCachedSchemaData = (path, schemaId, overlays) => {
           });
           if (matchingProperty) return matchingProperty;
         }
+
         return undefined;
       }, sourceSchema);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdtf/schemas",
-  "version": "3.5.1-3",
+  "version": "3.5.1-4",
   "description": "Property Data Trust Framework Schemas and Utilities",
   "main": "index.js",
   "directories": {

package/src/examples/v3/exampleAddParticipantVouch.json

@@ -20,6 +20,9 @@
       }
     ]
   },
+  "terms_of_use": {
+    "confidentiality_level": "restricted"
+  },
   "claims": {
     "/participants/-": {
       "name": {

package/src/examples/v3/exampleDocumentedVouch.json

@@ -32,6 +32,9 @@
       }
     ]
   },
+  "terms_of_use": {
+    "confidentiality_level": "public"
+  },
   "claims": {
     "/propertyPack/councilTax": {
       "councilTaxBand": "D",

package/src/examples/v3/exampleElectronicRecord.json

@@ -21,6 +21,9 @@
       }
     ]
   },
+  "terms_of_use": {
+    "confidentiality_level": "public"
+  },
   "claims": {
     "/propertyPack/address": {
       "line1": "3 The Hollys",

package/src/examples/v3/exampleVouch.json

@@ -21,6 +21,9 @@
       }
     ]
   },
+  "terms_of_use": {
+    "confidentiality_level": "restricted"
+  },
   "claims": {
     "/propertyPack/delayFactors/hasDelayFactors": {
       "yesNo": "No"

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

@@ -0,0 +1,569 @@
+const {
+  isPathValid,
+  getSubschema,
+  getSubschemaValidator,
+  validateVerifiedClaims,
+} = require("../../../index.js");
+
+const schemaId =
+  "https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json";
+
+describe("patternProperties support in path validation", () => {
+  describe("isPathValid with patternProperties", () => {
+    test("validates path with patternProperties - simple offer ID", () => {
+      const path = "/offers/offer-123";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("validates path with patternProperties - UUID", () => {
+      const path = "/offers/550e8400-e29b-41d4-a716-446655440000";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("validates path with patternProperties - DID format", () => {
+      const path = "/offers/did:example:buyer123";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("validates path with patternProperties - alphanumeric with special chars", () => {
+      const path = "/offers/1sorzJCFHbWVlHA2tYXA";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("validates nested path within patternProperties", () => {
+      const path = "/offers/offer-456/amount";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("validates deeply nested path within patternProperties", () => {
+      const path = "/offers/offer-456/inclusions";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("rejects invalid nested path within patternProperties", () => {
+      const path = "/offers/offer-456/nonExistentField";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(false);
+    });
+
+    test("validates path with patternProperties exists at root /offers", () => {
+      const path = "/offers";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+  });
+
+  describe("getSubschema with patternProperties", () => {
+    test("returns correct subschema for patternProperties path", () => {
+      const path = "/offers/offer-123";
+      const subschema = getSubschema(path, schemaId);
+
+      expect(subschema).toBeDefined();
+      expect(subschema.type).toBe("object");
+      expect(subschema.properties).toBeDefined();
+      expect(subschema.properties.amount).toBeDefined();
+      expect(subschema.properties.currency).toBeDefined();
+      expect(subschema.properties.status).toBeDefined();
+    });
+
+    test("returns correct subschema for nested property in patternProperties", () => {
+      const path = "/offers/offer-123/amount";
+      const subschema = getSubschema(path, schemaId);
+
+      expect(subschema).toBeDefined();
+      expect(subschema.type).toBe("number");
+      expect(subschema.minimum).toBe(0);
+    });
+
+    test("returns correct subschema for status enum", () => {
+      const path = "/offers/offer-123/status";
+      const subschema = getSubschema(path, schemaId);
+
+      expect(subschema).toBeDefined();
+      expect(subschema.type).toBe("string");
+      expect(subschema.enum).toContain("pending");
+      expect(subschema.enum).toContain("accepted");
+      expect(subschema.enum).toContain("rejected");
+      expect(subschema.enum).toContain("withdrawn");
+      expect(subschema.enum).toContain("noteOfInterest");
+    });
+
+    test("returns correct subschema for currency pattern", () => {
+      const path = "/offers/offer-123/currency";
+      const subschema = getSubschema(path, schemaId);
+
+      expect(subschema).toBeDefined();
+      expect(subschema.type).toBe("string");
+      expect(subschema.pattern).toBe("^[A-Z]{3}$");
+    });
+
+    test("returns offers object schema", () => {
+      const path = "/offers";
+      const subschema = getSubschema(path, schemaId);
+
+      expect(subschema).toBeDefined();
+      expect(subschema.type).toBe("object");
+      expect(subschema.patternProperties).toBeDefined();
+      expect(subschema.propertyNames).toBeDefined();
+    });
+
+    test("returns undefined for invalid path", () => {
+      const path = "/offers/offer-123/invalidField";
+      const subschema = getSubschema(path, schemaId);
+
+      expect(subschema).toBeUndefined();
+    });
+  });
+
+  describe("getSubschemaValidator with patternProperties", () => {
+    test("returns working validator for patternProperties path", () => {
+      const path = "/offers/offer-123";
+      const validator = getSubschemaValidator(path, schemaId);
+
+      expect(validator).toBeDefined();
+      expect(typeof validator).toBe("function");
+
+      const validOffer = {
+        amount: 500000,
+        currency: "GBP",
+        status: "pending",
+      };
+
+      const isValid = validator(validOffer);
+      expect(isValid).toBe(true);
+    });
+
+    test("validator correctly validates valid offer data", () => {
+      const path = "/offers/offer-456";
+      const validator = getSubschemaValidator(path, schemaId);
+
+      const validOffer = {
+        amount: 300000,
+        currency: "EUR",
+        status: "accepted",
+        inclusions: ["carpets", "curtains"],
+        exclusions: ["garden furniture"],
+        conditions: ["Subject to survey"],
+      };
+
+      const isValid = validator(validOffer);
+      expect(isValid).toBe(true);
+    });
+
+    test("validator correctly rejects invalid offer data - missing required field", () => {
+      const path = "/offers/offer-789";
+      const validator = getSubschemaValidator(path, schemaId);
+
+      const invalidOffer = {
+        amount: 400000,
+        currency: "GBP",
+        // missing required status field
+      };
+
+      const isValid = validator(invalidOffer);
+      expect(isValid).toBe(false);
+      expect(validator.errors).toBeDefined();
+      expect(validator.errors.length).toBeGreaterThan(0);
+    });
+
+    test("validator correctly rejects invalid offer data - negative amount", () => {
+      const path = "/offers/offer-999";
+      const validator = getSubschemaValidator(path, schemaId);
+
+      const invalidOffer = {
+        amount: -100000,
+        currency: "GBP",
+        status: "pending",
+      };
+
+      const isValid = validator(invalidOffer);
+      expect(isValid).toBe(false);
+      expect(validator.errors.some((e) => e.keyword === "minimum")).toBe(true);
+    });
+
+    test("validator correctly rejects invalid offer data - invalid status", () => {
+      const path = "/offers/offer-abc";
+      const validator = getSubschemaValidator(path, schemaId);
+
+      const invalidOffer = {
+        amount: 250000,
+        currency: "GBP",
+        status: "invalid-status",
+      };
+
+      const isValid = validator(invalidOffer);
+      expect(isValid).toBe(false);
+      expect(validator.errors.some((e) => e.keyword === "enum")).toBe(true);
+    });
+
+    test("validator for nested path works correctly", () => {
+      const path = "/offers/offer-nested/amount";
+      const validator = getSubschemaValidator(path, schemaId);
+
+      expect(validator(500000)).toBe(true);
+      expect(validator(0)).toBe(true);
+      expect(validator(-1)).toBe(false);
+      expect(validator("not a number")).toBe(false);
+    });
+  });
+
+  describe("validateVerifiedClaims with patternProperties paths", () => {
+    test("accepts valid claim with patternProperties path", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-001": {
+            amount: 500000,
+            currency: "GBP",
+            status: "pending",
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors).toHaveLength(0);
+    });
+
+    test("accepts valid claim with UUID offer ID", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/1sorzJCFHbWVlHA2tYXA": {
+            amount: 750000,
+            currency: "GBP",
+            status: "accepted",
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors).toHaveLength(0);
+    });
+
+    test("accepts valid claim with DID format offer ID", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/did:example:buyer123": {
+            amount: 600000,
+            currency: "EUR",
+            status: "noteOfInterest",
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors).toHaveLength(0);
+    });
+
+    test("accepts valid claim with nested patternProperties path", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-002/amount": 450000,
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors).toHaveLength(0);
+    });
+
+    test("accepts claim with all optional offer fields", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-complete": {
+            amount: 550000,
+            currency: "GBP",
+            status: "accepted",
+            inclusions: ["carpets", "curtains", "light fixtures"],
+            exclusions: ["garden shed"],
+            conditions: ["Subject to survey", "Subject to mortgage approval"],
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors).toHaveLength(0);
+    });
+
+    test("rejects claim with invalid offer data - missing required field", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-invalid": {
+            amount: 500000,
+            currency: "GBP",
+            // missing required status field
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+
+    test("rejects claim with invalid offer data - negative amount", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-negative": {
+            amount: -100000,
+            currency: "GBP",
+            status: "pending",
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+
+    test("rejects claim with invalid offer data - invalid status enum", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-bad-status": {
+            amount: 500000,
+            currency: "GBP",
+            status: "completed", // not a valid enum value
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+
+    test("rejects claim with invalid offer data - invalid currency format", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-bad-currency": {
+            amount: 500000,
+            currency: "gbp", // should be uppercase
+            status: "pending",
+          },
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors.length).toBeGreaterThan(0);
+    });
+
+    test("accepts multiple claims with different patternProperties paths", () => {
+      const claims = [
+        {
+          timestamp: 1643115903108,
+          verification: {
+            trust_framework: "uk_pdtf",
+            time: "2025-01-15T12:00:00Z",
+          },
+          claims: {
+            "/offers/offer-1": {
+              amount: 500000,
+              currency: "GBP",
+              status: "pending",
+            },
+          },
+        },
+        {
+          timestamp: 1643115903109,
+          verification: {
+            trust_framework: "uk_pdtf",
+            time: "2025-01-15T12:01:00Z",
+          },
+          claims: {
+            "/offers/offer-2": {
+              amount: 520000,
+              currency: "GBP",
+              status: "accepted",
+            },
+          },
+        },
+      ];
+
+      const errors = validateVerifiedClaims(claims, schemaId);
+      expect(errors).toHaveLength(0);
+    });
+
+    test("accepts claim with multiple patternProperties paths", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-1": {
+            amount: 500000,
+            currency: "GBP",
+            status: "pending",
+          },
+          "/offers/offer-2": {
+            amount: 510000,
+            currency: "GBP",
+            status: "withdrawn",
+          },
+          "/offers/offer-3/status": "rejected",
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors).toHaveLength(0);
+    });
+
+    test("rejects claim for non-existent nested property in patternProperties", () => {
+      const claim = {
+        timestamp: 1643115903108,
+        verification: {
+          trust_framework: "uk_pdtf",
+          time: "2025-01-15T12:00:00Z",
+        },
+        claims: {
+          "/offers/offer-1/nonExistentField": "some value",
+        },
+      };
+
+      const errors = validateVerifiedClaims([claim], schemaId);
+      expect(errors.length).toBeGreaterThan(0);
+      expect(errors.some((e) => e.includes("not a valid PDTF schema path"))).toBe(
+        true
+      );
+    });
+  });
+
+  describe("precedence: explicit properties over patternProperties", () => {
+    // This test documents the expected behavior that explicit properties
+    // should take precedence over patternProperties matches
+    test("explicit property should match before patternProperties", () => {
+      // If offers had an explicit property called "special" and also had
+      // patternProperties that would match "special", the explicit property
+      // should win. This is standard JSON Schema behavior.
+
+      // Since our current schema doesn't have this scenario, this test
+      // documents the expected behavior for future schema changes
+      expect(true).toBe(true);
+    });
+  });
+
+  describe("caching with patternProperties paths", () => {
+    test("caches subschema for patternProperties paths", () => {
+      const path = "/offers/cached-offer-123";
+
+      // First call - cache miss
+      const subschema1 = getSubschema(path, schemaId);
+      expect(subschema1).toBeDefined();
+
+      // Second call - should hit cache
+      const subschema2 = getSubschema(path, schemaId);
+      expect(subschema2).toBeDefined();
+      expect(subschema2).toEqual(subschema1);
+    });
+
+    test("caches validator for patternProperties paths", () => {
+      const path = "/offers/cached-offer-456";
+
+      // First call - cache miss
+      const validator1 = getSubschemaValidator(path, schemaId);
+      expect(validator1).toBeDefined();
+
+      // Second call - should hit cache
+      const validator2 = getSubschemaValidator(path, schemaId);
+      expect(validator2).toBeDefined();
+
+      // Should be the same validator function
+      expect(validator2).toBe(validator1);
+    });
+
+    test("different patternProperties paths get separate cache entries", () => {
+      const path1 = "/offers/offer-aaa";
+      const path2 = "/offers/offer-bbb";
+
+      const validator1 = getSubschemaValidator(path1, schemaId);
+      const validator2 = getSubschemaValidator(path2, schemaId);
+
+      // Both should work but point to same schema (since they match same pattern)
+      expect(validator1).toBeDefined();
+      expect(validator2).toBeDefined();
+
+      // They should be the same since they resolve to the same schema
+      expect(validator1).toBe(validator2);
+    });
+  });
+
+  describe("edge cases", () => {
+    test("handles offer ID with dots", () => {
+      const path = "/offers/offer.123.abc";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("handles offer ID with underscores", () => {
+      const path = "/offers/offer_123_abc";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("handles offer ID with colons (DID format)", () => {
+      const path = "/offers/did:web:example.com:users:alice";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("handles offer ID with plus signs", () => {
+      const path = "/offers/offer+123";
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+
+    test("handles very long offer ID", () => {
+      const longId = "a".repeat(100);
+      const path = `/offers/${longId}`;
+      const isValid = isPathValid(path, schemaId);
+      expect(isValid).toBe(true);
+    });
+  });
+});