@pdtf/schemas 3.6.0-dev.1 → 3.6.0-dev.11

package/docs/backend-lms-profile-filtering-spec.md

@@ -1,180 +0,0 @@
-# Backend LMS Profile Filtering Spec
-
-## Context
-
-Moverly will consume `@pdtf/schemas@dev` for early access to schema changes, but
-LMS should only receive data shaped to the `pdtf-transaction.json` profile they
-currently support.
-
-This compatibility layer belongs in Moverly backend services because it is an
-integration-boundary concern. The PDTF schema package should not carry
-LMS-specific profile code unless the capability later becomes generic and useful
-to PDTF consumers.
-
-## Target Profile
-
-Initial LMS profile:
-
-- Source: LMS-supplied `pdtf-transaction.json`
-- Profile id: `lms-2026-05-08`
-- Schema id: `https://trust.propdata.org.uk/schemas/v3/pdtf-transaction.json`
-- Raw SHA-256:
-  `5135ffd6158bbe48955ae630cf9cae42ba18f6cd522daed771cd3e44136283d7`
-- Canonical SHA-256:
-  `98aeebe4231557c1aa7bc5182cbb5318d28af32cdcbe3b293feb61dca1e8d6f5`
-
-The LMS profile is not an official PDTF release. It is a pinned recipient
-profile supplied by LMS. When LMS can support an official PDTF release, move the
-target profile to that release artifact instead.
-
-## Configuration
-
-Add a backend environment variable:
-
-```bash
-LMS_PDTF_TARGET_PROFILE=lms-2026-05-08
-```
-
-Behaviour:
-
-- Non-production may default to `lms-2026-05-08`.
-- Production must fail startup or alert loudly if the variable is missing or
-  unknown.
-- Logs and telemetry must include the selected profile id.
-
-## Scope
-
-Apply LMS profile filtering to:
-
-- backend endpoints that expose PDTF transaction data to LMS;
-- webhooks sent to LMS;
-- verified claim payloads included in LMS-facing API responses or webhooks.
-
-Do not apply LMS filtering to:
-
-- stored/source Moverly verified claims;
-- internal Moverly workflows;
-- non-LMS partners;
-- frontend schema rendering, except where frontend displays backend-provided
-  compatibility metadata.
-
-## Filtering Rules
-
-Treat the target profile as closed for outbound LMS payloads, even though PDTF
-schemas generally do not declare `additionalProperties: false`.
-
-For transaction payloads:
-
-1. Build the normal internal Moverly/PDTF payload.
-2. Filter unknown top-level and nested fields against the selected LMS target
-   schema.
-3. Validate the filtered payload against the selected LMS target schema.
-4. Send only the filtered payload.
-
-For verified claims:
-
-1. Iterate each verified claim envelope.
-2. Inspect each `claims` path/value pair independently.
-3. Keep the line item only if:
-   - the path exists in the selected LMS target schema; and
-   - the value validates against that path's subschema.
-4. Drop unsupported or invalid line items.
-5. Preserve the verified claim envelope if at least one line item remains.
-6. Drop the envelope only if all line items are suppressed.
-7. Preserve envelope metadata such as `id`, `transactionId`, `schemaVersion`,
-   `verification`, and `terms_of_use`.
-8. Do not mutate the source verified claim.
-
-Do not map paths or transform values. If a field needs structural mapping, that
-is a separate business/product decision and should not happen implicitly in this
-filtering layer.
-
-## Selective Disclosure Semantics
-
-Suppression means "not disclosed to LMS under this profile".
-
-It does not mean "the seller/source did not assert this". Any backend feature
-answering questions such as "did the seller make an assertion about flooding?"
-must query the source verified claims or explicit suppression metadata, not the
-LMS-filtered payload.
-
-## Suggested Backend Module
-
-Create a small backend-owned module, for example:
-
-```text
-src/integrations/lms/pdtfProfile/
-  lms-2026-05-08/pdtf-transaction.json
-  lms-2026-05-08/metadata.json
-  filterTransactionForProfile.ts
-  filterVerifiedClaimsForProfile.ts
-  profileRegistry.ts
-```
-
-The implementation should:
-
-- load the selected profile by id;
-- verify the pinned file hash in tests;
-- use JSON Schema parsing rather than hand-maintained path allowlists;
-- compile validators with the same AJV draft/settings used for PDTF validation;
-- cache subschema validators by `profileId:path`;
-- return suppression metadata without logging claim values.
-
-## Observability
-
-Record:
-
-- partner: `LMS`;
-- target profile id;
-- profile raw/canonical hash;
-- endpoint or webhook name;
-- transaction id;
-- claim line items before filtering;
-- claim line items after filtering;
-- verified claim envelopes before filtering;
-- verified claim envelopes after filtering;
-- envelopes dropped;
-- unsupported path count;
-- invalid value count;
-- suppressed paths, where safe;
-- validation errors, without sensitive values.
-
-## Tests
-
-Backend tests should cover:
-
-- selected profile id is read from env;
-- unknown production profile id fails loudly;
-- profile metadata hashes match the bundled LMS schema file;
-- transaction filtering removes unknown top-level fields;
-- transaction filtering removes unknown nested fields;
-- filtered transaction validates against the LMS target profile;
-- a field valid in `@pdtf/schemas@dev` but absent from LMS is suppressed;
-- verified claim line items are filtered independently;
-- verified claim envelope metadata is preserved;
-- envelopes are dropped only when all line items are suppressed;
-- source verified claims are not mutated;
-- suppression metadata is returned and contains no claim values.
-
-## Rollout
-
-1. Publish and install `@pdtf/schemas@dev` in Moverly backend.
-2. Add the LMS target profile module and tests.
-3. Set `LMS_PDTF_TARGET_PROFILE=lms-2026-05-08` in non-production.
-4. Run LMS endpoint and webhook regression tests.
-5. Deploy on Monday morning behind normal backend release controls.
-6. Monitor suppression and validation telemetry.
-7. Set the production env var and complete go-live.
-8. Keep the previous behaviour available for rollback until LMS confirms the new
-   payloads are accepted.
-
-## Future Profiles
-
-For a new LMS-supported PDTF release:
-
-1. Add the official released `pdtf-transaction.json` artifact or reference.
-2. Give it a clear profile id, for example `pdtf-3.6.0`.
-3. Add metadata and hash tests.
-4. Update `LMS_PDTF_TARGET_PROFILE`.
-5. Deploy backend and monitor telemetry.
-6. Retain the previous profile until rollback is no longer needed.

package/src/examples/v1/exampleAddParticipantVouch.json

@@ -1,32 +0,0 @@
-{
-  "verification": {
-    "trust_framework": "uk_pdtf",
-    "time": "2022-01-25T13:05:03.108Z",
-    "evidence": [
-      {
-        "type": "vouch",
-        "attestation": {
-          "type": "digital_attestation",
-          "voucher": {
-            "name": "Martin Abode"
-          }
-        },
-        "verification_method": {
-          "type": "auth"
-        }
-      }
-    ]
-  },
-  "claims": {
-    "/participants/-": {
-      "name": {
-        "firstName": "Martin",
-        "lastName": "Abode"
-      },
-      "email": "martin@abode.co.uk",
-      "organisation": "Abode and Floggit Estate Agents",
-      "organisationReference": "MAR/12243/22",
-      "role": "Estate Agent"
-    }
-  }
-}

package/src/examples/v1/exampleDocumentedVouch.json

@@ -1,40 +0,0 @@
-{
-  "verification": {
-    "trust_framework": "uk_pdtf",
-    "time": "2022-01-25T13:16:44.527Z",
-    "evidence": [
-      {
-        "type": "vouch",
-        "attachments": [
-          {
-            "digest": {
-              "alg": "md5",
-              "value": "randomHashValue"
-            },
-            "url": "https://fakeFileStore.com/some/kind/of/file",
-            "desc": "proofOfAddress.pdf",
-            "pdtfSchemaPath": "/propertyPack/materialFacts/councilTax/councilTaxAffectingAlterations/details"
-          }
-        ],
-        "verification_method": {
-          "type": "auth"
-        },
-        "attestation": {
-          "voucher": {
-            "name": "Maria Harris"
-          },
-          "type": "digital_attestation"
-        }
-      }
-    ]
-  },
-  "claims": {
-    "/propertyPack/materialFacts/councilTax": {
-      "councilTaxBand": "D",
-      "councilTaxAffectingAlterations": {
-        "yesNo": "Yes",
-        "details": "Extension added in 2005 to add bedroom with ensuite shower room. Certificate of Compliance issued 17th Feb 2006 and council tax updated"
-      }
-    }
-  }
-}

package/src/examples/v1/exampleElectronicRecord.json

@@ -1,30 +0,0 @@
-{
-  "verification": {
-    "time": "2022-01-25T07:52:14.318Z",
-    "trust_framework": "uk_pdtf",
-    "evidence": [
-      {
-        "type": "electronic_record",
-        "verifier": {
-          "organization": "Property Pack Assembly Software Ltd"
-        },
-        "record": {
-          "source": {
-            "name": "Royal Mail Postcode Address File",
-            "rights": "(c) Royal Mail"
-          },
-          "type": "postcode_address_file"
-        }
-      }
-    ]
-  },
-  "claims": {
-    "/propertyPack/materialFacts/address": {
-      "line1": "3 The Hollys",
-      "line2": "Birtley",
-      "town": "CHESTER LE STREET",
-      "county": "County Durham",
-      "postcode": "DH3 1QN"
-    }
-  }
-}